连接你的业务系统

1 · 换取访问令牌

在用户端“开发者”创建凭证。API Key 只显示一次；不要放入前端代码。

令牌有效期最多 30 分钟。撤销、轮换凭证或撤销创建人的登录权限后，已有令牌立即失效。

2 · 选择租户与权限

资源请求使用 Authorization: Bearer。可用 x-tenant-id 指定所属租户；凭证若限定租户或环境，不能通过参数切换。权限不足返回 403。

3 · 安全地重试

创建租户、持卡人、卡片、加额和卡片状态变更需要 UUID v4 的 Idempotency-Key，或正文 request_id；同时提供时必须一致。同一业务重试保留原编号和参数。202 表示已受理但结果待核对，读取卡片/申请状态，不要换编号重复开卡。

列表使用从 0 开始的 page_num 和 1–100 的 page_size，has_more 表示还有下一页。金额以币种主单位传入，推荐十进制字符串；带 minor 后缀的字段为最小货币单位整数字符串。

资源请求默认每客户端每分钟 120 次，换取令牌每分钟 10 次。429 时按 Retry-After 等待。响应带 X-Request-Id；错误返回 code、message、request_id。

完整卡号、CVV 和安全展示 token 只允许临时使用，不应记录日志或持久化。实际可展示性取决于卡片状态和发卡服务权限。