在应用中嵌入 eSIM 连接功能
使用本指南将 eSIM 购买与应用中的账户关联。你需要一个 Bird 工作区、一个服务端 API 集成，以及一种验证客户身份的方式。有关权限和请求详情，请参阅 API 指南。
1. 展示客户可用的套餐
根据客户的目的地列出套餐，并展示所选套餐的覆盖范围、流量额度、有效期和公开价格。购买前请检查设备兼容性和身份识别要求。
如需自动续订，使用套餐的结账选项来展示可用的购买模式和接受条款。将套餐版本和报价与客户的选择一起保存。如果报价发生变化，展示新条款并要求客户在购买前确认接受。
2. 将购买与客户关联
将 Bird API 密钥保存在服务端。使用应用的客户账户授权对每个订单和 eSIM 的访问；工作区 API 密钥可以访问属于多个客户的资源。
将客户 ID 与订单 ID 一起存储，交付后再存储 eSIM 和套餐 ID。如果需要具名服务用户或自动续订，请从工作区联系人创建订阅者。分配记录的是谁在使用该 eSIM，而不会将该用户登录到你的应用或授予凭据访问权限。
组织钱包为 Bird 购买提供资金。如果你单独向客户收费，请将该付款与 eSIM 订单分开跟踪，以便在付款或交付失败时进行处理。
3. 创建一个可恢复的购买
在创建订单之前生成并存储一个 Idempotency-Key。如果响应中断，使用同一个密钥重新提交相同的请求。
在订单达到最终结果之前显示处理中状态。在将客户引导至安装之前保存订单，并允许客户从其账户返回该订单。对于未付款或失败的订单，使用购买恢复步骤。
4. 安全交付安装说明
订单完成后，为目标客户创建托管安装链接，或通过电子邮件或 SMS 发送链接。按照安装指南处理交付、过期、撤销和设备设置。
将链接和激活详情视为凭据。不要将其记录在分析工具、公开日志和常规支持备注中。将购买完成、链接交付和设备安装作为独立的结果分别记录。
如果要替换现有的连接服务，请规划一次新的 Bird eSIM 购买和安装。在客户更改现有服务之前，检查目标设备和套餐。Bird eSIM API 不会导入现有配置文件或转移手机号码。
5. 添加用于持续使用的账户页面
允许已认证的客户重新打开其现有 eSIM，查看已报告的套餐余额和到期时间，以及联系支持。准确显示余额时间戳和未知值。
使用兼容套餐进行充值，并根据 eSIM 的 available_actions 决定显示哪些控件。使用返回的原因解释被禁用的操作，并在提交前可用性发生变化时处理拒绝。按照循环套餐指南处理续订和取消。
验证中断与恢复
购买后关闭浏览器，重新打开客户的账户。确认能够找到同一个订单和 eSIM。安装开始后重复此操作。
检查丢失的购买响应、过期的安装链接和未知的用量值是否都能引导至适当的恢复操作。验证一个客户无法通过您的账户页面打开另一个客户的安装链接或 eSIM。