调用方v0.4 · 公开快照

HTTP 接口参考

本文描述当前 v0.4 开发原型。文档公开不表示查询服务已对外开放。示例地址为占位符，部署方需另行提供实际地址及接入方式。

提交查询

http

POST /verifications
Content-Type: application/json

bash

curl -X POST 'https://your-api.example/verifications' \
  -H 'Content-Type: application/json' \
  -d '{"rid":"example-001","name":"瑞金医院","query_mask":7}'

字段	类型	规则
rid	string 或 integer	必填；非空，字符串表示最多200字符；不接受布尔值
name	string 或 null	最多200字符；与信用代码至少一项非空
social_credit_code	string 或 null	最多200字符；格式问题在业务结果中反馈
query_mask	integer	1–7，默认7；不接受布尔值

不接收额外字段。name／social_credit_code 纯空白视为无值。JSON 不允许重复字段或非标准常量，请求体为1–8192字节，暂不支持 Transfer-Encoding。

信用代码当前仅检查18位大写字母／数字形式，尚未实施校验位算法。格式不符但仍有名称时可继续名称路径；不要把格式检查当成有效性确认。

提交响应与任务状态

成功提交返回 HTTP 202。下面为合成的结构示例：

json

{
  "job_id": "00000000000000000000000000000001",
  "state": "QUEUED",
  "request": {
    "rid": "example-001",
    "name": "瑞金医院",
    "social_credit_code": null,
    "query_mask": 7
  },
  "created_at": "2026-10-22T00:00:00+00:00",
  "updated_at": "2026-10-22T00:00:00+00:00",
  "result": null,
  "status_url": "/verifications/00000000000000000000000000000001"
}

每次 POST 都创建新任务。rid 仅关联，不提供幂等保障。

查询任务

http

GET /verifications/{job_id}

返回任务封装；job_id 为32位小写十六进制字符串。

state	含义
QUEUED	已接受，等待来源执行
RUNNING	当前正在执行
COMPLETED	执行结束；不保证唯一匹配或所有字段齐全
FAILED	任务级执行失败或中断恢复标记，检查错误

业务结论在 result.status，字段完整性在 details 各组 query_status。HTTP 200 和 COMPLETED 都不能替代这些判断。

健康检查

http

GET /health

当前返回 status=ok 与 schema_version=0.4，仅表示进程能响应，不承诺来源授权、额度或实时可用性。

HTTP 错误

HTTP	含义
400	JSON或字段校验失败
404	路径或任务不存在
413	请求体为空或超过8192字节
415	非 application/json
429	队列已满，最多20个未完成任务

来源超时、无权限、日额度不足等通常体现在任务结果的 sources／issues。不要把来源失败解释为未找到主体。

当前执行限制

当前不支持批量、取消、人工恢复或任务级自动重试。来源按预算串行执行，医疗渠道有至少65秒提交间隔、验证码最多3次及单次预算；任务整体尚无统一截止时间，极端串行耗时可能较长。重启后中断的 RUNNING 任务标记失败，不自动重复扣费重跑。

下载 OpenAPI 原型参考（描述当前接口，非生产契约承诺）