异步文档处理API

2026-06-02 09:45

重要说明：

所有请求及返回参数均严格以官网API文档为准。
API返回结果中可能包含未在文档中定义的字段。这些字段仅供内部调试使用，不保证稳定性及兼容性，请勿在生产环境中依赖这些字段，ZOLOZ保留随时修改或删除这些字段的权利，且无需另行通知。

RealDoc提供异步文档处理能力，当前支持以下功能：

文档信息提取
文档防伪检测
文档洞察
文档交叉比对
文档解析（Markdown）

重要提示

文档上传方式

在“上传文档”API中，除交叉比对场景外，fileContent与fileUrl必须传入一个；同时传入时优先使用fileUrl。
交叉比对场景下，需要在documents中传入两个待比对文档，每个文档的fileContent与fileUrl参数必须二选一传入。

配额限制
如果商户没有可用配额，则会返回PRODUCT_NOT_AVAILABLE错误。
计费说明
异步任务只要处理成功，无论是否查询结果都会计费。
任务处理流程

任务提交成功后，建议先通过“查询任务状态”API轮询任务状态，任务状态为Success时再查询结果。
当任务状态为Success时，系统将返回具体的处理结果。当任务状态为Failure时，系统将返回失败原因，具体请查看返回的resultMessage字段，并根据提示信息定位问题。

速率限制
部分API存在速率限制，如遇限流请联系ZOLOZ技术支持。

通用请求参数

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

字段名称

数据类型

描述

bizId

String

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

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

上传文档

API路径

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

API描述

该接口用于提交异步文档处理任务。任务提交成功后，可通过返回的transactionId查询任务状态和对应处理结果。

请求参数

字段名称	数据类型	是否必填	默认值	描述	示例值
bizId	String	是	-	商户的业务ID，用于区分不同的请求或任务。	20230601001
productType	String	是	-	产品类型。取值： `REALDOC_FORGERY_DETECTION`：文档防伪检测 `REALDOC_DOCUMENT_EXTRACTION`：文档信息提取 `REALDOC_DOCUMENT_INSIGHT`：文档洞察 `REALDOC_CROSS_MATCHING`：文档交叉比对 `REALDOC_DOCUMENT_PARSING`：文档解析（Markdown）	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。说明：除交叉比对场景外，`fileContent`与`fileUrl`必须传入一个；同时传入时优先使用`fileUrl`。	/9j/4AAQSkZJRgABAQAAlgCWAAD/4QCARXhpZgAA
fileUrl	String	否	null	待处理的文件URL地址。说明：除交叉比对场景外，`fileContent`与`fileUrl`必须传入一个；同时传入时优先使用`fileUrl`。	https://example.com/file.pdf
documents	List	否	null	交叉比对场景下使用的文档列表。当`productType`为`REALDOC_CROSS_MATCHING`时必填，且必须传入2个文档。	[ { "fileType": "pdf", "fileUrl": "https://example.com/file-a.pdf" }, { "fileType": "pdf", "fileUrl": "https://example.com/file-b.pdf" } ]

Document字段说明

字段名称	数据类型	是否必填	默认值	描述	示例值
fileType	String	否	null	指定文件类型。支持的文件类型包括：pdf、jpg、jpeg、png、webp、bmp、tiff。	pdf
fileContent	String	否	null	待比对文档文件，需经过Base64编码后传入，文件大小最大为10MB。说明：`fileContent`与`fileUrl`必须传入一个。	/9j/4AAQSkZJRgABAQAAlgCWAAD/4QCARXhpZgAA
fileUrl	String	否	null	待比对文件URL地址。说明：`fileContent`与`fileUrl`必须传入一个。	https://example.com/file-a.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
{
    "bizId": "20230601002", 
    "productType": "REALDOC_DOCUMENT_INSIGHT", 
    "fileType": "pdf", 
    "fileUrl": "https://example.com/document.pdf", 
    "schemaId": "general_insight_v1"
}

文档交叉比对：

copy
{
    "bizId": "20230601003", 
    "productType": "REALDOC_CROSS_MATCHING", 
    "schemaId": "general_cross_matching_v1", 
    "documents": [
        {
            "fileType": "pdf", 
            "fileUrl": "https://example.com/file-a.pdf"
        }, 
        {
            "fileType": "pdf", 
            "fileUrl": "https://example.com/file-b.pdf"
        }
    ]
}

文档解析（Markdown）：

copy
{
    "bizId": "20230601004", 
    "productType": "REALDOC_DOCUMENT_PARSING", 
    "fileType": "pdf", 
    "fileUrl": "https://example.com/document.pdf", 
    "schemaId": "general_text_parsing_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/documentinsight/result

API描述

该接口用于获取异步文档洞察结果。文档洞察用于对文档进行综合分析，并返回风险评分、摘要说明、洞察明细，以及可能存在的风险位置明细。

请求参数

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

返回参数

字段名称	数据类型	描述	示例值
result	Result	API请求结果，包含结果状态、结果码和结果信息。	{ "resultStatus": "S", "resultCode": "SUCCESS", "resultMessage": "Success" }
transactionId	String	ZOLOZ返回的事务ID。	R00000020251011105012a1b2c3d4
summary	Summary	文档洞察结果摘要。	参考返回示例
tamperInfo	List	风险或篡改位置详情，仅当检测到相关风险时返回。	参考返回示例

Summary字段说明

字段名称	数据类型	描述	示例值
overallRiskScore	Double	整体风险评分，取值范围为0-100。分值越高文档风险越大。	82
executiveSummary	String	洞察结果摘要。	The document shows several risk indicators.
insightInfo	String	洞察详细信息。	The invoice amount and tax section require manual review.

TamperInfo字段说明

字段名称	数据类型	描述	示例值
content	String	风险或篡改区域的内容。	Invoice Amount
location	Double[]	风险或篡改区域的边界框坐标，格式为[x1, y1, x2, y2]。	[ 0.365, 0.281, 0.582, 0.318 ]
explanation	String	风险或篡改检测说明。	The amount field is inconsistent with the tax details.
page	Integer	风险或篡改位置所在页。	1

请求示例

copy
{
    "bizId": "20230601002", 
    "transactionId": "R00000020251011105012a1b2c3d4"
}

返回示例

copy
{
    "result": {
        "resultStatus": "S", 
        "resultCode": "SUCCESS", 
        "resultMessage": "Success"
    }, 
    "transactionId": "R00000020251011105012a1b2c3d4", 
    "summary": {
        "overallRiskScore": 82, 
        "executiveSummary": "The document shows several risk indicators and should be reviewed manually.", 
        "insightInfo": "The invoice amount and tax section require manual review."
    }, 
    "tamperInfo": [
        {
            "content": "Invoice Amount", 
            "location": [
                0.365, 
                0.281, 
                0.582, 
                0.318
            ], 
            "explanation": "The amount field is inconsistent with the tax details.", 
            "page": 1
        }
    ]
}

获取文档防伪检测结果

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	Double	篡改区域的坐标位置，格式为[x1, y1, x2, y2]，表示被篡改内容的边界框。	[ 0.865, 0.281, 0.882, 0.318 ]
explanation	String	篡改检测说明。	"The black block covering the text `Customer Name`."
page	Integer	篡改位置所在页。	1

请求示例

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": "5", 
            "explanation": "The digit '5' in the 'Invoice Date' field exhibits font and rendering inconsistency, appearing marginally bolder with different sharpness and anti-aliasing. A subtle background halo around it suggests a copy-paste operation.", 
            "location": [
                0.865, 
                0.281, 
                0.882, 
                0.318
            ], 
            "page": 1
        }
    ]
}

获取文档交叉比对结果

API路径

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

API描述

该接口用于获取异步文档交叉比对结果。交叉比对用于比较两个文档中的关键信息是否一致，并返回整体匹配结果、匹配分数和字段级比对明细。

请求参数

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

返回参数

字段名称	数据类型	描述	示例值
result	Result	API请求结果，包含结果状态、结果码和结果信息。	{ "resultStatus": "S", "resultCode": "SUCCESS", "resultMessage": "Success" }
transactionId	String	ZOLOZ返回的事务ID。	R00000020251011110012e5f6g7h8
overallMatchResult	String	整体匹配结果，例如`True`、`False`、`None`。	True
overallMatchScore	Double	整体匹配分数，取值范围为0-100。	92.5
executiveSummary	String	匹配结果摘要。	High similarity detected.
matchingInfo	List	字段级匹配明细。	参考MatchInfo字段说明。

MatchInfo字段说明

字段名称	数据类型	描述	示例值
field	String	比对字段名称。	address
value1	String	第一个文档中的字段值。	123 Main St
value2	String	第二个文档中的字段值。	123 Main St
explanation	String	字段匹配说明。	Address matches exactly.

请求示例

copy
{
    "bizId": "20230601003", 
    "transactionId": "R00000020251011110012e5f6g7h8"
}

返回示例

copy
{
    "result": {
        "resultStatus": "S", 
        "resultCode": "SUCCESS", 
        "resultMessage": "Success"
    }, 
    "transactionId": "R00000020251011110012e5f6g7h8", 
    "overallMatchResult": "True", 
    "overallMatchScore": 92.5, 
    "executiveSummary": "High similarity detected between the two documents.", 
    "matchingInfo": [
        {
            "field": "address", 
            "value1": "123 Main St", 
            "value2": "123 Main St", 
            "explanation": "Address matches exactly."
        }, 
        {
            "field": "company_name", 
            "value1": "Example Trading Ltd.", 
            "value2": "Example Trading Limited", 
            "explanation": "Company names are semantically equivalent."
        }
    ]
}

获取文档解析（Markdown）结果

API路径

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

API描述

该接口用于获取异步文档解析（Markdown）结果。文档解析会将文档内容转换为结构化文本或Markdown内容，返回格式与文档解析响应模型一致，具体data内容由解析模板和文档内容共同决定。

请求参数

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

返回参数

字段名称	数据类型	描述	示例值
result	Result	API请求结果，包含结果状态、结果码和结果信息。	{ "resultStatus": "S", "resultCode": "SUCCESS", "resultMessage": "Success" }
transactionId	String	ZOLOZ返回的事务ID。	R00000020251011112012i9j0k1l2
data	Map<String, Object>	文档解析结果。通常包含Markdown文本、章节、表格或摘要等信息，具体返回字段以解析模板为准。	参考返回示例

请求示例

copy
{
    "bizId": "20230601004", 
    "transactionId": "R00000020251011112012i9j0k1l2"
}

返回示例

copy
{
    "result": {
        "resultStatus": "S", 
        "resultCode": "SUCCESS", 
        "resultMessage": "Success"
    }, 
    "data": {
        "markdown_base64": "base64content"
    }, 
    "transactionId": "R00000020251011112012i9j0k1l2"
}