查看用量并充值
使用本指南为现有 eSIM 添加流量。您需要读取该 eSIM 和购买套餐的权限，以及充足的钱包余额。充值是否可用取决于配置文件、现有套餐和所选方案。
1. 查看当前生效的套餐
从 eSIMs 打开配置文件，查看数据套餐。通过 API，列出该 eSIM 的套餐并检查其状态、到期时间和余额。
balance.total_bytes 是已购买的流量额度。used_bytes、remaining_bytes 或 used_percent 为 null 表示没有可用的测量数据。在应用中将这些值保持为未知状态。
读取 eSIM 的 balance_reporting 字段以决定显示内容。如果值为 unavailable，则显示已购买的流量额度，不要将其呈现为实测剩余数据。如果值为 available，在收到报告之前消耗量仍可能未知。每日用量历史是独立的，目前不可用。
使用 balance.as_of 获取最近一次余额更新时间；在上报消耗数据之前，该值可能是套餐交付时间。balance.observed_at 是网络测量时间（如果提供）。将时间戳与实测用量一起显示，以便客户识别延迟的报告。
2. 列出兼容的可选方案
在 eSIM 上选择 Top up，或为该配置文件调用列出兼容的可选方案。使用返回的方案，而不是从通用目录中自行选择。覆盖相同国家并不代表兼容。
如果充值不可用，请读取 eSIM 上的 available_actions 了解原因。未完成的订单或套餐数量限制可能阻止再次购买。请先处理现有订单，然后重试。提交前请刷新兼容套餐列表：套餐可能在选择和购买之间变为不可用。
处于 expired 状态的 eSIM 是休眠的，在完成兼容充值后可以恢复到 active 状态。在判定已安装的配置文件需要替换之前，先检查可用操作和兼容套餐。
3. 查看生效条款
显示所选套餐的流量额度、覆盖范围、公布价格和币种以及有效期。将新套餐的有效期与 eSIM 的 active_until 服务边界（如果存在）进行比较。如果该边界会缩短已购买的有效期，订单将返回 409 及实际有效期。显示较短的有效期并在设置 acknowledge_shortened_validity: true 之前获得用户确认。
充值会创建一个新套餐，不会更改现有套餐的余额或延长其到期时间。交付后请检查新套餐的激活时间和到期时间。
4. 批准并跟踪订单
在控制面板中确认购买。通过 API，使用现有的 esim_id、所选的 offer_id、套餐的 revision 作为 offer_revision、以及其 pricing.price 作为 expected_price 来创建订单。省略 subscriber_id；充值保留现有分配。保存订单 ID 和 Idempotency-Key 以便重试。
如果已接受的价格或版本发生变化，请获取当前套餐并在提交新购买之前确认新条款。直接复制返回的价格金额和币种，不要进行转换或四舍五入。
在 Orders 中跟踪订单，或通过 API 获取订单。在收到 201 和 202 响应后检查 status。如果响应丢失，请使用相同的密钥重试相同的请求；在结果不确定时不要创建替代购买。
5. 检查生成的套餐
当订单为 completed 时，使用其 package_id 来获取新套餐。确认目标 eSIM、覆盖范围和流量额度与购买内容一致。充值使用已安装的配置文件，无需安装新的 eSIM。等待首次使用的套餐可能尚无激活或到期时间戳。
故障排除
如果订单已完成但余额仍未知，请对比套餐状态和报告时间戳。上报可能滞后于设备实际用量；再次下单并不能解决该延迟。如果购买失败，请在重试前检查失败详情和退款记录编号（如有）。