Schema管理API

2026-06-30 08:42

重要说明：

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

Schema管理API用于管理文档处理模板（Schema），支持创建、更新和查询自定义文档提取规则。当前仅支持文档信息提取（REALDOC_DOCUMENT_EXTRACTION）产品类型。

通用请求参数

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

字段名称

数据类型

描述

bizId

String

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

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

创建Schema

API路径

POST /api/v1/zoloz/realdoc/schema/create

API描述

该接口用于创建Schema。

请求参数

字段名称	数据类型	是否必填	默认值	描述	示例值
bizId	String	是	-	商户的业务ID，用于区分不同的请求或任务。	20230601001
schemaId	String	是	-	Schema标识，仅支持字母、数字、下划线和连字符，最大长度128。说明：`schemaId`在同一商户下必须唯一，不可重复。	my_custom_schema
productType	String	是	-	产品类型，当前仅支持`REALDOC_DOCUMENT_EXTRACTION`（文档信息提取）。	REALDOC_DOCUMENT_EXTRACTION
schemaData	Object	是	-	Schema定义数据，须符合JSON Schema Draft 7规范，详见SchemaData校验说明。	参考请求示例

SchemaData校验说明

schemaData字段须符合JSON Schema Draft 7规范，并受以下规则限制：

类别	说明
支持的字段（共24个）	`type`、`format`、`title`、`description`、`nullable`、`default`、`items`、`minItems`、`maxItems`、`prefixItems`、`enum`、`properties`、`propertyOrdering`、`required`、`minProperties`、`maxProperties`、`additionalProperties`、`minimum`、`maximum`、`minLength`、`maxLength`、`pattern`、`example`、`anyOf`
不支持的字段（校验拒绝）	`$ref`、`$defs`、`allOf`、`oneOf`、`not`、`if/then/else`、`const`、`patternProperties` 等。如果使用了这些字段，系统将返回校验失败。
支持的`type`值	`string`、`number`、`integer`、`boolean`、`object`、`array`、`null`

返回参数

字段名称

数据类型

描述

示例值

result

Result

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

{

"resultStatus": "S",

"resultCode": "SUCCESS",

"resultMessage": "Success"

}

schemaId

String

创建成功的Schema标识。

my_custom_schema

请求示例

copy
{
    "bizId": "20230601001", 
    "schemaId": "my_custom_schema", 
    "productType": "REALDOC_DOCUMENT_EXTRACTION", 
    "schemaData": {
        "type": "object", 
        "properties": {
            "company_name": {
                "type": "string", 
                "description": "Company name"
            }, 
            "registration_number": {
                "type": "string", 
                "description": "Company registration number"
            }, 
            "registered_address": {
                "type": "string", 
                "description": "Registered address"
            }
        }, 
        "required": [
            "company_name"
        ]
    }
}

返回示例

copy
{
    "result": {
        "resultStatus": "S", 
        "resultCode": "SUCCESS", 
        "resultMessage": "Success"
    }, 
    "schemaId": "my_custom_schema"
}

更新Schema

API路径

POST /api/v1/zoloz/realdoc/schema/update

API描述

该接口用于更新Schema。

请求参数

字段名称	数据类型	是否必填	默认值	描述	示例值
bizId	String	是	-	商户的业务ID，用于区分不同的请求或任务。	20230601002
schemaId	String	是	-	待更新的Schema标识，仅支持字母、数字、下划线和连字符，最大长度128。	my_custom_schema
schemaData	Object	是	-	新的Schema定义数据，详见SchemaData校验说明。	参考请求示例

返回参数

字段名称

数据类型

描述

示例值

result

Result

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

{

"resultStatus": "S",

"resultCode": "SUCCESS",

"resultMessage": "Success"

}

请求示例

copy
{
    "bizId": "20230601002", 
    "schemaId": "my_custom_schema", 
    "schemaData": {
        "type": "object", 
        "properties": {
            "company_name": {
                "type": "string", 
                "description": "Company name"
            }, 
            "registration_number": {
                "type": "string", 
                "description": "Company registration number"
            }, 
            "registered_address": {
                "type": "string", 
                "description": "Registered address"
            }, 
            "incorporation_date": {
                "type": "string", 
                "description": "Date of incorporation"
            }
        }, 
        "required": [
            "company_name", 
            "registration_number"
        ]
    }
}

返回示例

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

查询Schema

API路径

POST /api/v1/zoloz/realdoc/schema/query

API描述

该接口用于查询Schema。支持查询单个Schema或查询当前商户下所有Schema的生效版本。

请求参数

字段名称	数据类型	是否必填	默认值	描述	示例值
bizId	String	是	-	商户的业务ID，用于区分不同的请求或任务。	20230601003
schemaId	String	是	-	待查询的Schema标识。取值：传入具体的`schemaId`：查询单个Schema。传入`All`：查询当前商户下所有Schema的生效版本。	my_custom_schema
productType	String	否	null	产品类型，用于过滤查询结果。当前仅支持`REALDOC_DOCUMENT_EXTRACTION`（文档信息提取）。	REALDOC_DOCUMENT_EXTRACTION

返回参数

字段名称

数据类型

描述

示例值

result

Result

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

{

"resultStatus": "S",

"resultCode": "SUCCESS",

"resultMessage": "Success"

}

schemas

List<SchemaItem>

Schema列表，仅返回当前生效版本的数据。

参考返回示例

SchemaItem字段说明

字段名称	数据类型	描述	示例值
schemaId	String	Schema标识。	my_custom_schema
productType	String	产品类型。	REALDOC_DOCUMENT_EXTRACTION
schemaData	Object	Schema定义数据，即当前生效版本的具体内容。	参考返回示例

请求示例

示例1：查询单个Schema

copy
{
    "bizId": "20230601003", 
    "schemaId": "my_custom_schema"
}

示例2：查询所有Schema

copy
{
    "bizId": "20230601003", 
    "schemaId": "All"
}

示例3：查询指定产品类型下的所有Schema

copy
{
    "bizId": "20230601003", 
    "schemaId": "All", 
    "productType": "REALDOC_DOCUMENT_EXTRACTION"
}

返回示例

copy
{
    "result": {
        "resultStatus": "S", 
        "resultCode": "SUCCESS", 
        "resultMessage": "Success"
    }, 
    "schemas": [
        {
            "schemaId": "my_custom_schema", 
            "productType": "REALDOC_DOCUMENT_EXTRACTION", 
            "schemaData": {
                "type": "object", 
                "properties": {
                    "company_name": {
                        "type": "string", 
                        "description": "Company name"
                    }, 
                    "registration_number": {
                        "type": "string", 
                        "description": "Company registration number"
                    }, 
                    "registered_address": {
                        "type": "string", 
                        "description": "Registered address"
                    }
                }, 
                "required": [
                    "company_name"
                ]
            }
        }
    ]
}

API结果码

Schema管理API的结果码见下表。

结果码	结果状态	描述
SUCCESS	S	操作成功。
PARAMETER_ERROR	F	请求参数错误，可能原因包括： schemaId为空 schemaId格式非法 productType不支持 schemaData校验失败
CLIENT_BUSINESS_ERROR	F	客户业务错误，可能原因包括： Schema已存在 Schema不存在产品类型不匹配版本冲突或更新冲突产品不可用（商户无可用配额）
INTERNAL_BUSINESS_ERROR	F	内部业务错误，可能原因包括： Schema创建失败 Schema更新失败
SYSTEM_ERROR	F	系统错误，服务暂不可用。