集成 eSIM API
使用 eSIM API 购买流量套餐并从您的应用交付安装详情。您需要一个工作区、一个 API 密钥以及组织钱包余额才能进行正式购买。请遵循身份验证流程，并使用与您的密钥匹配的 API 区域。
为密钥授予 esim:read 以查看套餐和资源，授予 esim:write 以进行购买或管理服务。安装凭据有单独的权限：esim_credentials:read 用于获取凭据，esim_credentials:write 用于创建或发送安装链接。请将 API 密钥保存在您的服务器应用中。
1. 选择套餐
针对目的地列出套餐，然后获取所选套餐。检查 zone.countries、pricing 中的流量额度和有效期、速率条款以及是否包含电话服务。对于已有的 eSIM，使用列出兼容套餐；目录中的通用可用性并不代表充值兼容性。
在收集订阅者信息之前，先获取套餐的身份验证要求。响应包含每个覆盖国家的 JSON Schema，要求提供名、姓和电子邮件，以及其他附加字段。请启用电子邮件和日期格式验证。您自行收集和验证这些信息；eSIM API 不会接收或核实答案，验证成功也不构成购买授权。
对于新的 eSIM，获取结账选项。在接受购买之前，显示返回的一次性价格或可用的周期性报价。结账价格为税前价格。续订有自己的价格和周期；当客户选择续订时，请参阅周期性套餐。
对于以下一次性购买示例，请安装 curl 和 jq。将 BIRD_API_URL 设为您的区域 base URL，BIRD_API_KEY 设为您的密钥，ESIM_OFFER_ID 设为所选套餐 ID：
curl --fail-with-body --silent --show-error \
"$BIRD_API_URL/v1/esim/offers/$ESIM_OFFER_ID/checkout" \
-H "Authorization: Bearer $BIRD_API_KEY" \
> esim-checkout.json
jq '.one_time' esim-checkout.json在继续之前，请检查价格和套餐条款。报价不保留库存。
2. 创建购买
使用 offer_id 创建订单。新配置文件时省略 esim_id；充值时包含它。对于一次性购买，从已接受的报价中发送 offer_revision 和 expected_price。这些字段会在扣费前以 409 拒绝已变更的条款；在接受变更后的价格之前，请获取并检查最新报价。
将 ESIM_ORDER_KEY 设为此次购买的唯一值，并与请求一起保存。以下示例购买一个新的、未分配的 eSIM，并直接复制发布的价格，不更改金额或币种：
jq '{offer_id, offer_revision: .one_time.offer_revision, expected_price: .one_time.price}' \
esim-checkout.json > esim-order.json
curl --fail-with-body --silent --show-error \
"$BIRD_API_URL/v1/esim/orders" \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $ESIM_ORDER_KEY" \
--data-binary @esim-order.json要在交付完成时分配新的配置文件，请包含工作区 subscriber_id；参阅订阅者设置。充值会保留现有分配，因此发送 esim_id 时省略 subscriber_id。安装详情需在交付后单独发送。
保存返回的订单 ID。即使在 HTTP 201 之后也要检查 status，其中可能包含已完成或已失败的订单。HTTP 202 表示处理仍在继续。获取订单直到状态变为 completed 或 failed。已完成的订单会标识 esim_id 和 package_id；设备安装仍是单独的步骤。
3. 提供安装详情
购买完成后，读取安装凭据、创建托管安装链接，或通过电子邮件或 SMS 发送链接。请勿将激活详情和安装链接记录到分析系统或公开日志中。
对于已发送的链接，保存投递 ID 并查看投递历史。202 响应表示已接受发送；delivered 表示消息已送达，设备安装需要单独检查。支持的方式、链接过期和恢复请参阅安装指南。
4. 恢复中断的购买
如果创建响应丢失或返回了 503，使用原始 Idempotency-Key 重新发送已保存的请求；参见幂等请求。如果你已有订单 ID，先读取该订单。在结果不确定时再次创建购买可能导致重复扣费。
对于处于 charging 状态的订单，检查 funding 和你的钱包余额。funding.required_amount 是所需的总余额（含税）；在充值前将其与现有余额比较。一次性订单会自动重试扣款。如果初次周期性购买因余额不足被拒绝，请充值后使用原始密钥显式重试同一创建请求。
即使在 funding.lapses_at 之后也要检查当前订单状态：该时间戳不能保证取消成功。如果订单在下一次余额不足尝试失败之前收到资金，仍然可能完成。
要停止不需要的未扣款购买，请取消订单。成功的未扣款取消会返回 status: failed 和 failure_code: canceled。已扣款的一次性订单会返回 409 并继续处理。对于初次周期性购买，取消期间恢复的付款可能导致已付费购买继续生效而未来的续订停止。在报告取消或退款之前，请检查返回的订单和订阅。
对于失败的购买，检查 failure_code 和 failure_reason。任何扣款会自动退还；refund_transaction_id 标识已发出的退款。如果付款、交付或退款仍未解决，请保留订单 ID 以联系支持。
5. 显示余额和服务状态
获取 eSIM 可查看状态、安装状态、套餐和 available_actions。使用用量指南展示套餐的配额、消耗量和观测时间。未知的消耗量在你的应用中必须保持未知。
在客户操作时重新检查操作可用性；系统会再次检查权限和状态。使用操作指南排查未完成的购买、安装问题或连接故障。