约定

金额和流量 - 字符串

{
  "balance": "124.30",
  "currency": "USD"
}
{
  "purchased_gb": "25.000",
  "used_gb": "2.566",
  "left_gb": "22.434"
}

请解析为 decimal，不要用 float。币种为 USD。1 GB = 10^9 字节。

带显式偏移量的 ISO-8601，始终为 UTC：2026-08-28T14:03:11+00:00。

订单状态、交易类型、事件类型、套餐状态、kind、family 会在 v1 内不另行通知地新增取值 - 你的代码需要能处理未知值。在筛选参数中，未知值视为“不筛选”。

参数	含义
`offset`	跳过的行数；默认 0
`limit`	1..200，默认 50（`GET /api/v1/packages` 为 200）

两者超出范围时会被截断而不是拒绝，并在响应体中返回截断后的值。响应中包含 total。

GET /api/v1/orders?limit=100&offset=100
    -> { "orders": [...], "total": 317, "offset": 100, "limit": 100 }

对于持续写入的列表，offset 指向的是位置：完整导出时请按 id 去重。排序固定 - 最新的在前。

事件日志的读取方式不同：?after=<id>，响应中包含 next_after。

扣款操作需要该请求头：POST /api/v1/packages（购买）、 POST /api/v1/packages/{id}/topup（加购流量）和 POST /api/v1/packages/{id}/prolong （地址续期）。

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

最长 255 个字符的字符串，首尾空格会被去除。

使用相同的键和相同的请求体重试，返回相同的响应。请在请求前生成键，并在重试时复用，包括超时后的重试。

键保留 24 小时：一天之后使用同一个键会开始一个新操作。

错误：

422 - idempotency_key_required（缺少请求头），idempotency_key_invalid（为空或超过 255 个字符），idempotency_key_reused（同一个键搭配了不同的请求体）
409 - idempotency_in_progress（上一个请求仍在执行 - 请稍后使用同一个键重试）
500 - operation_indeterminate（使用了一个结果未确定的操作的键重试 - 见错误）

地理目录的各个层级都返回 ETag - 目录版本的不透明哈希。在 If-None-Match 中发送它，即可获得不带响应体的 304。同一版本的可读形式位于响应体的 version 字段。

在 v1 中不另行通知地发布： 响应中的新字段、新的可选参数、可扩展枚举的新取值、新的端点、已有状态码上的新错误代码。

仅在新版本中发布： 删除或重命名字段、收窄类型、请求中新增必填字段、已描述情形的状态码或错误代码变更、默认值变更。

弃用：通过 Deprecation 和 Sunset 响应头通知，距离下线不少于 6 个月。