中登查询与查重 API 快速开始

接入前准备

文档可以直接阅读。实际调用需要有效密钥；创建密钥要求账户有有效订阅（含轻量版）。登录账户后，进入“接入中心 → API 密钥”查看当前状态。

1. 创建 API 密钥

   在“接入中心 → API 密钥”填写名称并创建密钥。有效密钥可调用本人账户的开放接口。

2. 将密钥保存在服务端

   完整密钥仅在创建时返回一次，从密钥管理器注入 ZDW_API_KEY。将 ZDW_API_BASE 设置为你的部署域名加 /api/open/v1。

3. 保存业务意图与任务编号

   新业务意图生成幂等键，持久保存该键和提交内容。网络超时后沿用原键重试，获取任务编号后通过 GET 查询进度。

完成首次查询与查重

所有路径均相对于 /api/open/v1。JSON 使用 UTF-8，请求加 Content-Type: application/json。创建任务必须携带非空、最长 128 字符的 Idempotency-Key，建议使用 UUID；服务端按实际任务计算并预留次数。请求体不接受未知字段、空必填项或类型隐式转换，数组至少一项；准确的必填、枚举、长度及分页边界以 OpenAPI schema 为准。

分页采用 ?page=1&pageSize=20，页码从 1 开始，每页 1–100 条；超出范围返回 400，不自动截断。响应为 {items,total,page,pageSize}。查询和查重列表支持 search、status，登记列表支持 search、多选 parseStatus；具体过滤项见契约。空 status 表示全部，非空值必须属于对应接口枚举，拼写错误返回 400。搜索中的 %、_、! 按字面匹配，不能作为通配符。所有资源和嵌套资源都校验本人归属，不存在或无权访问返回 404。文件 URL 同样需要 X-Api-Key，不能直接用浏览器链接代替服务端下载。任务报价接口 /billing/quotes 不再开放；创建任务直接按服务端规则受理计次。

网页和开放 API 的查询历史列表统一展示近 6 个自然月：服务端以北京时间当天零点向前推 6 个月，按查询 createdAt 筛选并包含边界当天。例如 2026-10-11 的起点为 2026-04-11 00:00（北京时间）。搜索、状态、总数以及网页批次和全选均使用此范围，不提供扩大范围的参数。历史数据及文件不会删除，已有查询 ID 的详情、登记清单和下载继续按归属权限访问，关联查重、监控及计费记录不受影响。

账户资格与次数

GET /account/entitlements 的 active 表示是否有有效订阅，apiEnabled 表示当前订阅是否允许通过 API 创建新任务。apiEnabled=true 不表示剩余次数充足或具有查重权益；分别读取 query.available 和 check.available，最终以创建响应为准。订阅过期后仍可读取已有结果、重放原成功请求，客户端不能用 apiEnabled=false 阻止原请求重放。

query、check 各自的 total、used、reserved、retained 汇总当前有效额度桶，排除已过期和未来生效额度；其中 used 为这些有效桶中已结算的次数，reserved 为已预留未结算次数，retained 为账面未用且未预留次数。available 是当前可以使用的次数；订阅无效时可能为零，即使仍有 retained。这些值不是账户历史累计消费报表。

查询：提交、轮询、读取

直接提交 POST /queries：

{"subjectNames":["示例融资企业有限公司"]}

响应形状为 {"queries":[{"id":"…","status":"queued","executionStatus":"queued",…}]}。企业全称或18位身份证号码规范化去重，整批受理或整批回滚。每个查询 ID 单独轮询 GET /queries/{id}，完成后分页读取登记清单和附件。需要重新获取上游资料时，以新的幂等键重新创建查询并正常计次。

个人查询沿用 subjectNames 字符串数组，查重沿用 applicant，不新增主体类型字段；返回的 subjectName／applicant 是规范化后的主体。服务端自动识别18位大陆居民身份证，统一全角、空白和末位 X 大小写，校验出生日期与校验位；证件候选不合法时整批拒绝，不预留次数、不回退为企业查询。首版不支持15位身份证及护照等其他个人证件。企业与个人可混合批量提交；身份证仅确定查询主体，查重仍须提供发票号或关键词。

查重：新查询或复用资料

提交 POST /checks：

{
  "applicant":"示例融资企业有限公司",
  "criteria":[{"kind":"invoice_no","value":"12345678901234567890"},{"kind":"keyword","value":"合同编号示例"}]
}

条件为 1–100 个，类型为 invoice_no 或 keyword，每项 value 为非空字符串、最长 200 字符；查询主体为企业全称或18位大陆居民身份证号码，最长 100 字符。场景固定为 asset_check，单次查重只接受一个主体。

复用资料时，在提交中加入 sourceRegistryQueryId。来源必须是本人、同一主体且已结束的成功或部分完成查询；applicant 仍必填。

创建查重返回单个任务对象，使用 id 轮询 GET /checks/{id}。执行完成后读取候选列表；候选的 evidence 提供文档、页码、命中片段，evidence-locations?documentId=…&pageNumber=1 提供页内坐标。文档下载地址都位于开放接口下。

下载并运行示例

以下示例源码位于代码仓库的 docs/examples/open-api，部署后的指南也提供各文件下载。从密钥管理器注入 ZDW_API_KEY，设置 ZDW_API_BASE=https://你的服务域名/api/open/v1；示例仅允许 HTTPS，或本机开发的 HTTP 地址。命令行中的企业名称、条件应在实际系统中由应用传入，不要将客户原文纳入命令日志。

• curl.sh：需要 Bash、curl、jq 和 Python 3（生成 UUID）。bash docs/examples/open-api/curl.sh query '企业全称' --idempotency-key UUID；check '企业全称' '关键词' [来源查询ID] --idempotency-key UUID；download '文档ID' '本地输出文件'。
• client.py：Python 3 标准库。python3 docs/examples/open-api/client.py query '企业全称' --idempotency-key UUID；check '企业全称' '关键词' --source-query '来源查询ID' --idempotency-key UUID；去掉 --source-query 为新资料查重；download '文档ID' '本地输出文件'。
• JDK 17、Maven：下载 pom.xml 和 OpenApiClient.java，保持 pom.xml 与 src/main/java/OpenApiClient.java 的目录关系。使用 JDK 17 在仓库中执行 mvn -f docs/examples/open-api/java/pom.xml compile exec:java -Dexec.args="query 企业全称 --idempotency-key UUID"。查重参数为 check 企业全称 关键词 [来源查询ID] --idempotency-key UUID，下载为 download 文档ID 本地输出文件。

三个示例会直接提交并轮询至明确执行终态；遇到未知状态会报错，不会将结果直接判定为无风险。示例仅输出任务编号、状态和完整性，不打印密钥或客户原文。下载不会覆盖已有文件。UUID 须替换为本次业务意图的真实唯一键；省略 --idempotency-key 时每次运行都会生成新键并打印到 stderr，因此恢复旧请求必须显式传入原键，同时逐项保留原企业名称、条件和来源 ID，不能更改正文。生产系统应在首次发送前将幂等键与原业务请求可靠保存；已取得任务 ID 时直接 GET 续查即可。查询与查重每个新意图可能正常计次，请使用本人授权的资料。

接入真实业务前

以 executionStatus 判断执行是否结束，并检查 coverageComplete 和 sourceStatus。任务受理成功不等于处理完成，资料不完整时未命中不能用于排除风险。

继续阅读