API 总览

接口面

方法	路径	用途	KYB
GET	/v1/exposure	你自有地址簿的匹配，附覆盖健康度。游标翻页。	需要
GET	/v1/coverage	单独查询覆盖健康度，按账户作用域。	需要
POST	/v1/screen/address	筛查单个地址。A 层，可选 B 层。	—
POST	/v1/decide/deposit	贷记闸门。Fail-closed。	需要
GET	/v1/decisions/{decision_id}/evidence	单条裁决的证据包，application/zip。	—

另有三个 webhook 投递给你：exposure.match、exposure.revoked、coverage.health_changed。

参考是生成的

api/openapi.yaml 是这套 API 的唯一事实源。本节的接口参考与类型参考由构建期从该文件渲染——它们没有自己的源文件。

这是结构选择，不是图省事。手写的接口表格会在有人上线了一个字段却忘了改文档的那一刻起漂移，而且这个漂移在某个接入方信了错的那一份之前是不可见的。这里没有什么可忘：契约改了，下一次构建这一页就跟着改；契约缺失，构建直接失败而不是渲染出一份空参考。

• 接口参考 —— 接口、webhook、投递请求头与错误模型。
• 类型与 reason code —— 全部具名 schema、全部枚举，以及完整的 reason code 清单。

那两页上的字段描述逐字取自契约。它们说明字段是什么，不说明它怎么算出来，而且无论怎么要求都不会出现说明后者的页面。

约定

媒体类型。 请求与成功响应是 application/json，证据包除外，它是 application/zip。所有非 2xx 响应是 application/problem+json，用 RFC 9457 的 Problem 形状。

时间戳。 RFC 3339，UTC，例如 2026-08-24T09:04:11Z。

金额。 amount_usd 是十进制字符串而不是数字，以免浮点丢精度。

不透明值。 游标、customer_address_ref、authority_id 都是不透明的。不要解析、不要构造、不要用它们排序。

未知字段。 忽略你不认识的字段。新增可选字段与新增 reason code 属于 minor 变更。

版本

破坏性变更走新的路径前缀。v1 既有语义不变。

新增可选字段或新增 reason code 属于 minor，会发生在 v1 内部。因此你的客户端必须把不认识的 reason code 当作至少与随附的 risk_level 同等严重，绝不能当作「不认识所以没事」。