Open API 文档
Open API 面向合作伙伴以及经管理员授权的会员。您的系统通过 /v1 查询目录、创建和读取订单、获取 eSIM 资料（ICCID + LPA 安装码）、跟踪用量，并通过 REST 定期轮询对账。付款从密钥所有者的钱包扣除，所有者可以是组织或会员。Webhook 面向组织；会员价格和发票遵循自主集成指南中的会员 OpenAPI 流程。
API 概览
30 项操作
共 6 组：目录 · 订单 · eSIM · 钱包 · Webhook · 测试模式。
统一身份验证
包括 GET 在内的请求均需使用 4 个 X-TKE-* 头进行 HMAC-SHA256 签名，不支持免签访问。
统一响应格式
使用 { ok, data } 或 { ok, error }，配合正确 HTTP 状态，错误绝不返回 200。
91 个公开错误码
每个错误码均附有后端注册表中的 HTTP 状态及重试标志。
8 种 Webhook 事件
通过 POST /v1/webhooks 配置，使用独立签名密钥，至少投递一次，并保留日志供重放。
独立主机测试模式
api-testing.tongkhoesim.com 仅接收 tke_test_，提供虚拟钱包、库存、确定性模拟发放及自动流量。准备完成后切换正式主机与 tke_live_。
text
https://api.tongkhoesim.com/v1 # 正式
https://api-testing.tongkhoesim.com/v1 # 测试模式正式环境：api.tongkhoesim.com / tke_live_（合作伙伴）或 tke_member_live_（已获授权会员）。测试：api-testing.tongkhoesim.com / tke_test_ / tke_member_test_（合作伙伴／会员）。
4 步接入
1. 创建测试密钥
在测试模式中创建 tke_test_，立即保存仅显示一次的密钥。首个测试密钥自动生成 3 个不同状态的示例订单，测试钱包可无限充值。
2. 在测试主机下单
使用 HMAC 签名并调用 POST https://api-testing.tongkhoesim.com/v1/orders，立即获取 ICCID 以 8999 开头的模拟 eSIM，不影响真实库存和资金。可用控制台或 Postman 测试。
3. 注册并测试 Webhook
通过 POST /v1/webhooks 注册 URL，CHECK_HEALTH 必须返回 2xx。使用 /v1/testmode/webhooks/fire 触发事件，/fail-next 测试重试。
4. 切换正式密钥
创建 tke_live_，保持代码不变，只切换主机、key_id 和 secret。Webhook 按 api_key_id 隔离，须为正式密钥单独注册。
3 个关键集成陷阱
以下三点可能通过测试，却在真实付款或对账时才暴露问题。
Idempotency-Key 按 API 密钥隔离
去重范围为 api_key_id。同一组织使用两个密钥发送相同 Idempotency-Key，会产生两笔订单和两次扣款。每个下单流程应固定密钥或包含 key_id。
REST 的 id 与 Webhook 的 order_item_id
REST 中 eSIM 的 id 与 Webhook 的 order_item_id 是同一 UUID，order_id 指向父订单。请使用 UUID 存储，ICCID 可能被复用。GET /v1/esims?iccid=… 可查 id。下单时发送 external_ref，REST 和 eSIM Webhook 会连同 order_id 返回，也可用 ?external_ref=… 查找关联 eSIM。
正确结束游标分页循环
GET /v1/orders 和 /v1/esims 使用游标。无效游标不会报错，而会返回起点。next_cursor 缺失或等于当前游标时必须停止，仅检查 !== null 会导致死循环。