CHA2A 开放 API 规范

CHA2A 开放 API 规范（Agent 身份 / 信任 / 号码 / 凭证）

> 版本：v0.1 ｜ 2026-08-28 ｜面向开发者（"第二份规范"：给生态的接入契约）

> Base URL：https://compliancehub.cn（RCS 消息类：https://compliancehub.cn/rcs）

> 原则：读开放、写受控。身份/信任/凭证/号码查询公开只读；注册/撤销/入账等写操作需管理员密钥或签名。

---

一、开发者场景（先看这个）

场景	用什么	一句话
号码解析	`GET /api/v1/phone/resolve?number=`	输入号码 → agent DID + 信任等级（来电/来信寻址）
信任查询	`GET /api/v1/trust/query?did=`	输入 DID → 等级 L0-L4 + 状态（可不可信、是否撤销）
凭证/证据验证	`GET /api/v1/evidence/query?did=`	输入 DID → 谁验证过、结果如何（可追溯证据）
身份文档	`GET /api/v1/did/<did>`	标准 DID Document（公钥/验证方法，W3C 格式）

二、基础信息

项	值
Base URL	`https://compliancehub.cn`
RCS Base	`https://compliancehub.cn/rcs`
格式	JSON（`Content-Type: application/json`）
鉴权	查询公开只读；写操作需 `X-Admin-Key` 或 agent 签名（见各端点）
编码	号码中的 `+` 需 URL 编码为 `%2B`（如 `%2B86951230001`）

三、端点一览

身份（registry）

方法	路径	说明
GET	`/api/v1/did/<did>`	DID Document（公钥/验证方法）
GET	`/api/v1/agent/list`	已注册 agent 列表
POST	`/api/v1/register`	注册主体（admin）
POST	`/api/v1/update`	更新记录（admin）
POST	`/api/v1/deactivate`	停用（admin）
POST	`/api/v1/agent/key/register`	登记 agent 公钥（#agent-key）

信任（registry）

方法	路径	说明
GET	`/api/v1/trust/query?did=`	信任等级 + 状态（核心）
GET	`/api/v1/trust/revocations`	撤销列表
POST	`/api/v1/trust/revoke`	撤销（admin）
POST	`/api/v1/verify/agent-sig`	出站签名验签（body: did/signature/payload）
POST	`/api/v1/verify/artifact`	内容完整性验证（v0.3：指纹+背书+等级+撤销，AI 资产聚合报告）

凭证 / 证据（registry）

方法	路径	说明
GET	`/api/v1/evidence/query?did=`	凭证列表（可追溯证据）
POST	`/api/v1/evidence/register`	登记凭证（验证者，签名）

号码（registry）

方法	路径	说明
GET	`/api/v1/phone/resolve?number=`	号码 → agent DID + 等级（寻址核心）
GET	`/api/v1/phone/lookup?did=`	DID → 号码
GET	`/api/v1/phone/directory`	号码簿（公开目录）
POST	`/api/v1/phone/apply`	开户申请（送体验额度）
POST	`/api/v1/phone/register`	绑定号码（admin）
POST	`/api/v1/phone/deactivate`	停用号码（admin）

号段（registry，admin）

方法	路径	说明
GET	`/api/v1/number-ranges`	号段列表
POST	`/api/v1/number-range/grant`	授权号段给 org（admin）

额度计费（registry）

方法	路径	说明
GET	`/api/v1/phone/credits?did=`	余额查询
POST	`/api/v1/phone/credits/purchase`	充值下单（¥1/¥10/¥100）
POST	`/api/v1/phone/credits/confirm`	确认支付入账
POST	`/api/v1/phone/credits/consume`	扣费（服务端内部，需鉴权）
GET	`/api/v1/phone/credits/ledger?did=`	账单流水

RCS 消息 / 群（rcs-server，`/rcs` 前缀）

方法	路径	说明
POST	`/rcs/api/v1/phone/message`	发送消息
GET	`/rcs/api/v1/phone/messages?did=`	收件箱（增量 seq 游标）
POST	`/rcs/api/v1/phone/group`	建群
GET	`/rcs/api/v1/phone/group/list?did=`	群列表
GET	`/rcs/api/v1/phone/group/<id>/messages?since=`	群历史（增量）
POST	`/rcs/api/v1/phone/group/message`	群消息广播
POST	`/rcs/api/v1/phone/attachment`	附件上传
GET	`/rcs/api/v1/phone/attachment/<fileId>`	附件下载

四、核心端点示例

1. 号码解析（寻址）

curl "https://compliancehub.cn/api/v1/phone/resolve?number=%2B86951230001"

{"number":"+86951230001","registered":true,"agentDid":"did:cha2a:agent:dshlib",
 "trust":{"level":2,"name":"L2 source"},"suspicious":false}

2. 信任查询（等级 + 状态）

curl "https://compliancehub.cn/api/v1/trust/query?did=did:cha2a:agent:dshlib"

{"did":"did:cha2a:agent:dshlib","registered":true,"active":true,"level":2,
 "levelName":"L2 source","revoked":false,
 "metadata":{"name":"dshlib","author":"演示操作员","agentPublicKey":"..."}}

3. 凭证/证据查询（可追溯）

curl "https://compliancehub.cn/api/v1/evidence/query?did=did:cha2a:agent:dshlib"

{"subject":"did:cha2a:agent:dshlib","count":1,
 "credentials":[{"id":"cred-...","subject":"did:cha2a:agent:dshlib",
  "predicateType":"https://in-toto.io/attestation/test-result/v0.1",
  "verifier":"did:cha2a:verifier:dshlib","result":"passed", ...}]}

4. 身份文档（DID Document）

curl "https://compliancehub.cn/api/v1/did/did:cha2a:agent:dshlib"

{"@context":["https://www.w3.org/ns/did/v1","https://w3id.org/security/suites/ed25519-2020/v1"],
 "id":"did:cha2a:agent:dshlib",
 "verificationMethod":[{"id":"did:cha2a:agent:dshlib#registry-key","type":"Ed25519VerificationKey2020",...}]}

五、信任等级（L0-L4）

等级	名称	语义
L0	未认证	未声明
L1	integrity	身份锚定密钥验签（#agent-key，出站签名可验）
L2	source	归属绑定（owner-binding + 号段授权）
L3	issuance	背书链（发行方/验证方签发）
L4	ecosystem	多方独立验证（预留）

六、错误码

码	含义
400	参数错误（无效 DID/号码）
401	缺少/错误管理员密钥（写操作）
404	不存在（未注册/号码不在簿）
409	冲突（重复注册/已撤销）
402	余额不足（消息计费）

七、接入示例（伪代码，任意语言）

function verifyAgent(did):
    t = GET /api/v1/trust/query?did=did
    if not t.registered or t.revoked: return REJECT
    if t.level < 2: return REJECT           # 门禁：L2+ 才放行
    e = GET /api/v1/evidence/query?did=did  # 可选：看验证证据
    return ALLOW(t.level)

---

*开放契约，欢迎任何平台接入。写操作鉴权与签名规范见 CHA2A 规范（did-method-cha2a）。*