版本历史
API 以 /v1 路径区分版本，破坏性变更使用新前缀，不静默改变 /v1。Webhook 独立版本管理。当前规范：v2.4.0。
版本历史
v2.4.0最新版
- 新增获授权的 OpenAPI 会员可在 api-testing.tongkhoesim.com 创建 tke_member_test_ 密钥，并使用虚拟余额、模拟订单/eSIM、示例和场景。密钥管理区分正式/测试；测试数据不影响真实钱包、历史、等级或发票。
- 说明会员批量订单和 Webhook 仍不支持。退款审核仅支持正式模式，测试取消会退回虚拟余额。会员 seed/reset 需要 Idempotency-Key，reset 需要 reason。测试不会调用真实供应商或开具真实 MISA 发票。
v2.3.0稳定版
- 新增管理员授权的部分会员可以使用真实 Open API 密钥。订单、钱包、退款和发票仍归会员所有。协商的专属价格为最终价格，不再叠加等级折扣。
- 说明新增会员 GET/POST /v1/esims/{id}/refund-requests，以及会员订单可选的 invoice_buyer。省略购买者时保留现有消费者开票流程。批量订单、Webhook 和测试模式仍仅限组织；会员返回 capability.not_supported。
v2.2.0稳定版
- 新增eSIM Webhook（esim.delivered、esim.activated、esim.usage_threshold、esim.expiring）新增 order_id 和 external_ref，无需额外 API 即可匹配自有订单。
- 新增GET /v1/esims、GET /v1/esims/{id} 和 items[] 新增 external_ref，可用 ?external_ref=… 查询订单全部 eSIM，仍可用 ?iccid=… 查 id。
- 新增POST /v1/testmode/esims/{id}/simulate 模拟 status enabled 时，与正式订单一样仅触发一次 esim.activated。
- 说明/v1/catalog/packages 价格与组织实际扣款完全一致，包含合同专属价格。
- 说明向后兼容，仅新增字段，不更改或删除。external_ref 始终存在，未填写时为 null。
v2.1.0稳定版
- 新增组织供应商范围限制目录、详情、订单和 plan-options；范围外返回 partner.package_not_visible / order.package_not_allowed。列表提示 filtered_by_provider_scope，catalog.updated 仅含范围内 SKU，不泄露供应商。
- 说明向后兼容，未设置范围的组织无变化。
v2.0.0稳定版
- 新增/v1 统一响应：{items, next_cursor, page_size, total, mode, warnings[]}，每个实体含 id，金额 {amount, currency}，统一 usage{}，安装信息需 ?include=lpa，新增 cancellable{allowed,reason,disclosed_at}。topup-options/topup 改为 plan-options/change-plan。
- 新增测试主机 api-testing.tongkhoesim.com 仅收 tke_test_，正式仅收 tke_live_，主机错误返回 403 partner.wrong_host。新增 /v1/testmode/* 的 status、seed、reset、esims/{id}/simulate、webhooks/fire、webhooks/fail-next，以及首密钥自动示例与定期流量增长。
- 说明此版本前尚无已集成合作伙伴，契约自此开始稳定。