eSIM API 检查清单 (2026)：旅行 eSIM API 必须具备的 12 项功能 —— 以及如何测试每一项

Q: TripoSIM API 支持白标交付吗？

支持。您可以接收激活码和 QR 数据，因此可以在您自己的应用或邮件中以您的品牌交付 eSIM。请查看 API 计划。

快速回答

一个可用于生产环境的旅游 eSIM API 应该提供：安全的 token 身份验证、确保重试不会导致重复扣费的幂等键（idempotency keys）、锁定价格的价格报价、针对每个 eSIM 事件的签名 Webhook、一个可以模拟完整 eSIM 生命周期和错误情况的沙盒环境、充值功能、用量数据、暂停/恢复功能，以及包含覆盖范围和公平使用详情的产品目录。在正式上线前，请务必在沙盒中测试每一项功能。

将 eSIM API 连接到您的应用、旅游平台或预订引擎并不难。难的是在上线后才发现：API 在超时时会重复扣费、无法告知客户流量何时用尽，或者根本没有办法测试故障情况。

这份清单涵盖了在生产环境中至关重要的 12 项功能，并针对每一项说明了在签约前如何进行测试。我们以 TripoSIM Partner API 作为示例，但您也可以使用同样的清单来对比任何供应商。

1. 安全的 token 身份验证

寻找目标： OAuth 2.0 客户端凭据：您通过交换 client ID 和 secret 来换取一个短期的 access token。Secret 不会随每次请求发送。

如何测试： 请求一个 token，然后检查它是否会过期。在 TripoSIM API 中，POST /auth/token 返回的 access token 有 15 分钟的有效期。请确保您的代码在它过期前自动刷新。

2. 幂等键（防止重复扣费）

寻找目标： 在每个订单和充值请求中都包含一个 Idempotency-Key 请求头。如果您的请求超时且您使用相同的 key 进行重试，API 必须返回原始结果，而不是创建第二个已付费的 eSIM。

如何测试： 使用相同的 key 发送两次相同的订单，并确认您只获得一个订单。然后使用相同的 key 但发送不同的请求体——优秀的 API 会拒绝它。TripoSIM 要求在生产订单和充值中使用该 key，如果使用不同的请求重复使用 key，它会返回 409 IDEMPOTENCY_KEY_REUSED。

3. 锁定价格的价格报价

寻找目标： 一种获取价格并将其保持短时间的方法，以便您的客户支付的金额与您展示的金额完全一致。

如何测试： 创建一个报价，等待一段时间，然后使用该报价进行下单。TripoSIM 的报价有效期为 10 分钟；过期的报价会返回 409 QUOTE_EXPIRED，这样您可以重新报价，而不是收取一个令人意外的价格。

4. 清晰的产品目录

寻找目标： 一个可以列出所有套餐的端点，包含价格、流量、有效期、覆盖国家、5G 支持、充值支持——以及对于无限量套餐，每日全速流量限制。

如何测试： 获取一个国家的目录并将其与供应商自己的网站进行对比。TripoSIM 的 /catalog 端点返回 JSON 或 CSV，包含覆盖该国的区域套餐，并为无限量套餐添加了公平使用字段 (fup_daily_mb, fup_throttle_kbps)。查看 [无限量每日限制是如何运作的](/blog/unlimited-esim-daily-limit-by-country-2026)。

5. 即时订单和 QR 交付

寻找目标： 订单响应（或几秒钟后的 Webhook）应包含标准 LPA 格式的激活码，例如 `LPA:1$smdp.example.com$ACTIVATION_CODE`，这样您就可以显示 QR 码或一键安装链接。

如何测试： 下一个沙盒订单，从 LPA 字符串生成 QR 码，并使用手机摄像头扫描，以检查格式是否有效。

6. 针对每个事件的签名 Webhook

寻找目标： 针对整个 eSIM 生命周期的推送通知，且经过签名以防止攻击者伪造。

TripoSIM 发送八种事件类型：order.completed, order.failed, esim.activated, esim.usage_80, esim.suspended, esim.resumed, esim.depleted 和 esim.expired。每个请求都携带一个 X-TripoSIM-Signature 请求头——这是使用您的签名密钥对时间戳和原始请求体进行 HMAC-SHA256 计算的结果：

<pre><code>// reject requests older than 5 minutes (replay protection) if (Math.floor(Date.now() / 1000) - parseInt(timestamp) > 300) throw new Error('Webhook too old'); const expected = crypto .createHmac('sha256', signingSecret) .update(timestamp + '.' + rawBody) .digest('hex'); if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) { throw new Error('Invalid webhook signature'); }</code></pre>

如何测试： 注册一个 Webhook，触发一个订单，并在您的代码中验证签名。然后修改请求体的一个字节，确保您的检查逻辑会拒绝它。

7. 模拟整个 eSIM 生命周期的沙盒

寻找目标： 真实的 eSIM 需要几天时间才能激活并使用数据。一个好的沙盒可以让您“快进”。

Ready to get connected?

Get a travel eSIM for 200+ destinations — instant QR by email, no roaming charges, with a discount applied automatically at checkout.

Browse eSIM plans

如何测试： 在 TripoSIM 沙盒中，使用 action 参数为 activate, usage, deplete, expire 或 reset 来调用 POST /sandbox/esims/{iccid}/simulate。每一步都会触发相应的 Webhook，因此您可以在几分钟内而不是几天内测试您的“您的流量快用完了”邮件提醒。

8. 故障模拟

寻找目标： 一种故意强制产生错误的方法，以便您知道您的应用如何处理这些错误。

如何测试： 发送带有如下模式的 X-Sandbox-Simulate 请求头：insufficient_balance, price_changed, rate_limit, provider_unavailable 或 timeout，并检查您的应用是否显示了清晰的消息，并且仅在应该重试时才进行重试。

9. 对同一张 eSIM 进行充值

寻找目标： 流量用尽的客户应该能够增加流量，而无需安装新的 eSIM。

如何测试： 在沙盒中调用 POST /esims/{iccid}/topup（带上幂等键），然后检查新的流量余额。同时检查哪些套餐支持充值——目录应该会告诉你。

10. 用量和状态数据

寻找目标： 一个可以查询已用流量、剩余流量和过期时间的端点，以便您的支持团队和应用可以回答“我还有多少流量？”

如何测试： 在模拟用量事件后调用 GET /esims/{iccid}/usage。TripoSIM 会缓存 5 分钟的用量数据，因此请使用 Webhook (esim.usage_80, esim.depleted) 来获取实时提醒。

11. 暂停与恢复

寻找目标： 一种暂停 eSIM 的方法——例如当支付发生争议或客户报告手机丢失时——并在稍后恢复它。

如何测试： 暂停一个沙盒 eSIM，确认收到 esim.suspended Webhook，然后恢复它并确认收到 esim.resumed。

12. 清晰的频率限制、错误代码和更新日志

寻找目标： 文档化的限制说明、能告知您是否可以重试的错误代码，以及一个公开的更新日志，确保更新不会让您感到意外。

如何测试： 阅读错误列表，并在您的代码中将每个代码映射为“重试”或“不要重试”。TripoSIM 每个合作伙伴账户每分钟允许 120 次请求（您可以为单个 API 密钥设置更低的限制），在返回 429 响应时会携带 Retry-After 请求头，并将每个错误代码标记为可重试或不可重试，并发布更新日志端点。

一个简单的上线计划

第 1 天： 获取沙盒密钥，进行身份验证，拉取产品目录。
第 2 天： 使用幂等键在沙盒下订单并展示 QR 码。
第 3 天： 添加 Webhook，运行生命周期和故障模拟器。
第 4 天： 添加充值和用量功能，然后在配备一张真实 eSIM 的手机上进行测试。
第 5 天： 正式上线。

大多数团队在不到一周的时间内就能完成连接。阅读完整的 [API 文档](https://docs.triposim.com) 或查看我们的逐步 [eSIM API 集成指南](/blog/esim-reseller-api-how-to-integrate-travel-esim-sales-into-your-platform)。

常见问题解答

旅游 eSIM API 应该包含哪些内容？

至少应包含：token 身份验证、幂等键、价格报价、产品目录、即时 QR/激活码、签名 Webhook、带有生命周期和故障模拟器的沙盒、充值功能、用量数据、暂停/恢复功能，以及文档化的频率限制和错误代码。

为什么幂等键对 eSIM API 很重要？

每个 eSIM 订单都涉及真实的资金。如果请求超时且您的系统进行了重试，幂等键可以确保重试返回的是第一次的结果，而不是购买第二个 eSIM。

我如何在不购买 eSIM 的情况下测试 eSIM API？

使用沙盒。一个好的沙盒可以模拟订单、激活、数据使用、耗尽和过期——并允许您强制产生错误——而不会扣除您的钱包资金。

eSIM API 集成需要多长时间？

凭借文档齐全的 API 和功能完备的沙盒，大多数团队可以在 3–5 个工作日内上线。

TripoSIM API 支持白标交付吗？

支持。您可以接收激活码和 QR 数据，因此可以在您自己的应用或邮件中以您的品牌交付 eSIM。请查看 [API 计划](/api-program)。

总结

价格很重要，但对于 eSIM API 来说，真正的区别在于上线之后：永不重复扣费的重试机制、您可以信任的 Webhook，以及一个让您能够先行测试一切的沙盒。在做出决定前，请针对任何供应商运行此清单——并[从我们的沙盒开始](/api-program)，看看 TripoSIM Partner API 的表现如何。