中登查询 API 接入规则

密钥与账户

服务端使用 X-Api-Key 请求头认证。网页登录 Cookie 不能认证开放接口，API Key 不能认证网页或管理接口。所有资源属于创建密钥的个人账户。

有效订阅用户（含轻量版）在「接入中心 → API 密钥」（/integrations/keys）填写名称并创建密钥。每个账户固定最多 3 个有效密钥，默认有效期 365 天。已撤销密钥不在列表显示；已过期但未撤销的密钥继续显示，已过期或已撤销的密钥均不占有效名额。完整密钥仅在创建时返回一次，请保存到服务端密钥管理器，经环境变量注入；不要置于前端代码、地址栏、日志、版本库或截图中。

有效密钥可调用所属账户的全部开放接口。轮换时先创建新密钥并更新调用方，再撤销旧密钥。撤销后新请求立即失效，已受理任务继续执行。订阅过期或次数耗尽后，已有密钥仍可读取已生成的结果；订阅过期禁止创建新任务及密钥。成功请求可以使用原幂等键重放。创建响应丢失时先在列表中撤销无法取得完整密钥的项目，再重新创建。

开放接口随服务启动即可使用，所有请求仍须通过 API Key 鉴权和资源归属校验。创建密钥及新任务需要有效订阅（含轻量版）；查重任务另需专业版或企业版查重权益；已有密钥的查看和撤销不受套餐限制。

异步状态、计次与重试

以 `executionStatus` 判断后台执行是否结束。 queued、waiting_resource、processing 需要继续轮询；succeeded、partial、failed、cancelled 是执行终态，cancelled 表示查询已取消。字段缺失或出现未知状态时应报错并保留任务 ID，不能按成功或完成处理。建议间隔从 3 秒逐步退避至 30 秒，并设置调用方总时限。长期等待资源可稍后继续轮询已有 ID，不要重复创建任务。

任务 status 表达业务状态，例如查询明确零登记为 no_result，查重执行结束后可能为 review_pending。候选的 systemDecision 与 manualReview 分别返回系统判断与已有人工结论；人工判断 confirmed 为确认风险，false_positive 为误报，任务的 confirmedRiskCount、excludedCount 仅统计人工结论。API 首期不写人工结论。

始终同时检查 coverageComplete 和 sourceStatus：coverageComplete=false 或 sourceStatus 为 quarantined、unavailable 时，未命中不能解释为排除风险。部分解析失败的结果仍可能包含有用命中。隔离资料不能下载；明确零登记是正常的已完成查询。

查询和查重任务以可选 failure: {code,message} 返回受控失败或覆盖不足原因，不返回上游错误原文。code 为 SOURCE_QUARANTINED、SOURCE_UNAVAILABLE、QUERY_FAILED、CHECK_FAILED、DOCUMENT_COVERAGE_INCOMPLETE 或 CHECK_COVERAGE_INCOMPLETE；结合状态和完整性判断，failure 存在不代表已有结果全部无用。公开查重任务不再返回 processingStartedAt，不要把创建时间当成实际工作开始时间；使用 createdAt、processingCompletedAt、completedAt 及状态描述当前进度。

网页的登记证明结果接口 GET /api/v1/checks/{id}/results 使用 resultStatus=all|pending|confirmed|excluded|unmatched 筛选，返回四类互斥的 counts，以及每份证明的 resultStatus、待处理原因和资料覆盖原因。pending 同时包含待人工复核的命中证明与资料尚不足以判定的证明；后者不能提交人工结论。原有系统匹配与人工复核字段继续单独记录。

新任务按现有计费规则预留；查询取得完整登记清单后结算，包含明确零登记。后续下载或解析失败不退查询次数。网页和 API 并发使用同一额度；以服务端最终受理结果为准。

为每次新的业务意图生成唯一 Idempotency-Key（建议 UUID），网络超时或连接中断时使用相同路径、请求体和幂等键重试。成功重放返回首次受理响应，不代表最新进度；最新状态通过 GET 读取。同一用户的不同密钥共享幂等空间。成功重放先通过认证校验，再使用已存响应，因此订阅过期、次数不足不会导致重试再次计次。相同幂等键搭配不同请求体返回冲突。

读取账户权益不预留次数；即使读取时次数充足，提交时也可能因并发消耗而返回次数不足。以服务端受理结果为准。

默认同一用户所有密钥合计：创建任务 10 次/分钟，其他请求 120 次/分钟，文件下载同时最多 3 个连接。429 携带 Retry-After；等待后继续相同意图。Redis 不可用返回受控 503，不进入收费执行。这些参数用于接口保护，不代表上游吞吐承诺。

响应均有 X-Request-Id。错误 JSON 为 {"code":"机器错误码","message":"公开消息","requestId":"请求编号"}。字段校验失败时可以附带 details.fields: [{path,code,message}]，path 如 criteria[3].value，用于定位错误项；只返回字段路径和受控规则说明，不回显客户原文或密钥。缺少 details 时仍按顶层错误码处理。保留请求编号用于排查，不记录密钥、请求正文或客户原文。常见状态：

文件下载成功返回 200，合法单段范围返回 206，不满足范围返回 416。下载完整文件时不加 Range，需要部分内容时例如 Range: bytes=0-1023；多段范围不受支持。

当前开放范围

开放登记查询、自动查重、结果与证据读取。当前不提供监控 API、Webhook、独立 OCR 接口、人工复核写入或 Excel 导出，不支持浏览器跨域调用。

接口保护参数与账号资源分别管理，默认限流不代表上游吞吐承诺。创建密钥和调用状态以服务端为准；如需确认当前接入条件，可先提交接入咨询。

继续阅读