异步文档处理API

2025-11-19 06:57

RealDoc支持异步文档处理，目前异步接口支持异步文档解析和异步文档防伪。

重要提示

在上传文档API中，fileContent与fileUrl参数必须传入其中一个。
如果商户没有可用配额，则会返回PRODUCT_NOT_AVAILABLE错误。
异步处理任务只要处理成功，无论是否查询结果都会计费。
任务提交成功后，建议先使用查询任务状态API轮询任务状态，任务状态为Success时再查询结果。
仅当任务状态为Success时，才会返回具体的处理结果。
部分API存在速率限制，如遇限流请联系ZOLOZ技术支持。

通用请求参数

所有API请求均使用HTTP POST方法，Content-Type为application/json。

字段名称

数据类型

描述

bizId

String

商户的业务ID，最大长度为64，用于区分不同的请求或任务。

请勿重复使用相同的bizId，以避免任务状态或结果查询混淆。

上传文档

API路径

POST /api/v1/zoloz/realdoc/async/upload

API描述

该接口用于异步处理文档，支持文档防伪检测和文档信息提取。

请求参数

字段名称	数据类型	是否必填	默认值	描述	示例值
bizId	String	是	-	商户的业务ID，用于区分不同的请求或任务。	20230601001
productType	String	是	-	产品类型。取值： `REALDOC_FORGERY_DETECTION`：文档防伪检测 `REALDOC_DOCUMENT_EXTRACTION`：文档信息提取	REALDOC_DOCUMENT_EXTRACTION
fileType	String	否	null	指定文件类型。支持的文件类型包括：pdf、jpg、jpeg、png、webp、bmp、tiff。	pdf
schemaId	String	否	null	文档解析模板ID，仅当`productType`设置为`REALDOC_DOCUMENT_EXTRACTION`时需要传入。取值： `companies_registry_v1`：公司注册证明 `business_registration_certificate_v1`：商业登记证明 `invoice_v1`：发票 `receipt_v1`：收据 `bank_statement_v1`：银行对账单 `mys_birth_certificate_v1`：马来西亚出生证明	bank_statement_v1
fileContent	String	否	null	待解析或检测的文档文件，需经过Base64编码后传入，文件大小最大为10MB。	/9j/4AAQSkZJRgABAQAAlgCWAAD/4QCARXhpZgAA
fileUrl	String	否	null	待解析或检测的文件URL地址。说明：`fileUrl`与`fileContent`必须传入一个，如果同时传入，则优先使用`fileUrl`。	https://example.com/file.pdf

返回参数

字段名称

数据类型

描述

示例值

transactionId

String

ZOLOZ返回的事务ID，用于查询任务状态和结果。

R00000020250926155511ff792165

result

Result

API请求结果，包含结果状态、结果码和结果信息。

{

"resultStatus": "S",

"resultCode": "SUCCESS",

"resultMessage": "Success"

}

请求示例

copy
{
    "bizId": "20230601001", 
    "productType": "REALDOC_DOCUMENT_EXTRACTION", 
    "fileType": "pdf", 
    "fileContent": "/9j/4AAQSkZJRgABAQAAlgCWAAD/4QCARXhpZgAA", 
    "schemaId": "bank_statement_v1"
}

返回示例

copy
{
    "result": {
        "resultStatus": "S", 
        "resultCode": "SUCCESS", 
        "resultMessage": "Success"
    }, 
    "transactionId": "R00000020250926155511ff792165"
}

查询任务状态

API路径

POST /api/v1/zoloz/realdoc/async/status

API描述

该接口用于查询异步任务的执行状态。

请求参数

字段名称	数据类型	是否必填	默认值	描述	示例值
bizId	String	是	-	商户的业务ID，用于区分不同的请求或任务。	20230601001
transactionId	String	是	-	上传文档接口返回的事务ID。	R00000020250926155511ff792165

返回参数

字段名称	数据类型	描述	示例值
result	Result	API请求结果，包含结果状态、结果码和结果信息。	{ "resultStatus": "S", "resultCode": "SUCCESS", "resultMessage": "Success" }
transactionId	String	ZOLOZ返回的事务ID。	R000000202509261556320d7d1c44
status	String	任务状态。 `Processing`：任务正在处理中 `Success`：任务执行成功 `Failure`：任务执行失败	Processing

请求示例

copy
{
    "bizId": "20230601001", 
    "transactionId": "R00000020250926155511ff792165"
}

返回示例

copy
{
    "result": {
        "resultStatus": "S", 
        "resultCode": "SUCCESS", 
        "resultMessage": "Success"
    }, 
    "transactionId": "R000000202509261556320d7d1c44", 
    "status": "Processing"
}

获取文档解析结果

API路径

POST /api/v1/zoloz/realdoc/async/documentparse/result

API描述

该接口用于获取异步文档解析结果，返回格式与同步文档解析API相同。

请求参数

字段名称	数据类型	是否必填	默认值	描述	示例值
bizId	String	是	-	商户的业务ID，用于区分不同的请求或任务。	20230601001
transactionId	String	是	-	上传文档接口返回的事务ID。	R000000202510111032563d0e515f

返回参数

字段名称	数据类型	描述	示例值
result	Result	API请求结果，包含结果状态、结果码和结果信息。	{ "resultStatus": "S", "resultCode": "SUCCESS", "resultMessage": "Success" }
transactionId	String	ZOLOZ返回的事务ID。	R00000020250926155511ff792165
data	Map<String, Object>	文档提取结果，不同`schemaId`对应的结果有所不同。	参考返回示例

请求示例

copy
{
  "bizId": "20230601001",
  "transactionId": "R000000202510111032563d0e515f"
}

返回示例

copy
{
    "result": {
        "resultStatus": "S", 
        "resultCode": "SUCCESS", 
        "resultMessage": "Success"
    }, 
    "data": {
        "account_holders_name": "MS. IxxG", 
        "account_number": "91802xxxxx04", 
        "bank_name": "AXIS BANK", 
        "starting_balance": "47315.01", 
        "ending_balance": "115368.01", 
        "deposits_and_credits": "372700.00", 
        "withdrawals_and_debits": "304647.00", 
        "scheme_code": "CA- LARGE RETAILERS AND DISTRIBUTORS", 
        "customer_id": "88xxx0", 
        "currency": "INR", 
        "lien_amount": "0.00", 
        "nomination_details": "NOMINATION REGISTERED", 
        "PIN": "11xxx1", 
        "details": [
            {
                "date": "10/04/2019", 
                "description": "MOB/SELFFT/SURJEET SINGH/9130100", 
                "balance": "315.01"
            }, 
            {
                "date": "13/04/2019", 
                "description": "GST @18% on Charge", 
                "balance": "2028.81"
            }
        ]
    }, 
    "transactionId": "R000000202510111032563d0e515f"
}

获取文档防伪检测结果

API路径

POST /api/v1/zoloz/realdoc/async/fraudcheck/result

API描述

该接口用于获取异步文档防伪检测结果。

请求参数

字段名称	数据类型	是否必填	默认值	描述	示例值
bizId	String	是	-	商户的业务ID，用于区分不同的请求或任务。	20230601001
transactionId	String	是	-	上传文档接口返回的事务ID。	R00000020251011103904dd53c8ff

返回参数

字段名称	数据类型	描述	示例值
result	Result	API请求结果，包含结果状态、结果码和结果信息。	{ "resultStatus": "S", "resultCode": "SUCCESS", "resultMessage": "Success" }
transactionId	String	ZOLOZ返回的事务ID。	R00000020251020115123c7c15c40
summary	Summary	防伪检测结果明细。	参考返回示例
tamperInfo	List<TamperInfo>	文档篡改详情，仅当检测到文档被篡改时才返回该参数。	参考返回示例

Summary字段说明

字段名称	数据类型	描述	示例值
overallRiskScore	Double	整体风险评分，取值范围为0-100。分值越高，表示文档被篡改或伪造的风险越大。	95
executiveSummary	String	检测结果摘要。针对风险评分较高的文档，将返回具体的风险信息。	""

TamperInfo字段说明

字段名称	数据类型	描述	示例值
content	String	文档被篡改区域的内容。	"Customer Name"
location	Integer[]	篡改区域的坐标位置，格式为[x1, y1, x2, y2]，表示被篡改内容的边界框。	[ 280, 159, 451, 175 ]
explanation	String	篡改检测说明。	"The black block covering the text `Customer Name`."

请求示例

copy
{
    "bizId": "20230601001", 
    "transactionId": "R00000020251011103904dd53c8ff"
}

返回示例

正常案例

copy
{
    "result": {
        "resultStatus": "S", 
        "resultCode": "SUCCESS", 
        "resultMessage": "Success"
    }, 
    "summary": {
        "overallRiskScore": 5, 
        "executiveSummary": "Based on the comprehensive visual and logical analysis, no evidence of digital forgery or malicious alteration was found. All examined regions of the document, including the dates, price, names, and official seal, are consistent with the characteristics of an authentically generated official document. Therefore, no forged locations have been identified."
    }, 
    "transactionId": "R000000202510111040423dc6af95"
}

篡改案例

copy
{
    "result": {
        "resultCode": "SUCCESS", 
        "resultStatus": "S", 
        "resultMessage": "Success"
    }, 
    "transactionId": "R00000020251020115123c7c15c40", 
    "summary": {
        "overallRiskScore": 95, 
        "executiveSummary": "Despite internal consistency and high template quality, the document exhibits deliberate tampering through malicious obscuration of critical identifying information (Customer Name and Correspondence Address) using black blocks, indicating a high likelihood of forgery."
    }, 
    "tamperInfo": [
        {
            "content": "Customer Name", 
            "location": [
                280, 
                159, 
                451, 
                175
            ], 
            "explanation": "The black block covering the text `Customer Name`."
        }, 
        {
            "content": "Correspondence Address", 
            "location": [
                62, 
                183, 
                491, 
                215
            ], 
            "explanation": "The black blocks covering the `Correspondence Address`."
        }
    ]
}