Integration Guide

2025-10-24 03:44

1. Overview

This guide provides step-by-step instructions for international customers to integrate with RealDoc's asynchronous and synchronous processing capabilities. The async and sync APIs allow you to process documents for forgery detection or information extraction.

2. Product Integration

2.1. Prepare

You can directly refer to the official documents: Getting started integrating

2.2. Pure API-mode integration

You can directly refer: Pure API-mode integration

3. Integration Architecture

RealDoc provides a simple three-step async processing flow:

Upload Document → Submit document for async processing
Check Status → Monitor processing progress
Get Results → Retrieve processed results

3.1. Sequence Diagram

4. Quick Start

4.1. Prerequisites

Valid RealDoc merchant account
API credentials (merchantId, secretKey)
Document files (support file: pdf、jpg/jpeg、png、webp、bmp、tiff, max 10MB)

4.2. Base Configuration

4.2.1. Latest SDK Version

Latest version：https://central.sonatype.com/artifact/com.zoloz.api.sdk/zoloz-api-sdk

copy
<dependency>
    <groupId>com.zoloz.api.sdk</groupId>
    <artifactId>zoloz-api-sdk</artifactId>
    <version>1.1.2</version>
</dependency>

4.2.2. Initialize OpenAPIClient with AK/SK

Test ak and sk can be obtained by directly contacting zoloz.

copy
public static OpenApiClient realdoc_test = new OpenApiClient(){{
        setClientId("xxx");
        setAccessKey("ak");
        setSecretKey("sk");
        setProtoName("aksk");
        setHostUrl("xxx");
    }};

5. Integration Steps

5.1. Base API

copy
private static RealDocAPI getRealDocAPI(String env) {
        // Initialize RealDocAPI using your configured OpenApiClient
    }
    // async upload doc
    @RequestMapping(value = {"/upload"}, method = RequestMethod.POST)
    public RealDocAsyncUploadResponse realDocUpload(@RequestBody RealDocAsyncUploadRequest request, @RequestParam String env) {
        return getRealDocAPI(env).asyncUpload(request);
    }
    // async check task status
    @RequestMapping(value = {"/status"}, method = RequestMethod.POST)
    public RealDocAsyncStatusResponse realDocStatus(@RequestBody RealDocAsyncStatusRequest request, @RequestParam String env) {
        return getRealDocAPI(env).asyncStatus(request);
    }
    // async fraudCheckResult
    @RequestMapping(value = {"/fraudCheckResult"}, method = RequestMethod.POST)
    public RealDocAsyncFraudCheckResultResponse realDocFraudCheckResult(@RequestBody RealDocAsyncFraudCheckResultRequest request, @RequestParam String env) {
        return getRealDocAPI(env).asyncFraudCheckResult(request);
    }
    // async parse
    @RequestMapping(value = {"/parseresult"}, method = RequestMethod.POST)
    public RealDocAsyncParseResultResponse realDocParse(@RequestBody RealDocAsyncParseResultRequest request, @RequestParam String env) {
        return getRealDocAPI(env).asyncParseResult(request);
    }
    // sync parse
    @RequestMapping(value = {"/parse"}, method = RequestMethod.POST)
    public RealDocParseResponse realDoc(@RequestBody RealDocParseRequest request, @RequestParam String env) {
        return getRealDocAPI(env).parse(request);
    }

5.2. Async Document Extraction Example

Step 1: Submit Document for Processing

Step 2: Monitor Processing Status

Step 3: Retrieve Results

copy
private static RealDocAPI getRealDocAPI(String env) {
        // Initialize RealDocAPI using your configured OpenApiClient
    }
/**
     * Complete asynchronous document parsing workflow case
     * 1. Upload document
     * 2. Check processing status
     * 3. Get parsing results
     */
@RequestMapping(value = {"/asyncParseCase"}, method = RequestMethod.POST)
public RealDocAsyncParseResultResponse asyncParseCase(@RequestBody RealDocAsyncUploadRequest uploadRequest, @RequestParam String env) {
    // Step 1: Upload document
    uploadRequest.setBizId("realdoc_parse_" + System.currentTimeMillis());
    RealDocAsyncUploadResponse uploadResponse = getRealDocAPI(env).asyncUpload(uploadRequest);
    if (uploadResponse == null || uploadResponse.getTransactionId() == null) {
        throw new RuntimeException("Document upload failed");
    }
    // Verify upload result status is successful
    if (!"S".equals(uploadResponse.getResult().getResultStatus())) {
        throw new RuntimeException("Document upload failed, resultStatus: " + uploadResponse.getResult().getResultStatus());
    }
    String transactionId = uploadResponse.getTransactionId();
    // Step 2: Poll processing status until completion
    RealDocAsyncStatusRequest statusRequest = new RealDocAsyncStatusRequest();
    statusRequest.setTransactionId(transactionId);
    int maxRetries = 5;
    int retryCount = 0;
    while (retryCount < maxRetries) {
        // bizId uniquely identifies a request and can be customized
        statusRequest.setBizId("realdoc_status_" + System.currentTimeMillis());
        RealDocAsyncStatusResponse statusResponse = getRealDocAPI(env).asyncStatus(statusRequest);
        if (statusResponse == null) {
            throw new RuntimeException("Failed to get status");
        }
        // Status codes: Processing means processing, Success means successful, Failure means failed
        String status = statusResponse.getStatus();
        if ("Success".equals(status)) {
            break; // Processing completed successfully, exit loop
        } else if ("Failure".equals(status)) {
            throw new RuntimeException("Document processing failed, status: " + status);
        } else if (!"Processing".equals(status)) {
            throw new RuntimeException("Unknown status: " + status);
        }
        // Processing, continue waiting
        retryCount++;
        try {
            Thread.sleep(20000); // Wait 20 seconds
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            throw new RuntimeException("Waiting interrupted", e);
        }
    }
    if (retryCount >= maxRetries) {
        throw new RuntimeException("Document processing timeout, exceeded maximum wait time");
    }
    // Step 3: Get parsing results
    RealDocAsyncParseResultRequest parseResultRequest = new RealDocAsyncParseResultRequest();
        parseResultRequest.setTransactionId(transactionId);
        parseResultRequest.setBizId("realdoc_parse_" + System.currentTimeMillis());
        return getRealDocAPI(env).asyncParseResult(parseResultRequest);
    }

5.3. Async Document Forgery Detection Example

Step 1: Submit Document for Processing

Step 2: Monitor Processing Status

Step 3: Retrieve Results

copy
private static RealDocAPI getRealDocAPI(String env) {
        // Initialize RealDocAPI using your configured OpenApiClient
    }
    /**
     * Complete asynchronous document fraud detection workflow case
     * 1. Upload document
     * 2. Check processing status
     * 3. Get fraud detection results
     */
    @RequestMapping(value = {"/asyncFraudCheckCase"}, method = RequestMethod.POST)
    public RealDocAsyncFraudCheckResultResponse asyncFraudCheckCase(@RequestBody RealDocAsyncUploadRequest uploadRequest, @RequestParam String env) {
        // Step 1: Upload document
        uploadRequest.setBizId("realdoc_fraudCheck_" + System.currentTimeMillis());
        RealDocAsyncUploadResponse uploadResponse = getRealDocAPI(env).asyncUpload(uploadRequest);
        if (uploadResponse == null || uploadResponse.getTransactionId() == null) {
            throw new RuntimeException("Document upload failed");
        }
        
        // Verify upload result status is successful
        if (!"S".equals(uploadResponse.getResult().getResultStatus())) {
            throw new RuntimeException("Document upload failed, resultStatus: " + uploadResponse.getResult().getResultStatus());
        }
        
        String transactionId = uploadResponse.getTransactionId();
        
        // Step 2: Poll processing status until completion
        RealDocAsyncStatusRequest statusRequest = new RealDocAsyncStatusRequest();
        statusRequest.setTransactionId(transactionId);
        
        int maxRetries = 5;
        int retryCount = 0;
        
        while (retryCount < maxRetries) {
            statusRequest.setBizId("realdoc_status_" + System.currentTimeMillis());
            RealDocAsyncStatusResponse statusResponse = getRealDocAPI(env).asyncStatus(statusRequest);
            
            if (statusResponse == null) {
                throw new RuntimeException("Failed to get status");
            }
            
            // Status codes: Processing means processing, Success means successful, Failure means failed
            String status = statusResponse.getStatus();
            if ("Success".equals(status)) {
                break; // Processing completed successfully, exit loop
            } else if ("Failure".equals(status)) {
                throw new RuntimeException("Document processing failed, status: " + status);
            } else if (!"Processing".equals(status)) {
                throw new RuntimeException("Unknown status: " + status);
            }
            
            // Processing, continue waiting
            retryCount++;
            try {
                Thread.sleep(20000); // Wait 20 seconds
            } catch (InterruptedException e) {
                Thread.currentThread().interrupt();
                throw new RuntimeException("Waiting interrupted", e);
            }
        }
        
        if (retryCount >= maxRetries) {
            throw new RuntimeException("Document processing timeout, exceeded maximum wait time");
        }
        
        // Step 3: Get fraud detection results
        RealDocAsyncFraudCheckResultRequest fraudCheckResultRequest = new RealDocAsyncFraudCheckResultRequest();
        fraudCheckResultRequest.setTransactionId(transactionId);
        fraudCheckResultRequest.setBizId("realdoc_fraud_" + System.currentTimeMillis());
        return getRealDocAPI(env).asyncFraudCheckResult(fraudCheckResultRequest);
    }

5.4. Sync Document Extraction Example

copy
private static RealDocAPI getRealDocAPI(String env) {
        // Initialize RealDocAPI using your configured OpenApiClient
    }
    
    // sync parse
    @RequestMapping(value = {"/parse"}, method = RequestMethod.POST)
    public RealDocParseResponse realDoc(@RequestBody RealDocParseRequest request, @RequestParam String env) {
        return getRealDocAPI(env).parse(request);
    }

6. Best Practices

6.1. Error Handling

Always implement proper error handling for network failures
Use exponential backoff for retries
Set reasonable timeouts (recommend 300s max)

6.2. Security

Never expose API keys in client-side code
Use HTTPS for all API calls
Implement rate limiting in your application

6.3. Performance

Use base64 encoding for small documents (<1MB)
Use file URLs for large documents (>1MB)
Implement proper connection pooling
Rate Limiting Notice: Some APIs have rate limiting settings. If you encounter rate limiting issues, please contact us.

6.4. Monitoring

Log all API interactions for debugging
Monitor processing times and success rates
Set up alerts for failures

6.5. Testing

Test with various document types and sizes
Test error scenarios and recovery
Implement proper integration tests

7. Support

For technical support or questions about integration:

Documentation: https://docs.zoloz.com
Online Support: https://www.zoloz.com/get-in-touch

8. Version History

Version	Date	Changes
1.0	2025-10-24	Initial release