Async API Documentation
1. Overview
AsyncProcessController provides asynchronous processing interfaces for RealDoc records, including document upload, task status query, and result retrieval for document parsing and forgery detection operations.
2. Common Parameters
2.1 Request Common Parameters
All interface requests use HTTP POST method with Content-Type: application/json.
Field Name | Type | Description |
bizId | String | business id max is 64 |
2.2 Response Common Parameters
All interface responses contain the following common fields:
Field Name | Type | Description |
result | Result Object | Response result |
transactionId | String | Transaction ID |
Result Object Structure
Field Name | Type | Description |
resultCode | String | Result code |
resultMessage | String | Result message |
resultStatus | String | Result status, " |
3. API List
3.1 Asynchronous Document Upload Interface
API Path
POST /api/v1/zoloz/realdoc/async/upload
Description
Used for asynchronous document processing, supporting both document forgery detection and document extraction types.
Request Parameters
Parameter Name | Type | Required | Description | Example Value |
bizId | String | Yes | Business ID | 20230601001 |
productType | String | Yes | Product type |
|
fileType | String | No | File type (pdf, jpg, png, etc.) | |
schemaId | String | No | Schema ID for document validation rules if |
|
fileContent | String | No | Document file to parse. Maximum size: 10 MB. | base64_encoded_content |
fileUrl | String | No | File URL address. Either |
Response Parameters
Field Name | Type | Description |
transactionId | String | Transaction ID |
result | Result Object | Response result |
Request Example
{
"bizId": "20230601001",
"productType": "REALDOC_DOCUMENT_EXTRACTION",
"fileType": "PDF",
"fileContent": "base64_encoded_file_content",
"schemaId": "general_text_parsing_v1"
}Response Example
{
"result": {
"resultStatus": "S",
"resultCode": "SUCCESS",
"resultMessage": "Success"
},
"transactionId": "R00000020250926155511ff792165"
}3.2 Task Status Query Interface
API Path
POST /api/v1/zoloz/realdoc/async/status
Description
Used to query the execution status of asynchronous tasks.
Request Parameters
Parameter Name | Type | Required | Description | Example Value |
bizId | String | Yes | Business ID | 20230601001 |
transactionId | String | Yes | Transaction ID returned from upload interface | R00000020250926155511ff792165 |
Response Parameters
Field Name | Type | Description |
result | Result Object | Response result |
transactionId | String | Transaction ID |
status | String | Task status (Processing, Success, Failure) |
Request Example
{
"bizId": "20230601001",
"transactionId": "R-1234567890abcdef"
}Response Example
{
"result": {
"resultStatus": "S",
"resultCode": "SUCCESS",
"resultMessage": "Success"
},
"transactionId": "R000000202509261556320d7d1c44",
"status": "Processing"
}3.3 Document Parsing Async Result Query Interface
API Path
POST /api/v1/zoloz/realdoc/async/documentparse/result
Description
Used to query the results of asynchronous document parsing, returning the same response format as the synchronous interface.
Request Parameters
Parameter Name | Type | Required | Description | Example Value |
bizId | String | Yes | Business ID | 20230601001 |
transactionId | String | Yes | Transaction ID returned from upload interface | R000000202510111032563d0e515f |
Response Parameters
Field Name | Type | Description |
result | Result Object | Response result |
transactionId | String | Transaction ID |
data | Map<String, Object> | Extracted information in string format |
Request Example
{
"bizId": "20230601001",
"transactionId": "R000000202510111032563d0e515f"
}Response Example
{
"result": {
"resultCode": "SUCCESS",
"resultStatus": "S",
"resultMessage": "Success"
},
"data": {
"raw_text": [
{
"bbox": [
200,
29,
283,
128
],
"text": "Invoice Number:25312000000203196905"
},
{
"bbox": [
201,
310,
269,
642
],
"text": "Electronic Invoice (General Invoice)"
},
{
"bbox": [
250,
737,
266,
915
],
"text": "Invoice Date: June 30, 2025"
},
{
"bbox": [
327,
535,
344,
767
],
"text": "Name: Shanghai Liulishuo Information Technology Co., Ltd."
},
{
"bbox": [
328,
70,
345,
126
],
"text": "Name: Individual"
},
{
"bbox": [
363,
506,
404,
521
],
"text": "Seller Information"
},
{
"bbox": [
364,
29,
404,
43
],
"text": "Buyer Information"
},
{
"bbox": [
376,
535,
394,
951
],
"text": "Unified Social Credit Code/Tax Identification Number:913101100693054787"
},
{
"bbox": [
378,
54,
394,
253
],
"text": "Unified Social Credit Code/Tax Identification Number:"
},
{
"bbox": [
418,
953,
434,
968
],
"text": "Tax Amount"
},
{
"bbox": [
419,
747,
435,
829
],
"text": "Tax Rate/Levy Rate"
},
{
"bbox": [
419,
680,
435,
726
],
"text": "Amount"
},
{
"bbox": [
419,
587,
435,
602
],
"text": "Price"
},
{
"bbox": [
419,
465,
435,
480
],
"text": "Quantity"
},
{
"bbox": [
419,
319,
435,
349
],
"text": "Unit"
},
{
"bbox": [
420,
201,
436,
257
],
"text": "Specification Model"
},
{
"bbox": [
420,
77,
436,
133
],
"text": "Item Name"
},
{
"bbox": [
438,
558,
454,
604
],
"text": "977.36"
},
{
"bbox": [
438,
680,
454,
726
],
"text": "977.36"
},
{
"bbox": [
438,
938,
454,
977
],
"text": "58.64"
},
{
"bbox": [
439,
477,
455,
485
],
"text": "1"
},
{
"bbox": [
439,
783,
455,
796
],
"text": "6%"
},
{
"bbox": [
439,
29,
475,
187
],
"text": "*R&D and Technical Services* Liulishuo English Software Service Fee"
},
{
"bbox": [
604,
929,
622,
976
],
"text": "¥58.64"
},
{
"bbox": [
605,
673,
621,
728
],
"text": "¥977.36"
},
{
"bbox": [
606,
95,
622,
110
],
"text": "Sub"
},
{
"bbox": [
606,
172,
621,
187
],
"text": "total"
},
{
"bbox": [
633,
689,
652,
812
],
"text": "(Subtotal)¥1036.00"
},
{
"bbox": [
634,
53,
653,
202
],
"text": "Total Amount (Capitalized)"
},
{
"bbox": [
634,
301,
652,
442
],
"text": "One Thousand Thirty-Six Yuan Only"
},
{
"bbox": [
672,
44,
688,
70
],
"text": "Remarks"
},
{
"bbox": [
784,
94,
800,
188
],
"text": "Invoice Issuer: Luo Rongrong"
}
]
},
"transactionId": "R00000020251020113034d099e3a4"
}3.4 Document Forgery Detection Async Result Query Interface
API Path
POST /api/v1/zoloz/realdoc/async/fraudcheck/result
Description
Used to query the results of asynchronous document forgery detection, returning the same response format as the synchronous interface.
Request Parameters
Parameter Name | Type | Required | Description | Example Value |
bizId | String | Yes | Business ID | 20230601001 |
transactionId | String | Yes | Transaction ID returned from upload interface | R-1234567890abcdef |
Response Parameters
Field Name | Type | Description |
result | Result Object | Response result |
transactionId | String | Transaction ID |
summary | Summary Object | Forgery detection result summary |
Summary Object Structure
Field Name | Type | Description |
overallRiskScore | Double | Overall risk score (0-100) |
executiveSummary | String | Executive summary of results |
tamperInfo | List<TamperInfo> | Possible tampering of information |
TamperInfo Object Structure
Field Name | Type | Description |
content | String | Content of the tampered area |
location | Integer[] | Location coordinates [x1, y1, x2, y2], represents the bounding box of the tampered content |
explanation | String | Explanation of the tampering detection |
Request Example
{
"bizId": "20230601001",
"transactionId": "R00000020251011103904dd53c8ff"
}Response Example
Normal case
{
"result": {
"resultStatus": "S",
"resultCode": "SUCCESS",
"resultMessage": "Success"
},
"summary": {
"overallRiskScore": 5.0,
"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"
}Tampering case
{
"result": {
"resultCode": "SUCCESS",
"resultStatus": "S",
"resultMessage": "Success"
},
"transactionId": "R00000020251020115123c7c15c40",
"summary": {
"overallRiskScore": 95.0,
"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`."
}
]
}4. Product Type Description
Product Type | Description |
REALDOC_FORGERY_DETECTION | Document forgery detection |
REALDOC_DOCUMENT_EXTRACTION | Document extraction |
5. Task Status Description
Status | Description |
Processing | Task is being processed |
Success | Task completed successfully |
Failure | Task execution failed |
6. Important Notes
- Either fileContent or fileUrl must be provided in request parameters.
- If the merchant has no quota,
PRODUCT_NOT_AVAILABLEerror will be returned. - For asynchronous processing, billing will be charged as long as the processing is successful, regardless of whether the results are queried.
- After successful task submission, it is recommended to use the status interface to poll the specific status before querying the results.
- Only when the task status is Success will the specific processing results be returned.
- Rate Limiting Notice: Some APIs have rate limiting settings. If you encounter rate limiting issues, please contact us.