RealDoc集成指南

2025-12-19 06:11

本文为客户集成RealDoc的异步和同步文档处理能力提供指导。通过接入RealDoc API，可实现文档防伪检测和文档信息提取功能。

集成概述

准备工作

在开始集成前，请参考快速入门完成准备工作。

集成模式

RealDoc目前支持纯API模式集成，具体操作详见使用API模式接入。

集成架构

RealDoc提供简单易用的异步处理流程，主要包含以下三个步骤：

上传文档：上传待处理文档
查询状态：监控处理进度
获取结果：获取处理结果

RealDoc异步处理流程对应的时序图如下：

快速开始

前提条件

已拥有有效的RealDoc商户账号。
已获取API凭证（Access Key和Secret Key），详见AK/SK接入所需的API凭证。
已准备好待处理的文档文件（支持格式：pdf、jpg、jpeg、png、webp、bmp、tiff，文件大小最大为10MB）。

基础配置

单击此处下载最新版SDK。
使用AK/SK初始化OpenAPIClient。测试所需AK和SK可联系ZOLOZ技术支持获取。

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

集成步骤

基础API

copy
private static RealDocAPI getRealDocAPI(String env) {
        // 使用配置的OpenApiClient初始化RealDocAPI
    }
    // 异步上传文档
    @RequestMapping(value = {"/upload"}, method = RequestMethod.POST)
    public RealDocAsyncUploadResponse realDocUpload(@RequestBody RealDocAsyncUploadRequest request, @RequestParam String env) {
        return getRealDocAPI(env).asyncUpload(request);
    }
    // 异步查询任务状态
    @RequestMapping(value = {"/status"}, method = RequestMethod.POST)
    public RealDocAsyncStatusResponse realDocStatus(@RequestBody RealDocAsyncStatusRequest request, @RequestParam String env) {
        return getRealDocAPI(env).asyncStatus(request);
    }
    // 异步获取防伪检测结果
    @RequestMapping(value = {"/fraudCheckResult"}, method = RequestMethod.POST)
    public RealDocAsyncFraudCheckResultResponse realDocFraudCheckResult(@RequestBody RealDocAsyncFraudCheckResultRequest request, @RequestParam String env) {
        return getRealDocAPI(env).asyncFraudCheckResult(request);
    }
    // 异步解析
    @RequestMapping(value = {"/parseresult"}, method = RequestMethod.POST)
    public RealDocAsyncParseResultResponse realDocParse(@RequestBody RealDocAsyncParseResultRequest request, @RequestParam String env) {
        return getRealDocAPI(env).asyncParseResult(request);
    }
    // 同步解析
    @RequestMapping(value = {"/parse"}, method = RequestMethod.POST)
    public RealDocParseResponse realDoc(@RequestBody RealDocParseRequest request, @RequestParam String env) {
        return getRealDocAPI(env).parse(request);
    }

异步文档信息提取示例

处理流程包含以下三个步骤：

上传待处理文档
查询文档处理状态
获取解析结果

示例代码如下：

copy
private static RealDocAPI getRealDocAPI(String env) {
        // 使用配置的OpenApiClient初始化RealDocAPI
    }
/**
     * 完整的异步文档解析工作流示例
     * 1. 上传文档
     * 2. 查询处理状态
     * 3. 获取解析结果
     */
@RequestMapping(value = {"/asyncParseCase"}, method = RequestMethod.POST)
public RealDocAsyncParseResultResponse asyncParseCase(@RequestBody RealDocAsyncUploadRequest uploadRequest, @RequestParam String env) {
    // 步骤1：上传文档
    uploadRequest.setBizId("realdoc_parse_" + System.currentTimeMillis());
    RealDocAsyncUploadResponse uploadResponse = getRealDocAPI(env).asyncUpload(uploadRequest);
    if (uploadResponse == null || uploadResponse.getTransactionId() == null) {
        throw new RuntimeException("Document upload failed");
    }
    // 验证上传结果
    if (!"S".equals(uploadResponse.getResult().getResultStatus())) {
        throw new RuntimeException("Document upload failed, resultStatus: " + uploadResponse.getResult().getResultStatus());
    }
    String transactionId = uploadResponse.getTransactionId();
    // 步骤2：轮询处理状态直至完成
    RealDocAsyncStatusRequest statusRequest = new RealDocAsyncStatusRequest();
    statusRequest.setTransactionId(transactionId);
    int maxRetries = 5;
    int retryCount = 0;
    while (retryCount < maxRetries) {
        // bizId用于唯一标识一个请求，且支持自定义
        statusRequest.setBizId("realdoc_status_" + System.currentTimeMillis());
        RealDocAsyncStatusResponse statusResponse = getRealDocAPI(env).asyncStatus(statusRequest);
        if (statusResponse == null) {
            throw new RuntimeException("Failed to get status");
        }
        // 状态码说明：Processing表示正在处理中，Success表示成功，Failure表示失败
        String status = statusResponse.getStatus();
        if ("Success".equals(status)) {
            break; // 处理成功，退出循环
        } else if ("Failure".equals(status)) {
            throw new RuntimeException("Document processing failed, status: " + status);
        } else if (!"Processing".equals(status)) {
            throw new RuntimeException("Unknown status: " + status);
        }
        // 正在处理中，请继续等待
        retryCount++;
        try {
            Thread.sleep(20000); // 等待20秒
        } 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");
    }
    // 步骤3：获取解析结果
    RealDocAsyncParseResultRequest parseResultRequest = new RealDocAsyncParseResultRequest();
        parseResultRequest.setTransactionId(transactionId);
        parseResultRequest.setBizId("realdoc_parse_" + System.currentTimeMillis());
        return getRealDocAPI(env).asyncParseResult(parseResultRequest);
    }

异步文档防伪检测示例

处理流程包含以下三个步骤：

上传待处理文档
查询文档处理状态
获取防伪检测结果

示例代码如下：

copy
private static RealDocAPI getRealDocAPI(String env) {
        // 使用配置的OpenApiClient初始化RealDocAPI
    }
    /**
     * 完整的异步文档防伪检测工作流示例
     * 1. 上传文档
     * 2. 查询处理状态
     * 3. 获取防伪检测结果
     */
    @RequestMapping(value = {"/asyncFraudCheckCase"}, method = RequestMethod.POST)
    public RealDocAsyncFraudCheckResultResponse asyncFraudCheckCase(@RequestBody RealDocAsyncUploadRequest uploadRequest, @RequestParam String env) {
        // 步骤1：上传文档
        uploadRequest.setBizId("realdoc_fraudCheck_" + System.currentTimeMillis());
        RealDocAsyncUploadResponse uploadResponse = getRealDocAPI(env).asyncUpload(uploadRequest);
        if (uploadResponse == null || uploadResponse.getTransactionId() == null) {
            throw new RuntimeException("Document upload failed");
        }
        
        // 验证上传结果
        if (!"S".equals(uploadResponse.getResult().getResultStatus())) {
            throw new RuntimeException("Document upload failed, resultStatus: " + uploadResponse.getResult().getResultStatus());
        }
        
        String transactionId = uploadResponse.getTransactionId();
        
        // 步骤2：轮询处理状态直至完成
        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");
            }
            
            // 状态码说明：Processing表示正在处理中，Success表示成功，Failure表示失败
            String status = statusResponse.getStatus();
            if ("Success".equals(status)) {
                break; // 处理成功，退出循环
            } else if ("Failure".equals(status)) {
                throw new RuntimeException("Document processing failed, status: " + status);
            } else if (!"Processing".equals(status)) {
                throw new RuntimeException("Unknown status: " + status);
            }
            
            // 正在处理中，请继续等待
            retryCount++;
            try {
                Thread.sleep(20000); // 等待20秒
            } 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");
        }
        
        // 步骤3：获取防伪检测结果
        RealDocAsyncFraudCheckResultRequest fraudCheckResultRequest = new RealDocAsyncFraudCheckResultRequest();
        fraudCheckResultRequest.setTransactionId(transactionId);
        fraudCheckResultRequest.setBizId("realdoc_fraud_" + System.currentTimeMillis());
        return getRealDocAPI(env).asyncFraudCheckResult(fraudCheckResultRequest);
    }

同步文档信息提取示例

调用实时同步文档解析API，上传文档后将直接返回提取结果。

copy
private static RealDocAPI getRealDocAPI(String env) {
        // 使用配置的OpenApiClient初始化RealDocAPI
    }
    
    // 同步解析
    @RequestMapping(value = {"/parse"}, method = RequestMethod.POST)
    public RealDocParseResponse realDoc(@RequestBody RealDocParseRequest request, @RequestParam String env) {
        return getRealDocAPI(env).parse(request);
    }

技术支持

如果有任何集成方面的问题，可通过以下方式获取帮助：

官方文档：https://docs.zoloz.com/zoloz/saas/cn
在线支持：https://www.zoloz.com/get-in-touch