09 API 与外部集成

09.1 接口原则

接口采用“契约优先、版本受控、身份可验证、失败可恢复、结果可对账”的原则。内部服务以版本化 Proto/gRPC 为主；对外 HTTP、文件、消息或其他协议以经双方批准的接口规范为准。

每个接口必须明确提供方、使用方、用途、协议、版本、认证、授权、字段、数据分类、超时、重试、幂等、错误码、审计、测试环境和上线责任人。

09.2 API 设计要求

• 已发布字段编号或字段语义不得随意复用；破坏性变更采用新版本或明确迁移窗口。
• 金额、币种、时间、标识、状态和错误码必须有唯一的机器可读语义。
• 列表查询应分页、限制最大结果并稳定排序；敏感批量导出应加强授权和审计。
• 请求与响应不得包含 Secret、私钥、长期令牌或不必要的个人数据。
• 服务端从已验证证书或受信任令牌提取调用身份；请求体字段不能替代授权。

09.3 幂等、超时与错误处理

发行、转账、赎回、审批、外部回调和批量处理必须使用稳定幂等标识。相同请求重复提交应返回既有结果或处理中状态；相同标识但不同请求必须拒绝。

所有出站调用必须设置 deadline。只对明确可重试、幂等的暂时性失败实施有限次数的退避重试；认证失败、规则拒绝、参数错误和永久性冲突不得自动重试。错误响应提供稳定错误码、对调用方安全的说明和关联追踪标识。

09.4 外部集成范围

集成域	目标	前置条件
RTGS/会计	发行、赎回、结算、会计关联与对账	已批准接口、会计规则、测试环境和责任人
商业银行/PSP	机构接入、钱包/支付服务、业务与状态查询	准入、证书、网络、协议和业务规则
CA/KMS/HSM	身份、证书、密钥与签名	设备/服务选型、权限、网络和审计策略
监控/告警	日志、指标、追踪、安全和运行事件	采集协议、保留期、访问控制和运营组织
其他甲方系统	通知、监管报送、目录或身份服务（如适用）	范围、数据最小化、合规和联调计划

09.5 联调与上线

接口上线前应完成契约评审、字段映射、认证联调、正常/异常用例、幂等和重复报文测试、性能边界验证、数据对账、日志追踪、回退预案和双方签认。

模拟接口可用于早期开发，但正式验收必须注明模拟与真实接口覆盖范围。因外部系统未就绪无法执行的用例，应记录前置条件、替代证据和后续验证计划。

09.6 互操作限制

对公有链、外部 CBDC/DLT、跨境或外汇系统的互操作不得默认启用；有关资产表示、跨链桥、最终性、AML/制裁筛查、数据出境、汇率和争议处理必须按第 16 章另行确认。