企庭开放平台 · API 设计规范

CHPEN OPEN API SPECIFICATION · v1

基址 open.chpen.com 版本 /v1/ 引擎 · 驿API站只增不删 · 全程留痕

一 · 基址与版本

对外统一基址 https://open.chpen.com，版本前缀 /v1/。仅当发生破坏性变更才升版本号，字段名新增、枚举扩展不算破坏性。

内部接口 /api/backend/v1/ 与对外接口物理隔离，对外只暴露本规范登记过的路径。

二 · 路径命名

资源导向，全小写，复数：/v1/contracts、/v1/entrepreneurs
动作作为子资源：/v1/contracts/{id}/sign
一次性免登录入口：/v1/contracts/sign/{token}（token 为 64 位十六进制）
日期一律 YYYY-MM-DD，时间一律 Unix 秒

三 · 鉴权

常规调用：Authorization: Bearer <access_key>
一次性场景（短信签署）：路径内 token，一次一签、用后即废
永不使用 Cookie，响应绝不下发 Allow-Credentials

curl https://open.chpen.com/v1/entrepreneurs \
  -H "Authorization: Bearer YOUR_ACCESS_KEY"

四 · 统一响应信封

所有接口一律返回同一信封，业务数据放在 data 里：

{
  "code": 0,
  "msg": "ok",
  "data": { },
  "ts": 1760460000,
  "req_id": "req_7f3a9c21"
}

⛔ 必查响应体，不能只看 HTTP 状态码

本平台路由不存在时返回 HTTP 200 且 code=1001。 axios/fetch 不会抛错，只判状态码会把失败当成成功。客户端必须解析 code 再决定后续动作。

五 · 错误码

code	含义	处理建议
`0`	成功	取 data
`1001`	路由不存在	核对路径与版本号
`4001`	鉴权失败	检查 access_key 是否过期
`4003`	无权限	申请对应 scope
`4029`	触发限流	退避重试，勿并发硬冲
`4220`	参数不合法	按 msg 修正字段
`5001`	服务异常	携 req_id 联系支持

六 · 分页与幂等

列表接口统一 ?page=1&page_size=20， data 内含 list / total / page / page_size。

写操作支持 X-Idempotency-Key 请求头，同键重复提交只生效一次，避免网络重 trials 造成重复签署或重复记账。

七 · 限流

单 IP 默认 120 次 / 分钟，突发上限 40。超限返回 4029，响应头带 Retry-After。

八 · 安全与合规

全站 HTTPS；响应头 Cache-Control: no-store，任何环节不得缓存
手机号永不明文返回，需经 /reveal 留痕接口解密，谁在何时看过可追溯（PIPL 要求）
一切留痕只增不删；合同正文落库即冻结，任何改动可被发现
自研时间戳：每日 Merkle 根公开公示，第三方可独立复算，无需第三方时间戳机构

九 · 已上线能力

能力	方法与路径	状态
电子合同 · 短信签署	`GET/POST /v1/contract/sign/{token}`	已上线
公开时间锚定	`GET /anchor/{YYYY-MM-DD}.txt`	已上线
电子合同 · 对外验真	`GET /v1/contract/verify?hash={64hex}` `GET /v1/contract/verify?no={合同编号}`	已上线

9.1 合同验真 · 请求与响应

验真无需鉴权：任何一方（客户、合作方、监管）拿到合同哈希或合同编号即可核真伪。 输出严格脱敏——不含合同标题、正文、金额、签署人姓名与手机号。

GET https://open.chpen.com/v1/contract/verify?no=SER20261014-93DB14

{
  "code": 0,
  "msg": "ok",
  "data": {
    "contract_no": "SER20261014-93DB14",
    "template": "SERVICE_VIP",
    "status": 3,
    "status_text": "双方已签",
    "chain_ok": true,
    "signatures": [
      { "role": "A", "signed_at": "2026-10-14 21:05:55", "method": "" },
      { "role": "B", "signed_at": "2026-10-14 21:05:56", "method": "" }
    ],
    "anchor": {
      "date": "2026-10-14",
      "root": "cccafe97affb489d",
      "url": "https://open.chpen.com/anchor/2026-10-14.txt"
    }
  },
  "ts": 1791993357
}

状态取值：1 待签 · 2 单方已签 · 3 双方已签 · 9 已作废。 chain_ok=true 表示正文哈希与链式签名哈希自洽（任何改动都会变为 false）。 anchor.root 只给当日 Merkle 根的前 16 位，完整根见 anchor.url，可独立复算。

错误：哈希/编号不存在 → HTTP 404 且 code=1001；参数缺失或格式不符 → HTTP 400 且 code=4001。

十 · 企庭企业家平台 · 预留口子

以下路径已按本规范预留，结构先行锁定，后续开放时客户端无需改造。 当前一律返回 HTTP 404 且 code=1001——对外只放行已验安全的路径，规范留口子不等于现在就开，实现并验证安全后才加入放行白名单。

能力	方法与路径	说明	状态
企业家名录	`GET /v1/entrepreneurs`	分页检索，默认脱敏	预留
企业家详情	`GET /v1/entrepreneurs/{id}`	档案与资质标签	预留
联系方式解密	`POST /v1/entrepreneurs/{id}/reveal`	留痕后返回手机号	预留
商机线索	`GET /v1/opportunities`	公海→认领→跟进→合同→交易	预留
会员体系	`GET /v1/members`	等级、有效期、权益	预留
企业工商核验	`GET /v1/companies/{keyword}`	主体状态与经营范围	预留

企庭开放平台 · 由驿API站引擎纳管巡检 · 返回门户｜能力清单 JSON ｜双环状态