{
  "components": {
    "schemas": {
      "BulkBatchResponse": {
        "properties": {
          "data": {
            "description": "批量订单结果。部分成功：失败行不阻止其他行，仅对 `done` 行扣款。不含 LPA/QR，请按各 `order_id` 通过 GET /v1/orders/{id} 获取。",
            "properties": {
              "created_at": {
                "format": "date-time",
                "type": "string"
              },
              "external_ref": {
                "example": "batch-2026-001",
                "nullable": true,
                "type": "string"
              },
              "failed_lines": {
                "type": "integer"
              },
              "id": {
                "format": "uuid",
                "type": "string"
              },
              "items": {
                "items": {
                  "$ref": "#/components/schemas/BulkLineResult"
                },
                "type": "array"
              },
              "mode": {
                "$ref": "#/components/schemas/ModeEcho"
              },
              "status": {
                "description": "`pending` 表示批次中仍有未执行行（中途被中断），请使用相同 `Idempotency-Key` 再调用以完成剩余行。",
                "enum": [
                  "pending",
                  "completed",
                  "partial",
                  "failed"
                ],
                "type": "string"
              },
              "succeeded_lines": {
                "type": "integer"
              },
              "total_charged": {
                "$ref": "#/components/schemas/Money"
              },
              "total_lines": {
                "type": "integer"
              }
            },
            "type": "object"
          },
          "ok": {
            "enum": [
              true
            ],
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "data"
        ],
        "type": "object"
      },
      "BulkLineResult": {
        "properties": {
          "charged": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              }
            ],
            "nullable": true
          },
          "error": {
            "description": "实际的 `domain.reason` 错误代码，例如 `wallet.insufficient_balance`、`esim.out_of_stock`、`order.package_not_allowed`、`wallet.velocity_exceeded`。",
            "nullable": true,
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "type": "object"
          },
          "external_ref": {
            "example": "po-1001",
            "nullable": true,
            "type": "string"
          },
          "line_no": {
            "description": "从 1 开始，与提交顺序完全一致。",
            "type": "integer"
          },
          "order_id": {
            "format": "uuid",
            "nullable": true,
            "type": "string"
          },
          "package_code": {
            "type": "string"
          },
          "quantity": {
            "type": "integer"
          },
          "status": {
            "enum": [
              "pending",
              "done",
              "failed"
            ],
            "type": "string"
          }
        },
        "type": "object"
      },
      "BulkRequest": {
        "properties": {
          "external_ref": {
            "description": "整个批次的参考编号，会在批次响应中返回。",
            "example": "batch-2026-001",
            "nullable": true,
            "type": "string"
          },
          "items": {
            "description": "每个条目创建一个独立订单。行数上限可配置（默认 100），超出返回 `internal.limit_exceeded`（422）。",
            "items": {
              "properties": {
                "external_ref": {
                  "description": "仅此行的参考编号，会在该行结果中原样返回。",
                  "example": "po-1001",
                  "nullable": true,
                  "type": "string"
                },
                "package_code": {
                  "description": "您目录中的套餐代码，即 `public_sku`。每个套餐的代码不可变，更换底层供应商时也不变，因此可安全用作对账键。示例仅格式正确，无法实际调用；请从 `GET /v1/catalog/packages` 获取真实代码。",
                  "example": "TKE-VN-30D-X3K9F",
                  "type": "string"
                },
                "quantity": {
                  "example": 5,
                  "minimum": 1,
                  "type": "integer"
                }
              },
              "required": [
                "package_code",
                "quantity"
              ],
              "type": "object"
            },
            "minItems": 1,
            "type": "array"
          }
        },
        "required": [
          "items"
        ],
        "type": "object"
      },
      "CancelResponse": {
        "properties": {
          "data": {
            "properties": {
              "cancelled_at": {
                "format": "date-time",
                "type": "string"
              },
              "esim_id": {
                "format": "uuid",
                "type": "string"
              },
              "mode": {
                "$ref": "#/components/schemas/ModeEcho"
              },
              "refund_suggested": {
                "description": "`true` 表示退款申请已排队等待人工批准，资金尚未转移。不要将 `refunded.amount = 0` 解读为“不退款”。",
                "type": "boolean"
              },
              "refunded": {
                "$ref": "#/components/schemas/Money",
                "description": "此次取消时实际退回钱包的金额。正式环境中通常为 `0`，请先查看 `refund_suggested` 再作判断。"
              },
              "status": {
                "example": "cancelled",
                "type": "string"
              }
            },
            "type": "object"
          },
          "ok": {
            "enum": [
              true
            ],
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "data"
        ],
        "type": "object"
      },
      "Cancellable": {
        "description": "eSIM 是否仍可取消及原因，请在调用 `POST /v1/esims/{order_item_id}/cancel` 前读取。此区块是明确回答，始终存在，不为 `null`。",
        "properties": {
          "allowed": {
            "type": "boolean"
          },
          "disclosed_at": {
            "description": "代码离开系统的时间（ISO-8601 UTC），无人查看时为 `null`。客户声称未收到代码却无法取消时，可据此核查。",
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "reason": {
            "description": "不可取消原因：`code_disclosed`（已发送或显示代码）、`wrong_status`（状态不允许）、`expired`（已过期）、`not_supported`（未声明取消能力）。`allowed = true` 时为 `null`，与 `esim.not_cancellable` 的 `meta.reason` 使用同一代码集。",
            "enum": [
              "code_disclosed",
              "wrong_status",
              "expired",
              "not_supported",
              null
            ],
            "nullable": true,
            "type": "string"
          }
        },
        "type": "object"
      },
      "ChangePlanRequest": {
        "properties": {
          "package_code": {
            "description": "您目录中的套餐代码，即 `public_sku`。每个套餐的代码不可变，更换底层供应商时也不变，因此可安全用作对账键。示例仅格式正确，无法实际调用；请从 `GET /v1/catalog/packages` 获取真实代码。",
            "example": "TKE-VN-7D-P4M2Q",
            "type": "string"
          }
        },
        "required": [
          "package_code"
        ],
        "type": "object"
      },
      "ChangePlanResponse": {
        "properties": {
          "data": {
            "description": "eSIM 更换套餐的结果。",
            "properties": {
              "charged": {
                "$ref": "#/components/schemas/Money"
              },
              "current_plan": {
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "expires_at": {
                    "format": "date-time",
                    "nullable": true,
                    "type": "string"
                  },
                  "started_at": {
                    "format": "date-time",
                    "nullable": true,
                    "type": "string"
                  }
                },
                "type": "object"
              },
              "esim_id": {
                "format": "uuid",
                "type": "string"
              },
              "mode": {
                "$ref": "#/components/schemas/ModeEcho"
              },
              "order_id": {
                "format": "uuid",
                "type": "string"
              },
              "previous_plan": {
                "nullable": true,
                "properties": {
                  "cancelled_at": {
                    "format": "date-time",
                    "nullable": true,
                    "type": "string"
                  },
                  "code": {
                    "type": "string"
                  },
                  "remaining_bytes_forfeited": {
                    "format": "int64",
                    "nullable": true,
                    "type": "integer"
                  }
                },
                "type": "object"
              },
              "warning": {
                "type": "string"
              }
            },
            "type": "object"
          },
          "ok": {
            "enum": [
              true
            ],
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "data"
        ],
        "type": "object"
      },
      "CreateOrderRequest": {
        "properties": {
          "external_ref": {
            "description": "您的自定义引用代码，会原样回传至响应和 Webhook。",
            "example": "po-1001",
            "nullable": true,
            "type": "string"
          },
          "include": {
            "description": "请求额外区块：`[\"lpa\"]` 或 `[\"lpa\",\"qr\"]`。省略时 `items[].install` 为 `null`，订单中所有 eSIM 保留取消资格。**返回代码即披露代码**：请求 `lpa` 即接受订单创建时取消窗口立即关闭。",
            "example": [
              "lpa"
            ],
            "items": {
              "enum": [
                "lpa",
                "qr"
              ],
              "type": "string"
            },
            "nullable": true,
            "type": "array"
          },
          "invoice_buyer": {
            "$ref": "#/components/schemas/MemberInvoiceBuyer"
          },
          "items": {
            "description": "待购买套餐及数量列表（最多 50 个 eSIM）。",
            "items": {
              "properties": {
                "package_code": {
                  "description": "您目录中的套餐代码，即 `public_sku`。每个套餐的代码不可变，更换底层供应商时也不变，因此可安全用作对账键。示例仅格式正确，无法实际调用；请从 `GET /v1/catalog/packages` 获取真实代码。",
                  "example": "TKE-VN-30D-X3K9F",
                  "type": "string"
                },
                "quantity": {
                  "description": "此套餐要购买的 eSIM 数量（≥ 1）。",
                  "example": 2,
                  "type": "integer"
                }
              },
              "required": [
                "package_code",
                "quantity"
              ],
              "type": "object"
            },
            "type": "array"
          }
        },
        "required": [
          "items"
        ],
        "type": "object"
      },
      "CreateWebhookResponse": {
        "properties": {
          "data": {
            "properties": {
              "active": {
                "description": "`false` 表示已停止接收新事件，仅在组织通过后台暂停或 API 密钥被撤销时发生（同一事务内联动关闭）。通过 CHECK_HEALTH 的 `PUT /v1/webhooks/{id}` 可重新启用。",
                "type": "boolean"
              },
              "created_at": {
                "format": "date-time",
                "type": "string"
              },
              "events": {
                "description": "为空表示接收全部。",
                "items": {
                  "enum": [
                    "order.completed",
                    "order.failed",
                    "esim.delivered",
                    "esim.activated",
                    "esim.usage_threshold",
                    "esim.expiring",
                    "wallet.low_balance",
                    "catalog.updated"
                  ],
                  "type": "string"
                },
                "type": "array"
              },
              "health_check": {
                "enum": [
                  "passed"
                ],
                "type": "string"
              },
              "id": {
                "description": "端点 ID，用于 `/v1/webhooks/{id}`。每次创建都会生成新 ID，删除后重建得到的是另一个端点，而非恢复旧端点。",
                "format": "uuid",
                "type": "string"
              },
              "last_delivery_at": {
                "description": "通过此端点最后投递的时间。`null` 表示从未投递，不同于“投递失败”；合作伙伴反馈未收到 webhook 时应首先检查。",
                "format": "date-time",
                "nullable": true,
                "type": "string"
              },
              "mode": {
                "$ref": "#/components/schemas/ModeEcho"
              },
              "secret_last4": {
                "description": "Webhook 密钥的末四个字符，可用于核对手持密钥是否与系统签名密钥一致，而无需任何端点重新泄露密钥。完整密钥仅在创建时显示一次。",
                "type": "string"
              },
              "url": {
                "type": "string"
              },
              "webhook_secret": {
                "description": "仅在创建时显示一次（前缀 `whsec_`）。",
                "type": "string"
              }
            },
            "type": "object"
          },
          "ok": {
            "enum": [
              true
            ],
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "data"
        ],
        "type": "object"
      },
      "DeleteWebhookResponse": {
        "properties": {
          "data": {
            "properties": {
              "deleted_at": {
                "format": "date-time",
                "type": "string"
              },
              "id": {
                "format": "uuid",
                "type": "string"
              },
              "mode": {
                "$ref": "#/components/schemas/ModeEcho"
              }
            },
            "type": "object"
          },
          "ok": {
            "enum": [
              true
            ],
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "data"
        ],
        "type": "object"
      },
      "Delivery": {
        "properties": {
          "attempts": {
            "type": "integer"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "event_id": {
            "description": "事件标识。重放会创建一个新投递记录，但保留同一 `event_id`；请按 `event_id` 去重，不要按投递 `id` 去重。",
            "format": "uuid",
            "type": "string"
          },
          "event_type": {
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "last_attempt_at": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "next_retry_at": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "response_code": {
            "nullable": true,
            "type": "integer"
          },
          "status": {
            "enum": [
              "pending",
              "delivered",
              "failed"
            ],
            "type": "string"
          },
          "webhook_id": {
            "format": "uuid",
            "type": "string"
          }
        },
        "type": "object"
      },
      "DeliveryListResponse": {
        "properties": {
          "data": {
            "properties": {
              "items": {
                "items": {
                  "$ref": "#/components/schemas/Delivery"
                },
                "type": "array"
              },
              "mode": {
                "$ref": "#/components/schemas/ModeEcho"
              },
              "next_cursor": {
                "description": "获取下一页时请原样传回。`null` 是唯一的结束信号，即使当前页少于 `page_size` 条，也可能仍有后续页面。",
                "nullable": true,
                "type": "string"
              },
              "page_size": {
                "description": "服务器用于本页的最大记录数，已应用上限，并非 `items` 中的实际元素数量。",
                "nullable": true,
                "type": "integer"
              },
              "total": {
                "description": "符合筛选条件的记录数量。统计成本过高时为 `null`，请勿据此判断是否结束，应以 `next_cursor` 为准。",
                "format": "int64",
                "nullable": true,
                "type": "integer"
              },
              "warnings": {
                "description": "列表呈现方式的原因；无异常时为空。封闭代码集：`filtered_by_key_package_filters`、`filtered_by_provider_scope`、`no_price_for_org`、`price_filter_removed_rows`、`provider_disabled`、`capability_missing`，分别代表密钥限制、组织供应源范围、未定价、价格筛选、供应商停用、未声明功能。`count` 为涉及行数，无法量化时为 `null`。",
                "example": [],
                "items": {
                  "$ref": "#/components/schemas/ListWarning"
                },
                "type": "array"
              }
            },
            "type": "object"
          },
          "ok": {
            "enum": [
              true
            ],
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "data"
        ],
        "type": "object"
      },
      "DeliveryReplayResponse": {
        "properties": {
          "data": {
            "properties": {
              "attempts": {
                "type": "integer"
              },
              "created_at": {
                "format": "date-time",
                "type": "string"
              },
              "event_id": {
                "description": "事件标识。重放会创建一个新投递记录，但保留同一 `event_id`；请按 `event_id` 去重，不要按投递 `id` 去重。",
                "format": "uuid",
                "type": "string"
              },
              "event_type": {
                "type": "string"
              },
              "id": {
                "format": "uuid",
                "type": "string"
              },
              "last_attempt_at": {
                "format": "date-time",
                "nullable": true,
                "type": "string"
              },
              "mode": {
                "$ref": "#/components/schemas/ModeEcho"
              },
              "next_retry_at": {
                "format": "date-time",
                "nullable": true,
                "type": "string"
              },
              "response_code": {
                "nullable": true,
                "type": "integer"
              },
              "status": {
                "enum": [
                  "pending",
                  "delivered",
                  "failed"
                ],
                "type": "string"
              },
              "webhook_id": {
                "format": "uuid",
                "type": "string"
              }
            },
            "type": "object"
          },
          "ok": {
            "enum": [
              true
            ],
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "data"
        ],
        "type": "object"
      },
      "ErrorEnvelope": {
        "properties": {
          "error": {
            "properties": {
              "code": {
                "description": "`domain.reason` 格式代码（参见错误代码表）。",
                "type": "string"
              },
              "field": {
                "nullable": true,
                "type": "string"
              },
              "message": {
                "type": "string"
              },
              "meta": {
                "nullable": true,
                "type": "object"
              },
              "request_id": {
                "type": "string"
              }
            },
            "required": [
              "code",
              "message",
              "request_id"
            ],
            "type": "object"
          },
          "ok": {
            "enum": [
              false
            ],
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "error"
        ],
        "type": "object"
      },
      "Esim": {
        "properties": {
          "data": {
            "properties": {
              "cancellable": {
                "$ref": "#/components/schemas/Cancellable"
              },
              "external_ref": {
                "description": "您的订单引用（下单时发送的 `external_ref`），用于将 eSIM 对应到您的订单。未提供时为 `null`。",
                "nullable": true,
                "type": "string"
              },
              "iccid": {
                "example": "8984012345678901234",
                "nullable": true,
                "type": "string"
              },
              "id": {
                "description": "eSIM ID，用于所有 `/v1/esims/{id}/…` 路径，也就是 webhook 中的 `order_item_id`。若只有 ICCID，请调用 `GET /v1/esims?iccid=…` 获取 `id`。",
                "format": "uuid",
                "type": "string"
              },
              "install": {
                "$ref": "#/components/schemas/Install"
              },
              "mode": {
                "$ref": "#/components/schemas/ModeEcho"
              },
              "msisdn": {
                "nullable": true,
                "type": "string"
              },
              "order_id": {
                "format": "uuid",
                "type": "string"
              },
              "package_code": {
                "description": "目录中的套餐代码，用于将此 eSIM 对应回您的目录。仅当源套餐已从目录移除时为 `null`。",
                "nullable": true,
                "type": "string"
              },
              "package_name": {
                "description": "供人阅读、可能变化的显示名称。请勿用作对账键。",
                "type": "string"
              },
              "plan": {
                "$ref": "#/components/schemas/PlanView"
              },
              "smdp_status": {
                "example": "released",
                "nullable": true,
                "type": "string"
              },
              "status": {
                "example": "delivered",
                "type": "string"
              },
              "updated_at": {
                "format": "date-time",
                "type": "string"
              },
              "usage": {
                "$ref": "#/components/schemas/Usage"
              }
            },
            "type": "object"
          },
          "ok": {
            "enum": [
              true
            ],
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "data"
        ],
        "type": "object"
      },
      "EsimItem": {
        "properties": {
          "cancellable": {
            "$ref": "#/components/schemas/Cancellable"
          },
          "external_ref": {
            "description": "您的订单引用（下单时发送的 `external_ref`），用于将 eSIM 对应到您的订单。未提供时为 `null`。",
            "nullable": true,
            "type": "string"
          },
          "iccid": {
            "example": "8984012345678901234",
            "nullable": true,
            "type": "string"
          },
          "id": {
            "description": "eSIM ID，用于所有 `/v1/esims/{id}/…` 路径，也就是 webhook 中的 `order_item_id`。若只有 ICCID，请调用 `GET /v1/esims?iccid=…` 获取 `id`。",
            "format": "uuid",
            "type": "string"
          },
          "install": {
            "$ref": "#/components/schemas/Install"
          },
          "msisdn": {
            "nullable": true,
            "type": "string"
          },
          "order_id": {
            "format": "uuid",
            "type": "string"
          },
          "package_code": {
            "description": "目录中的套餐代码，用于将此 eSIM 对应回您的目录。仅当源套餐已从目录移除时为 `null`。",
            "nullable": true,
            "type": "string"
          },
          "package_name": {
            "description": "供人阅读、可能变化的显示名称。请勿用作对账键。",
            "type": "string"
          },
          "plan": {
            "$ref": "#/components/schemas/PlanView"
          },
          "smdp_status": {
            "example": "released",
            "nullable": true,
            "type": "string"
          },
          "status": {
            "example": "delivered",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          }
        },
        "type": "object"
      },
      "EsimListResponse": {
        "properties": {
          "data": {
            "properties": {
              "items": {
                "items": {
                  "$ref": "#/components/schemas/EsimItem"
                },
                "type": "array"
              },
              "mode": {
                "$ref": "#/components/schemas/ModeEcho"
              },
              "next_cursor": {
                "description": "获取下一页时请原样传回。`null` 是唯一的结束信号，即使当前页少于 `page_size` 条，也可能仍有后续页面。",
                "nullable": true,
                "type": "string"
              },
              "page_size": {
                "description": "服务器用于本页的最大记录数，已应用上限，并非 `items` 中的实际元素数量。",
                "nullable": true,
                "type": "integer"
              },
              "total": {
                "description": "符合筛选条件的记录数量。统计成本过高时为 `null`，请勿据此判断是否结束，应以 `next_cursor` 为准。",
                "format": "int64",
                "nullable": true,
                "type": "integer"
              },
              "warnings": {
                "description": "列表呈现方式的原因；无异常时为空。封闭代码集：`filtered_by_key_package_filters`、`filtered_by_provider_scope`、`no_price_for_org`、`price_filter_removed_rows`、`provider_disabled`、`capability_missing`，分别代表密钥限制、组织供应源范围、未定价、价格筛选、供应商停用、未声明功能。`count` 为涉及行数，无法量化时为 `null`。",
                "example": [],
                "items": {
                  "$ref": "#/components/schemas/ListWarning"
                },
                "type": "array"
              }
            },
            "type": "object"
          },
          "ok": {
            "enum": [
              true
            ],
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "data"
        ],
        "type": "object"
      },
      "EsimUsage": {
        "properties": {
          "data": {
            "properties": {
              "esim_id": {
                "format": "uuid",
                "type": "string"
              },
              "mode": {
                "$ref": "#/components/schemas/ModeEcho"
              },
              "usage": {
                "$ref": "#/components/schemas/Usage"
              }
            },
            "type": "object"
          },
          "ok": {
            "enum": [
              true
            ],
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "data"
        ],
        "type": "object"
      },
      "Install": {
        "description": "安装此 eSIM 所需的全部信息。`null` 表示您未请求此信息（未传 `include=lpa`），并不表示 eSIM 尚无安装代码；后者会返回此对象且 `lpa: null`。\n\n包含此对象的响应始终带有 `Cache-Control: no-store`。",
        "nullable": true,
        "properties": {
          "android_url": {
            "nullable": true,
            "type": "string"
          },
          "apn": {
            "description": "设备无法自动获取配置时需输入的接入点名称（APN）。当前版本始终为 `null`，表示“未知”，而非“不需要”。",
            "nullable": true,
            "type": "string"
          },
          "ios_url": {
            "nullable": true,
            "type": "string"
          },
          "lpa": {
            "description": "eSIM 激活码，属于可销售的机密。仅凭此字符串即可在您的系统生成二维码。",
            "example": "LPA:1$smdp.example.com$MATCH-ABC123",
            "nullable": true,
            "type": "string"
          },
          "matching_id": {
            "example": "MATCH-ABC123",
            "nullable": true,
            "type": "string"
          },
          "qr_code_base64": {
            "description": "二维码的 PNG data-URI。仅在详情端点请求 `include=qr` 时返回，列表绝不包含（每行约 11 KB，100 行约 1.1 MB）；列表中请使用 `lpa` 自行生成二维码。",
            "nullable": true,
            "type": "string"
          },
          "smdp_address": {
            "example": "smdp.example.com",
            "nullable": true,
            "type": "string"
          }
        },
        "type": "object"
      },
      "ListWarning": {
        "description": "列表呈现方式的原因；无异常时为空。封闭代码集：`filtered_by_key_package_filters`、`filtered_by_provider_scope`、`no_price_for_org`、`price_filter_removed_rows`、`provider_disabled`、`capability_missing`，分别代表密钥限制、组织供应源范围、未定价、价格筛选、供应商停用、未声明功能。`count` 为涉及行数，无法量化时为 `null`。",
        "properties": {
          "code": {
            "enum": [
              "filtered_by_key_package_filters",
              "filtered_by_provider_scope",
              "no_price_for_org",
              "price_filter_removed_rows",
              "provider_disabled",
              "capability_missing"
            ],
            "example": "no_price_for_org",
            "type": "string"
          },
          "count": {
            "example": 12,
            "format": "int64",
            "nullable": true,
            "type": "integer"
          },
          "message": {
            "example": "12 gói bị lược vì tổ chức bạn chưa có giá.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "MemberInvoiceBuyer": {
        "description": "仅适用于会员密钥。未填写时使用消费者流程，无需组织或越南法人。填写时按现有个人规则验证full_name、12位个人tax_code及结账address/email规则。企业发票在购买后申请。测试模式只验证快照，不签发MISA发票。",
        "nullable": true,
        "properties": {
          "address": {
            "nullable": true,
            "type": "string"
          },
          "email": {
            "nullable": true,
            "type": "string"
          },
          "full_name": {
            "nullable": true,
            "type": "string"
          },
          "legal_name": {
            "nullable": true,
            "type": "string"
          },
          "tax_code": {
            "nullable": true,
            "type": "string"
          }
        },
        "type": "object"
      },
      "MemberRefundRequest": {
        "properties": {
          "decided_at": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "decision_note": {
            "nullable": true,
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "order_id": {
            "format": "uuid",
            "type": "string"
          },
          "order_item_id": {
            "format": "uuid",
            "type": "string"
          },
          "reason": {
            "type": "string"
          },
          "refunded": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Money"
              }
            ],
            "nullable": true
          },
          "requested_at": {
            "format": "date-time",
            "type": "string"
          },
          "status": {
            "enum": [
              "pending",
              "approved",
              "rejected"
            ],
            "type": "string"
          },
          "suggested": {
            "$ref": "#/components/schemas/Money"
          }
        },
        "type": "object"
      },
      "MemberRefundRequestInput": {
        "properties": {
          "reason": {
            "description": "退款理由，去除首尾空白后为 5 至 1000 个字符。",
            "maxLength": 1000,
            "minLength": 5,
            "type": "string"
          }
        },
        "required": [
          "reason"
        ],
        "type": "object"
      },
      "MemberRefundRequestListResponse": {
        "properties": {
          "data": {
            "properties": {
              "has_open_request": {
                "type": "boolean"
              },
              "items": {
                "items": {
                  "$ref": "#/components/schemas/MemberRefundRequest"
                },
                "type": "array"
              },
              "mode": {
                "$ref": "#/components/schemas/ModeEcho"
              },
              "next_cursor": {
                "description": "获取下一页时请原样传回。`null` 是唯一的结束信号，即使当前页少于 `page_size` 条，也可能仍有后续页面。",
                "nullable": true,
                "type": "string"
              },
              "page_size": {
                "description": "服务器用于本页的最大记录数，已应用上限，并非 `items` 中的实际元素数量。",
                "nullable": true,
                "type": "integer"
              },
              "total": {
                "description": "符合筛选条件的记录数量。统计成本过高时为 `null`，请勿据此判断是否结束，应以 `next_cursor` 为准。",
                "format": "int64",
                "nullable": true,
                "type": "integer"
              },
              "warnings": {
                "description": "列表呈现方式的原因；无异常时为空。封闭代码集：`filtered_by_key_package_filters`、`filtered_by_provider_scope`、`no_price_for_org`、`price_filter_removed_rows`、`provider_disabled`、`capability_missing`，分别代表密钥限制、组织供应源范围、未定价、价格筛选、供应商停用、未声明功能。`count` 为涉及行数，无法量化时为 `null`。",
                "example": [],
                "items": {
                  "$ref": "#/components/schemas/ListWarning"
                },
                "type": "array"
              }
            },
            "type": "object"
          },
          "ok": {
            "enum": [
              true
            ],
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "data"
        ],
        "type": "object"
      },
      "MemberRefundRequestResponse": {
        "properties": {
          "data": {
            "properties": {
              "decided_at": {
                "format": "date-time",
                "nullable": true,
                "type": "string"
              },
              "decision_note": {
                "nullable": true,
                "type": "string"
              },
              "id": {
                "format": "uuid",
                "type": "string"
              },
              "mode": {
                "$ref": "#/components/schemas/ModeEcho"
              },
              "order_id": {
                "format": "uuid",
                "type": "string"
              },
              "order_item_id": {
                "format": "uuid",
                "type": "string"
              },
              "reason": {
                "type": "string"
              },
              "refunded": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Money"
                  }
                ],
                "nullable": true
              },
              "requested_at": {
                "format": "date-time",
                "type": "string"
              },
              "status": {
                "enum": [
                  "pending",
                  "approved",
                  "rejected"
                ],
                "type": "string"
              },
              "suggested": {
                "$ref": "#/components/schemas/Money"
              }
            },
            "type": "object"
          },
          "ok": {
            "enum": [
              true
            ],
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "data"
        ],
        "type": "object"
      },
      "ModeEcho": {
        "description": "调用密钥的环境，与X-TKE-Mode标头一致。组织密钥使用tke_live_/tke_test_，会员密钥使用tke_member_live_/tke_member_test_。正式和测试主机校验密钥模式。",
        "enum": [
          "test",
          "live"
        ],
        "example": "live",
        "type": "string"
      },
      "Money": {
        "description": "金额。`/v1` 全部使用统一结构，字段不会在对象和裸数字之间切换。",
        "properties": {
          "amount": {
            "description": "以 `currency` 最小单位表示的整数（VND 无辅币单位）。",
            "example": 273000,
            "format": "int64",
            "type": "integer"
          },
          "currency": {
            "example": "VND",
            "type": "string"
          }
        },
        "type": "object"
      },
      "OkEnvelope": {
        "properties": {
          "data": {
            "description": "载荷因端点而异。",
            "type": "object"
          },
          "ok": {
            "enum": [
              true
            ],
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "data"
        ],
        "type": "object"
      },
      "OrderItem": {
        "properties": {
          "cancellable": {
            "$ref": "#/components/schemas/Cancellable"
          },
          "external_ref": {
            "description": "您的订单引用（下单时发送的 `external_ref`），用于将 eSIM 对应到您的订单。未提供时为 `null`。",
            "nullable": true,
            "type": "string"
          },
          "iccid": {
            "example": "8984012345678901234",
            "nullable": true,
            "type": "string"
          },
          "id": {
            "description": "eSIM ID，用于所有 `/v1/esims/{id}/…` 路径，也就是 webhook 中的 `order_item_id`。若只有 ICCID，请调用 `GET /v1/esims?iccid=…` 获取 `id`。",
            "format": "uuid",
            "type": "string"
          },
          "install": {
            "$ref": "#/components/schemas/Install"
          },
          "msisdn": {
            "nullable": true,
            "type": "string"
          },
          "order_id": {
            "format": "uuid",
            "type": "string"
          },
          "package_code": {
            "description": "目录中的套餐代码，用于将此 eSIM 对应回您的目录。仅当源套餐已从目录移除时为 `null`。",
            "nullable": true,
            "type": "string"
          },
          "package_name": {
            "description": "供人阅读、可能变化的显示名称。请勿用作对账键。",
            "type": "string"
          },
          "plan": {
            "$ref": "#/components/schemas/PlanView"
          },
          "smdp_status": {
            "example": "released",
            "nullable": true,
            "type": "string"
          },
          "status": {
            "example": "delivered",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          }
        },
        "type": "object"
      },
      "OrderListItem": {
        "properties": {
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "external_ref": {
            "example": "po-1001",
            "nullable": true,
            "type": "string"
          },
          "fulfillment_status": {
            "enum": [
              "fulfilled",
              "partially_fulfilled",
              "unfulfilled"
            ],
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "item_count": {
            "format": "int64",
            "type": "integer"
          },
          "net": {
            "$ref": "#/components/schemas/Money"
          },
          "public_ref": {
            "example": "TKE-DH-2A4C7Q",
            "nullable": true,
            "type": "string"
          },
          "refunded": {
            "$ref": "#/components/schemas/Money"
          },
          "status": {
            "type": "string"
          },
          "total": {
            "$ref": "#/components/schemas/Money"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object"
      },
      "OrderListResponse": {
        "properties": {
          "data": {
            "properties": {
              "items": {
                "items": {
                  "$ref": "#/components/schemas/OrderListItem"
                },
                "type": "array"
              },
              "mode": {
                "$ref": "#/components/schemas/ModeEcho"
              },
              "next_cursor": {
                "description": "获取下一页时请原样传回。`null` 是唯一的结束信号，即使当前页少于 `page_size` 条，也可能仍有后续页面。",
                "nullable": true,
                "type": "string"
              },
              "page_size": {
                "description": "服务器用于本页的最大记录数，已应用上限，并非 `items` 中的实际元素数量。",
                "nullable": true,
                "type": "integer"
              },
              "total": {
                "description": "符合筛选条件的记录数量。统计成本过高时为 `null`，请勿据此判断是否结束，应以 `next_cursor` 为准。",
                "format": "int64",
                "nullable": true,
                "type": "integer"
              },
              "warnings": {
                "description": "列表呈现方式的原因；无异常时为空。封闭代码集：`filtered_by_key_package_filters`、`filtered_by_provider_scope`、`no_price_for_org`、`price_filter_removed_rows`、`provider_disabled`、`capability_missing`，分别代表密钥限制、组织供应源范围、未定价、价格筛选、供应商停用、未声明功能。`count` 为涉及行数，无法量化时为 `null`。",
                "example": [],
                "items": {
                  "$ref": "#/components/schemas/ListWarning"
                },
                "type": "array"
              }
            },
            "type": "object"
          },
          "ok": {
            "enum": [
              true
            ],
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "data"
        ],
        "type": "object"
      },
      "OrderResponse": {
        "properties": {
          "data": {
            "description": "合作伙伴订单。",
            "properties": {
              "created_at": {
                "format": "date-time",
                "type": "string"
              },
              "external_ref": {
                "example": "po-1001",
                "nullable": true,
                "type": "string"
              },
              "fulfillment_status": {
                "description": "实际交付情况，与 `status` 是独立维度。订单含 3 个 eSIM，其中 2 个交付、1 个失败时，仍为 `status=completed`，同时 `fulfillment_status=partially_fulfilled` 且 `refunded_amount > 0`。",
                "enum": [
                  "fulfilled",
                  "partially_fulfilled",
                  "unfulfilled"
                ],
                "type": "string"
              },
              "id": {
                "description": "订单 ID（UUID）。",
                "format": "uuid",
                "type": "string"
              },
              "idempotent_replay": {
                "description": "此请求为先前成功操作的幂等重放时为真。",
                "nullable": true,
                "type": "boolean"
              },
              "invoice_no": {
                "description": "开具后的发票号码。",
                "nullable": true,
                "type": "string"
              },
              "invoice_status": {
                "description": "订单的增值税发票状态。`none` 表示尚未开具。",
                "enum": [
                  "none",
                  "pending",
                  "issuing",
                  "issued",
                  "failed",
                  "cancelled"
                ],
                "type": "string"
              },
              "items": {
                "items": {
                  "$ref": "#/components/schemas/OrderItem"
                },
                "type": "array"
              },
              "mode": {
                "$ref": "#/components/schemas/ModeEcho"
              },
              "money_settled": {
                "description": "订单资金是否已结算（无处理中退款）。`false` 表示暂时不能开票。",
                "type": "boolean"
              },
              "net": {
                "$ref": "#/components/schemas/Money"
              },
              "public_ref": {
                "description": "简短易读的订单编号，提交支持工单时使用。",
                "example": "TKE-DH-2A4C7Q",
                "nullable": true,
                "type": "string"
              },
              "refunded": {
                "$ref": "#/components/schemas/Money"
              },
              "status": {
                "enum": [
                  "completed",
                  "pending_provider",
                  "provider_failed",
                  "cancelled"
                ],
                "type": "string"
              },
              "total": {
                "$ref": "#/components/schemas/Money"
              }
            },
            "type": "object"
          },
          "ok": {
            "enum": [
              true
            ],
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "data"
        ],
        "type": "object"
      },
      "Package": {
        "description": "**`null` 表示信息未知，既不是“否”也不是“是”。** 不要从空字段推断承诺。只有 `true`/`false` 值和 `features.apps[]` 中实际存在的条目才是供应商声明的信息。",
        "properties": {
          "capabilities": {
            "$ref": "#/components/schemas/PackageCapabilities"
          },
          "code": {
            "description": "您目录中的套餐代码，即 `public_sku`。每个套餐的代码不可变，更换底层供应商时也不变，因此可安全用作对账键。示例仅格式正确，无法实际调用；请从 `GET /v1/catalog/packages` 获取真实代码。",
            "example": "TKE-VN-30D-X3K9F",
            "type": "string"
          },
          "coverage": {
            "description": "套餐可用地区。",
            "properties": {
              "countries": {
                "description": "ISO-3166 alpha-2 国家代码。全球套餐不逐一列出 200 个国家；全球套餐及未声明覆盖范围的套餐返回空数组。",
                "example": [
                  "CN"
                ],
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              "country_count": {
                "description": "套餐覆盖的国家数量，可据此排序或筛选多国套餐，无须获取全部数据后自行统计数组。",
                "example": 1,
                "type": "integer"
              },
              "group": {
                "description": "覆盖范围为国家列表（`country`）、地区（`region`）或全球（`global`）。开放枚举，必须忽略未知值。",
                "example": "country",
                "type": "string"
              },
              "region": {
                "description": "始终为 `null`：地区关联国家而非套餐，填值将属于推断。仍可通过 `?region=` 筛选。",
                "nullable": true,
                "type": "string"
              }
            },
            "type": "object"
          },
          "data": {
            "description": "套餐流量额度，所有数值均以**字节**表示，而非 MB／GB，以避免重复舍入。",
            "properties": {
              "daily_bytes": {
                "description": "每日流量额度，单位为字节。`fixed` 或 `unlimited` 套餐为 `null`。",
                "example": 1073741824,
                "format": "int64",
                "nullable": true,
                "type": "integer"
              },
              "label": {
                "description": "由所有界面共用的函数生成的可读标签。",
                "example": "1GB/ngày",
                "type": "string"
              },
              "model": {
                "description": "流量计算方式：`daily`（每日额度）、`fixed`（整个有效期总量）或 `unlimited`。此枚举可扩展，客户端必须忽略未知值。",
                "enum": [
                  "daily",
                  "fixed",
                  "unlimited"
                ],
                "example": "daily",
                "type": "string"
              },
              "reset": {
                "description": "每日额度重置时间。深夜购买时会影响首日可用时间，属于销售信息。`null` 表示未声明。",
                "nullable": true,
                "properties": {
                  "at": {
                    "description": "按 `timezone` 所在时区表示的重置时间（`00:00`、`00:00:01`）。",
                    "example": "00:00",
                    "nullable": true,
                    "type": "string"
                  },
                  "note": {
                    "nullable": true,
                    "type": "string"
                  },
                  "timezone": {
                    "description": "重置时点的时区（`UTC+8`、`UTC+7`）。",
                    "example": "UTC+8",
                    "nullable": true,
                    "type": "string"
                  }
                },
                "type": "object"
              },
              "total_bytes": {
                "description": "整个周期总流量（字节）。`daily`/`unlimited` 套餐为 `null`：每日额度乘天数并非供应商承诺的总量。",
                "example": null,
                "format": "int64",
                "nullable": true,
                "type": "integer"
              }
            },
            "type": "object"
          },
          "description": {
            "description": "套餐销售说明，尚未填写时为 `null`。",
            "nullable": true,
            "type": "string"
          },
          "description_en": {
            "description": "英文描述，尚未提供时为 `null`。",
            "nullable": true,
            "type": "string"
          },
          "features": {
            "description": "套餐能力采用带类型对象而非代码数组：`[]` 无法区分“不支持热点”和“信息未知”，`false` 与 `null` 可以。",
            "properties": {
              "apps": {
                "description": "按操作系统区分的应用支持状态。\n\n**数组中不存在的应用表示信息未知，并非“支持”。** 仅已列出的条目属于供应商承诺；目前只声明了 TikTok。\n\n有意不提供合并字段：真实目录中有 2,465 个套餐支持 iPhone 上的 TikTok，但不支持 Android。一个合并标记会将其全部归为“不支持”，从而误判近三分之一的目录。",
                "items": {
                  "properties": {
                    "android": {
                      "description": "`supported`（声明支持）、`blocked`（声明不支持）、`unknown`（声明未覆盖此操作系统）。开放枚举。",
                      "enum": [
                        "supported",
                        "blocked",
                        "unknown"
                      ],
                      "example": "blocked",
                      "type": "string"
                    },
                    "app": {
                      "description": "小写应用代码（例如 `tiktok`）。",
                      "example": "tiktok",
                      "type": "string"
                    },
                    "ios": {
                      "description": "`supported`（声明支持）、`blocked`（声明不支持）、`unknown`（声明未覆盖此操作系统）。开放枚举。",
                      "enum": [
                        "supported",
                        "blocked",
                        "unknown"
                      ],
                      "example": "supported",
                      "type": "string"
                    },
                    "note": {
                      "nullable": true,
                      "type": "string"
                    }
                  },
                  "type": "object"
                },
                "type": "array"
              },
              "hotspot": {
                "description": "向其他设备共享 Wi-Fi。`null` 表示未声明，与 `false` 不同。",
                "example": true,
                "nullable": true,
                "type": "boolean"
              },
              "kyc_required": {
                "description": "使用前需要身份验证（KYC）。`null` 表示未声明。",
                "example": false,
                "nullable": true,
                "type": "boolean"
              },
              "sms": {
                "description": "短信功能。`false` 表示无法接收短信，因此也无法接收银行验证码。`null` 表示未声明。",
                "example": false,
                "nullable": true,
                "type": "boolean"
              },
              "voice": {
                "description": "语音通话。`false` 表示供应商明确不支持语音，纯数据线路不能接听电话。`null` 表示未声明。",
                "example": false,
                "nullable": true,
                "type": "boolean"
              }
            },
            "type": "object"
          },
          "fup": {
            "description": "高速流量耗尽后的处理方式。`null` 表示未声明限速政策。",
            "nullable": true,
            "properties": {
              "behavior": {
                "description": "`throttle`（限速）、`cutoff`（断网）或 `null`（未声明）。开放枚举。",
                "enum": [
                  "throttle",
                  "cutoff",
                  null
                ],
                "nullable": true,
                "type": "string"
              },
              "high_speed_bytes": {
                "description": "开始限速前可全速使用的字节数。",
                "example": 1048576,
                "format": "int64",
                "nullable": true,
                "type": "integer"
              },
              "note": {
                "nullable": true,
                "type": "string"
              },
              "speed_kbps": {
                "description": "高速额度用尽后的速率（kbps）。断网或未声明时为 `null`，不同于整个套餐的速率上限 `network.speed_cap_kbps`。",
                "example": 128,
                "nullable": true,
                "type": "integer"
              }
            },
            "type": "object"
          },
          "market": {
            "description": "套餐的供应系统，为可扩展枚举，客户端必须忽略未知值。它决定是否有库存及可用售后操作：`domestic` 销售套件，支持追加、取消和用量查询；`international` 按需向供应商下单，因此没有库存。",
            "enum": [
              "domestic",
              "international"
            ],
            "example": "international",
            "type": "string"
          },
          "name": {
            "example": "eSIM Trung Quốc Mainland Multi - 1GB/ngày - 24 ngày",
            "type": "string"
          },
          "name_en": {
            "description": "英文名称，尚未提供时为 `null`。",
            "nullable": true,
            "type": "string"
          },
          "network": {
            "description": "套餐可用的网络。",
            "properties": {
              "apn": {
                "description": "某些无法自动配置的 Android 设备需要手动输入的 APN。此信息用于编写安装指南，否则每次都会变成客服咨询。`null` 表示未声明。",
                "example": "e-ideas",
                "nullable": true,
                "type": "string"
              },
              "carriers": {
                "description": "套餐实际使用的运营商网络。这是 eSIM 的无线网络规格，并非供应商。",
                "items": {
                  "properties": {
                    "name": {
                      "example": "China Unicom",
                      "type": "string"
                    }
                  },
                  "type": "object"
                },
                "type": "array"
              },
              "generations": {
                "description": "套餐可使用的网络代际（`[\"4g\", \"5g\"]`）。`null` 表示未声明，并非“仅支持 2G”。",
                "example": [
                  "4g",
                  "5g"
                ],
                "items": {
                  "type": "string"
                },
                "nullable": true,
                "type": "array"
              },
              "speed_cap_kbps": {
                "description": "整个套餐的速率上限（kbps），不同于高速额度用尽后适用的 `fup.speed_kbps`。",
                "nullable": true,
                "type": "integer"
              }
            },
            "type": "object"
          },
          "price": {
            "$ref": "#/components/schemas/Money",
            "description": "您组织通过 API 支付的价格，与 `POST /v1/orders` 实际扣款一致。始终为 `{amount, currency}` 对象，不使用裸数字。此处不披露成本价。"
          },
          "tags": {
            "description": "规范化的商业标签（小写、使用连字符），也用于匹配密钥的目录限制。目前没有套餐带标签，因此在卖方开始添加标签之前，`?tag=` 返回空列表。",
            "example": [],
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "validity": {
            "description": "套餐有效期及开始计时的条件。",
            "properties": {
              "days": {
                "example": 24,
                "type": "integer"
              },
              "install_by_days": {
                "description": "购买后可扫描二维码或安装 eSIM 的天数。`null` 表示未声明，并非“随时可以安装”。",
                "example": 365,
                "nullable": true,
                "type": "integer"
              },
              "label": {
                "example": "24 ngày",
                "type": "string"
              },
              "reclaim_on_expiry": {
                "description": "供应商在套餐到期时回收订阅，此后不能加购或换套餐。销售续费时需了解此窗口。`null` 表示未声明。",
                "example": true,
                "nullable": true,
                "type": "boolean"
              },
              "starts_when": {
                "description": "计时起点：`on_install`（安装时）、`on_purchase`（购买时）或 `null`。这直接影响有效期计算；为 `null` 时不要承诺具体到期日期。",
                "enum": [
                  "on_install",
                  "on_purchase",
                  null
                ],
                "example": "on_install",
                "nullable": true,
                "type": "string"
              },
              "unused_valid_days": {
                "description": "套餐未使用时可存放至过期的天数。`null` 表示未声明，并非无限期。此字段与 `install_by_days` 有意区分：一个是保管期限，一个是安装期限。",
                "nullable": true,
                "type": "integer"
              }
            },
            "type": "object"
          }
        },
        "type": "object"
      },
      "PackageCapabilities": {
        "description": "套餐售后能力取自套餐实际声明，不根据供应商类型推断。未声明时所有标志为 `false`，避免承诺必然返回 `422 capability.not_supported` 的操作。",
        "properties": {
          "cancel": {
            "properties": {
              "restriction": {
                "description": "`code_not_disclosed` 表示仅在无人查看过激活码时可取消（包括未发送客户、未通过后台或 `?include=lpa` 读取）。这是真实取消条件，与系统无法判断的安装状态无关。旧名称 `unused_only` 会造成错误承诺。",
                "enum": [
                  "code_not_disclosed",
                  null
                ],
                "nullable": true,
                "type": "string"
              },
              "supported": {
                "type": "boolean"
              }
            },
            "type": "object"
          },
          "plan_change": {
            "properties": {
              "policy": {
                "$ref": "#/components/schemas/PlanChangePolicy"
              },
              "supported": {
                "type": "boolean"
              }
            },
            "type": "object"
          },
          "usage_check": {
            "properties": {
              "supported": {
                "type": "boolean"
              }
            },
            "type": "object"
          }
        },
        "type": "object"
      },
      "PackageDetail": {
        "properties": {
          "data": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Package"
              },
              {
                "properties": {
                  "mode": {
                    "$ref": "#/components/schemas/ModeEcho"
                  }
                },
                "type": "object"
              }
            ]
          },
          "ok": {
            "enum": [
              true
            ],
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "data"
        ],
        "type": "object"
      },
      "PackageListResponse": {
        "properties": {
          "data": {
            "properties": {
              "items": {
                "items": {
                  "$ref": "#/components/schemas/Package"
                },
                "type": "array"
              },
              "mode": {
                "$ref": "#/components/schemas/ModeEcho"
              },
              "next_cursor": {
                "description": "获取下一页时请原样传回。`null` 是唯一的结束信号，即使当前页少于 `page_size` 条，也可能仍有后续页面。",
                "nullable": true,
                "type": "string"
              },
              "page_size": {
                "description": "服务器用于本页的最大记录数，已应用上限，并非 `items` 中的实际元素数量。",
                "nullable": true,
                "type": "integer"
              },
              "total": {
                "description": "匹配筛选条件的套餐总数。集合较大、计数成本高时（国际套餐或无 `market` 筛选）为 `null`。此计数发生在密钥限制及组织价格检查之前，表示目录匹配数而非可购数。",
                "format": "int64",
                "nullable": true,
                "type": "integer"
              },
              "warnings": {
                "description": "列表呈现方式的原因；无异常时为空。封闭代码集：`filtered_by_key_package_filters`、`filtered_by_provider_scope`、`no_price_for_org`、`price_filter_removed_rows`、`provider_disabled`、`capability_missing`，分别代表密钥限制、组织供应源范围、未定价、价格筛选、供应商停用、未声明功能。`count` 为涉及行数，无法量化时为 `null`。",
                "example": [],
                "items": {
                  "$ref": "#/components/schemas/ListWarning"
                },
                "type": "array"
              }
            },
            "type": "object"
          },
          "ok": {
            "enum": [
              true
            ],
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "data"
        ],
        "type": "object"
      },
      "PlanChangePolicy": {
        "description": "此供应商追加新套餐时的处理方式。`null` 表示套餐无法追加，或尚未确认供应商政策，不能据此推断；全部字段为 `false` 的对象则表示保证不会取消任何套餐，两者含义不同。",
        "nullable": true,
        "properties": {
          "note": {
            "nullable": true,
            "type": "string"
          },
          "requires_cancel_first": {
            "description": "新套餐下单前会取消正在使用的套餐，因为此供应商不叠加套餐。请在客户点击追加新套餐按钮之前告知。",
            "type": "boolean"
          },
          "stacking": {
            "description": "新套餐的有效期和额度是否叠加到当前套餐。",
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "PlanOptionsResponse": {
        "properties": {
          "data": {
            "description": "可为此 eSIM 加购的套餐，已按当前供应商筛选。每项均为完整 `Package`，结构与目录相同。`policy` 是当前供应商政策，`null` 表示尚未核实，不能理解为“不会取消任何套餐”。",
            "properties": {
              "items": {
                "items": {
                  "$ref": "#/components/schemas/Package"
                },
                "type": "array"
              },
              "mode": {
                "$ref": "#/components/schemas/ModeEcho"
              },
              "next_cursor": {
                "description": "获取下一页时请原样传回。`null` 是唯一的结束信号，即使当前页少于 `page_size` 条，也可能仍有后续页面。",
                "nullable": true,
                "type": "string"
              },
              "page_size": {
                "description": "服务器用于本页的最大记录数，已应用上限，并非 `items` 中的实际元素数量。",
                "type": "integer"
              },
              "policy": {
                "$ref": "#/components/schemas/PlanChangePolicy"
              },
              "total": {
                "description": "匹配筛选条件的套餐总数。集合较大、计数成本高时（国际套餐或无 `market` 筛选）为 `null`。此计数发生在密钥限制及组织价格检查之前，表示目录匹配数而非可购数。",
                "format": "int64",
                "nullable": true,
                "type": "integer"
              },
              "warnings": {
                "description": "列表呈现方式的原因；无异常时为空。封闭代码集：`filtered_by_key_package_filters`、`filtered_by_provider_scope`、`no_price_for_org`、`price_filter_removed_rows`、`provider_disabled`、`capability_missing`，分别代表密钥限制、组织供应源范围、未定价、价格筛选、供应商停用、未声明功能。`count` 为涉及行数，无法量化时为 `null`。",
                "example": [],
                "items": {
                  "$ref": "#/components/schemas/ListWarning"
                },
                "type": "array"
              }
            },
            "type": "object"
          },
          "ok": {
            "enum": [
              true
            ],
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "data"
        ],
        "type": "object"
      },
      "PlanView": {
        "description": "此 eSIM 当前使用的套餐。",
        "nullable": true,
        "properties": {
          "current_code": {
            "type": "string"
          },
          "expires_at": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "started_at": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          }
        },
        "type": "object"
      },
      "ResendResponse": {
        "properties": {
          "data": {
            "properties": {
              "id": {
                "description": "刚刚重新发送的订单 ID。",
                "format": "uuid",
                "type": "string"
              },
              "mode": {
                "$ref": "#/components/schemas/ModeEcho"
              },
              "resent_at": {
                "format": "date-time",
                "type": "string"
              },
              "resent_to": {
                "description": "部分隐藏的收件地址，合作伙伴接口不会重新返回客户的完整邮箱。",
                "example": "ab***@x.com",
                "type": "string"
              }
            },
            "type": "object"
          },
          "ok": {
            "enum": [
              true
            ],
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "data"
        ],
        "type": "object"
      },
      "SimulateRequest": {
        "properties": {
          "data": {
            "description": "部分覆盖示例载荷中的 `data` 字段。",
            "type": "object"
          }
        },
        "type": "object"
      },
      "SimulateResponse": {
        "properties": {
          "data": {
            "properties": {
              "delivery_id": {
                "format": "uuid",
                "type": "string"
              },
              "event_id": {
                "format": "uuid",
                "type": "string"
              },
              "mode": {
                "$ref": "#/components/schemas/ModeEcho"
              }
            },
            "type": "object"
          },
          "ok": {
            "enum": [
              true
            ],
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "data"
        ],
        "type": "object"
      },
      "TestModeEsimState": {
        "properties": {
          "data": {
            "properties": {
              "cancellable": {
                "$ref": "#/components/schemas/Cancellable"
              },
              "external_ref": {
                "description": "您的订单引用（下单时发送的 `external_ref`），用于将 eSIM 对应到您的订单。未提供时为 `null`。",
                "nullable": true,
                "type": "string"
              },
              "iccid": {
                "example": "8984012345678901234",
                "nullable": true,
                "type": "string"
              },
              "id": {
                "description": "eSIM ID，用于所有 `/v1/esims/{id}/…` 路径，也就是 webhook 中的 `order_item_id`。若只有 ICCID，请调用 `GET /v1/esims?iccid=…` 获取 `id`。",
                "format": "uuid",
                "type": "string"
              },
              "install": {
                "$ref": "#/components/schemas/Install"
              },
              "mode": {
                "$ref": "#/components/schemas/ModeEcho"
              },
              "msisdn": {
                "nullable": true,
                "type": "string"
              },
              "order_id": {
                "format": "uuid",
                "type": "string"
              },
              "package_code": {
                "description": "目录中的套餐代码，用于将此 eSIM 对应回您的目录。仅当源套餐已从目录移除时为 `null`。",
                "nullable": true,
                "type": "string"
              },
              "package_name": {
                "description": "供人阅读、可能变化的显示名称。请勿用作对账键。",
                "type": "string"
              },
              "plan": {
                "$ref": "#/components/schemas/PlanView"
              },
              "simulated": {
                "description": "应用场景后的模拟状态。",
                "properties": {
                  "esim_state": {
                    "description": "测试 eSIM 的技术生命周期。正式环境来自 `smdp_status`，但测试 eSIM 没有可读取的 SM-DP+ 配置，因此放在此处，与其他测试专用字段并列。",
                    "enum": [
                      "released",
                      "installed",
                      "enabled",
                      "disabled"
                    ],
                    "type": "string"
                  },
                  "last_via": {
                    "description": "最近修改此 eSIM 的流程。",
                    "enum": [
                      "open_api",
                      "simulate",
                      "seed"
                    ],
                    "type": "string"
                  },
                  "via": {
                    "description": "创建此测试 eSIM 的流程。",
                    "enum": [
                      "open_api",
                      "simulate",
                      "seed"
                    ],
                    "type": "string"
                  }
                },
                "type": "object"
              },
              "smdp_status": {
                "example": "released",
                "nullable": true,
                "type": "string"
              },
              "status": {
                "example": "delivered",
                "type": "string"
              },
              "updated_at": {
                "format": "date-time",
                "type": "string"
              },
              "usage": {
                "$ref": "#/components/schemas/Usage"
              }
            },
            "type": "object"
          },
          "ok": {
            "enum": [
              true
            ],
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "data"
        ],
        "type": "object"
      },
      "TestModeFailNextRequest": {
        "properties": {
          "count": {
            "default": 1,
            "maximum": 5,
            "minimum": 1,
            "type": "integer"
          }
        },
        "type": "object"
      },
      "TestModeFailNextResponse": {
        "properties": {
          "data": {
            "properties": {
              "endpoint_id": {
                "format": "uuid",
                "type": "string"
              },
              "mode": {
                "$ref": "#/components/schemas/ModeEcho"
              },
              "testmode_fail_next": {
                "type": "integer"
              }
            },
            "type": "object"
          },
          "ok": {
            "enum": [
              true
            ],
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "data"
        ],
        "type": "object"
      },
      "TestModeReset": {
        "properties": {
          "data": {
            "properties": {
              "esim_states_deleted": {
                "format": "int64",
                "type": "integer"
              },
              "mode": {
                "$ref": "#/components/schemas/ModeEcho"
              },
              "order_items_deleted": {
                "format": "int64",
                "type": "integer"
              },
              "orders_deleted": {
                "format": "int64",
                "type": "integer"
              },
              "wallet_balance": {
                "description": "重置后的测试钱包余额，始终为 0。不会删除账本，而是通过抵销分录将余额归零。",
                "format": "int64",
                "type": "integer"
              }
            },
            "type": "object"
          },
          "ok": {
            "enum": [
              true
            ],
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "data"
        ],
        "type": "object"
      },
      "TestModeResetInput": {
        "properties": {
          "reason": {
            "example": "Reset test data",
            "maxLength": 1000,
            "minLength": 1,
            "type": "string"
          }
        },
        "type": "object"
      },
      "TestModeSeed": {
        "properties": {
          "data": {
            "properties": {
              "already_seeded": {
                "type": "boolean"
              },
              "esims_created": {
                "type": "integer"
              },
              "mode": {
                "$ref": "#/components/schemas/ModeEcho"
              },
              "orders_created": {
                "type": "integer"
              },
              "seeded": {
                "type": "boolean"
              }
            },
            "type": "object"
          },
          "ok": {
            "enum": [
              true
            ],
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "data"
        ],
        "type": "object"
      },
      "TestModeSimulateRequest": {
        "description": "要应用的场景。字段均为可选，但至少需提供一个；空请求体返回 `422 testmode.invalid_scenario`，不会静默成功。",
        "properties": {
          "data_used_mb": {
            "description": "已使用流量（MB，以二进制 1 MiB 为单位）。超出套餐额度时截至额度上限，表示流量耗尽场景，而非错误。",
            "example": 4096,
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          },
          "expire_at": {
            "description": "设置明确的到期时间（ISO-8601 UTC）。",
            "format": "date-time",
            "type": "string"
          },
          "expire_now": {
            "description": "`true` 表示立即让套餐过期（`esim_status` 变为 `expired`）。",
            "type": "boolean"
          },
          "provider_reject": {
            "description": "模拟供应商拒绝下一次操作（追加／取消）。",
            "type": "boolean"
          },
          "status": {
            "description": "eSIM 配置的技术生命周期，采用供应商术语，不同于 eSIM 端点返回的业务状态 `esim_status`。",
            "enum": [
              "released",
              "installed",
              "enabled",
              "disabled"
            ],
            "example": "enabled",
            "type": "string"
          },
          "throttled": {
            "description": "`true` 表示线路已限速（无限套餐超过高速额度）。",
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "TestModeStatus": {
        "properties": {
          "data": {
            "properties": {
              "base_url_testing": {
                "description": "测试模式主机。仅使用tke_test_或tke_member_test_密钥；调用正式主机返回403 partner.wrong_host。",
                "type": "string"
              },
              "capabilities": {
                "properties": {
                  "bulk_orders": {
                    "type": "boolean"
                  },
                  "cancel_refund": {
                    "type": "boolean"
                  },
                  "refund_requests": {
                    "type": "boolean"
                  },
                  "webhooks": {
                    "type": "boolean"
                  }
                },
                "type": "object"
              },
              "checklist": {
                "description": "根据同一所有者在测试模式下的实际API记录计算集成进度。Webhook步骤仅适用于组织。",
                "items": {
                  "properties": {
                    "done": {
                      "type": "boolean"
                    },
                    "label": {
                      "type": "string"
                    },
                    "last_at": {
                      "format": "date-time",
                      "nullable": true,
                      "type": "string"
                    },
                    "step": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                },
                "type": "array"
              },
              "drift": {
                "description": "模拟用量循环的启用状态、间隔及最后运行时间。阈值Webhook仅发送给支持Webhook的组织。",
                "properties": {
                  "enabled": {
                    "type": "boolean"
                  },
                  "interval_secs": {
                    "format": "int64",
                    "type": "integer"
                  },
                  "last_run_at": {
                    "format": "date-time",
                    "nullable": true,
                    "type": "string"
                  }
                },
                "type": "object"
              },
              "mode": {
                "enum": [
                  "test",
                  "live"
                ],
                "type": "string"
              },
              "ready": {
                "description": "密钥所有者是否已完成所有受支持的检查步骤。会员无需测试Webhook。",
                "type": "boolean"
              },
              "sample_counts": {
                "properties": {
                  "test_esims": {
                    "format": "int64",
                    "type": "integer"
                  },
                  "test_orders": {
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "type": "object"
              },
              "seeded": {
                "description": "密钥所有者是否已有测试订单和eSIM样本数据。",
                "type": "boolean"
              },
              "test_key_count": {
                "format": "int64",
                "type": "integer"
              },
              "wallet_balance": {
                "description": "密钥所有者的虚拟VND测试钱包余额，与正式钱包隔离。",
                "format": "int64",
                "type": "integer"
              },
              "webhook": {
                "properties": {
                  "endpoint_url": {
                    "nullable": true,
                    "type": "string"
                  },
                  "fail_next": {
                    "type": "integer"
                  },
                  "status": {
                    "nullable": true,
                    "type": "string"
                  }
                },
                "type": "object"
              }
            },
            "type": "object"
          },
          "ok": {
            "enum": [
              true
            ],
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "data"
        ],
        "type": "object"
      },
      "TestModeWebhookFireRequest": {
        "properties": {
          "data": {
            "description": "部分覆盖示例载荷中的 `data` 字段。",
            "type": "object"
          },
          "event_type": {
            "description": "要模拟触发的 Webhook 事件类型。",
            "enum": [
              "order.completed",
              "order.failed",
              "esim.delivered",
              "esim.activated",
              "esim.usage_threshold",
              "esim.expiring",
              "wallet.low_balance",
              "catalog.updated"
            ],
            "type": "string"
          }
        },
        "required": [
          "event_type"
        ],
        "type": "object"
      },
      "Usage": {
        "description": "eSIM 流量使用统计，从未查询过时 `updated_at = null`。",
        "nullable": true,
        "properties": {
          "expires_at": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "remaining_bytes": {
            "format": "int64",
            "nullable": true,
            "type": "integer"
          },
          "source": {
            "enum": [
              "poll",
              "webhook"
            ],
            "nullable": true,
            "type": "string"
          },
          "total_bytes": {
            "format": "int64",
            "nullable": true,
            "type": "integer"
          },
          "updated_at": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "used_bytes": {
            "format": "int64",
            "nullable": true,
            "type": "integer"
          }
        },
        "type": "object"
      },
      "WalletBalance": {
        "properties": {
          "data": {
            "properties": {
              "available": {
                "$ref": "#/components/schemas/Money"
              },
              "balance": {
                "$ref": "#/components/schemas/Money"
              },
              "credit_limit": {
                "$ref": "#/components/schemas/Money"
              },
              "mode": {
                "$ref": "#/components/schemas/ModeEcho"
              }
            },
            "type": "object"
          },
          "ok": {
            "enum": [
              true
            ],
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "data"
        ],
        "type": "object"
      },
      "WebhookConfig": {
        "properties": {
          "data": {
            "properties": {
              "active": {
                "description": "`false` 表示已停止接收新事件，仅在组织通过后台暂停或 API 密钥被撤销时发生（同一事务内联动关闭）。通过 CHECK_HEALTH 的 `PUT /v1/webhooks/{id}` 可重新启用。",
                "type": "boolean"
              },
              "created_at": {
                "format": "date-time",
                "type": "string"
              },
              "events": {
                "description": "为空表示接收全部。",
                "items": {
                  "enum": [
                    "order.completed",
                    "order.failed",
                    "esim.delivered",
                    "esim.activated",
                    "esim.usage_threshold",
                    "esim.expiring",
                    "wallet.low_balance",
                    "catalog.updated"
                  ],
                  "type": "string"
                },
                "type": "array"
              },
              "id": {
                "description": "端点 ID，用于 `/v1/webhooks/{id}`。每次创建都会生成新 ID，删除后重建得到的是另一个端点，而非恢复旧端点。",
                "format": "uuid",
                "type": "string"
              },
              "last_delivery_at": {
                "description": "通过此端点最后投递的时间。`null` 表示从未投递，不同于“投递失败”；合作伙伴反馈未收到 webhook 时应首先检查。",
                "format": "date-time",
                "nullable": true,
                "type": "string"
              },
              "mode": {
                "$ref": "#/components/schemas/ModeEcho"
              },
              "secret_last4": {
                "description": "Webhook 密钥的末四个字符，可用于核对手持密钥是否与系统签名密钥一致，而无需任何端点重新泄露密钥。完整密钥仅在创建时显示一次。",
                "type": "string"
              },
              "url": {
                "type": "string"
              }
            },
            "type": "object"
          },
          "ok": {
            "enum": [
              true
            ],
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "data"
        ],
        "type": "object"
      },
      "WebhookEndpoint": {
        "properties": {
          "active": {
            "description": "`false` 表示已停止接收新事件，仅在组织通过后台暂停或 API 密钥被撤销时发生（同一事务内联动关闭）。通过 CHECK_HEALTH 的 `PUT /v1/webhooks/{id}` 可重新启用。",
            "type": "boolean"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "events": {
            "description": "为空表示接收全部。",
            "items": {
              "enum": [
                "order.completed",
                "order.failed",
                "esim.delivered",
                "esim.activated",
                "esim.usage_threshold",
                "esim.expiring",
                "wallet.low_balance",
                "catalog.updated"
              ],
              "type": "string"
            },
            "type": "array"
          },
          "id": {
            "description": "端点 ID，用于 `/v1/webhooks/{id}`。每次创建都会生成新 ID，删除后重建得到的是另一个端点，而非恢复旧端点。",
            "format": "uuid",
            "type": "string"
          },
          "last_delivery_at": {
            "description": "通过此端点最后投递的时间。`null` 表示从未投递，不同于“投递失败”；合作伙伴反馈未收到 webhook 时应首先检查。",
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "secret_last4": {
            "description": "Webhook 密钥的末四个字符，可用于核对手持密钥是否与系统签名密钥一致，而无需任何端点重新泄露密钥。完整密钥仅在创建时显示一次。",
            "type": "string"
          },
          "url": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "WebhookListResponse": {
        "properties": {
          "data": {
            "properties": {
              "items": {
                "items": {
                  "$ref": "#/components/schemas/WebhookEndpoint"
                },
                "type": "array"
              },
              "mode": {
                "$ref": "#/components/schemas/ModeEcho"
              },
              "next_cursor": {
                "description": "获取下一页时请原样传回。`null` 是唯一的结束信号，即使当前页少于 `page_size` 条，也可能仍有后续页面。",
                "nullable": true,
                "type": "string"
              },
              "page_size": {
                "description": "服务器用于本页的最大记录数，已应用上限，并非 `items` 中的实际元素数量。",
                "nullable": true,
                "type": "integer"
              },
              "total": {
                "description": "符合筛选条件的记录数量。统计成本过高时为 `null`，请勿据此判断是否结束，应以 `next_cursor` 为准。",
                "format": "int64",
                "nullable": true,
                "type": "integer"
              },
              "warnings": {
                "description": "列表呈现方式的原因；无异常时为空。封闭代码集：`filtered_by_key_package_filters`、`filtered_by_provider_scope`、`no_price_for_org`、`price_filter_removed_rows`、`provider_disabled`、`capability_missing`，分别代表密钥限制、组织供应源范围、未定价、价格筛选、供应商停用、未声明功能。`count` 为涉及行数，无法量化时为 `null`。",
                "example": [],
                "items": {
                  "$ref": "#/components/schemas/ListWarning"
                },
                "type": "array"
              }
            },
            "type": "object"
          },
          "ok": {
            "enum": [
              true
            ],
            "type": "boolean"
          }
        },
        "required": [
          "ok",
          "data"
        ],
        "type": "object"
      },
      "WebhookRequest": {
        "properties": {
          "events": {
            "description": "为空表示接收全部。未知值返回 400 `internal.validation_failed`（字段 `events`）。",
            "items": {
              "enum": [
                "order.completed",
                "order.failed",
                "esim.delivered",
                "esim.activated",
                "esim.usage_threshold",
                "esim.expiring",
                "wallet.low_balance",
                "catalog.updated"
              ],
              "type": "string"
            },
            "type": "array"
          },
          "url": {
            "example": "https://partner.example.com/hooks/tke",
            "format": "uri",
            "type": "string"
          }
        },
        "required": [
          "url"
        ],
        "type": "object"
      }
    },
    "securitySchemes": {
      "TkeHmac": {
        "description": "HMAC-SHA256 认证（§4）。发送四个请求头：`X-TKE-Key`（公开 key_id）、`X-TKE-Timestamp`（epoch 毫秒）、`X-TKE-Nonce`（每个请求一个 UUID）、`X-TKE-Signature`（小写十六进制）。signing_string = method\npath\ntimestamp\nnonce\nbody_hash；body_hash = SHA256(raw_body) 的十六进制值。使用恒定时间比较。path 包含查询字符串。",
        "in": "header",
        "name": "X-TKE-Signature",
        "type": "apiKey"
      }
    }
  },
  "info": {
    "description": "面向接入 eSIM 销售的合作伙伴的 Open API（仅单级合作伙伴）。所有 `/v1/*` 端点均通过四个 `X-TKE-*` 请求头进行 **HMAC-SHA256** 认证，不支持无签名模式。涉及资金或订单的 POST 必须携带 `Idempotency-Key`。`tke_test_` 密钥在测试主机运行，使用虚拟钱包、库存和开通。REST 是事实来源，通过 `updated_since` 与游标主动对账；webhook 仅作为辅助。资源主键始终为 `id`，外键带有 `order_id` 等前缀。",
    "title": "Tổng Kho eSIM — Open API đối tác",
    "version": "2.4.0"
  },
  "openapi": "3.0.3",
  "paths": {
    "/v1/catalog/packages": {
      "get": {
        "description": "所需权限范围: `catalog:read`.\n\n您所属组织的套餐目录：两个供应系统共用一个接口，通过 `?market=` 筛选。\n\n仅返回实际可购买的套餐：已发布、供应商仍在分销、符合密钥目录限制，且已为组织定价。未定价套餐不显示是因为无法下单。\n\n游标分页：首次不传 `cursor`，之后原样传回 `next_cursor`，直到为 `null`。当前页少于 `page_size` 条并不表示结束。\n\n`capabilities` 来自套餐真实声明，绝不推测；未声明时全部标志为 `false`。宁可省略原本可用的按钮，也不承诺必然返回 `422` 的功能。\n\n目录不包含库存概念，没有数量或有货/售罄等级。如果供应商无法交付，`POST /v1/orders` 会在下单时直接返回明确错误（如 `esim.out_of_stock`），无须从预先展示的字段推断。",
        "operationId": "get_catalog_packages",
        "parameters": [
          {
            "description": "每页记录数，默认 50，上限 100；超过上限时限制为 100，不报错。",
            "in": "query",
            "name": "page_size",
            "required": false,
            "schema": {
              "default": 50,
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "供应系统：`domestic` | `international`。列表之外的值返回 `internal.invalid_filter`（400），而不是完整目录，避免将拼写错误误认为筛选没有排除任何记录。",
            "in": "query",
            "name": "market",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "ISO-3166 alpha-2 国家代码（如 `VN`），仅返回覆盖该国的套餐。",
            "in": "query",
            "name": "country",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "区域标识（如 `chau-a`），返回覆盖该区域至少一个国家的套餐及所有全球套餐。",
            "in": "query",
            "name": "region",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "按公开代码和套餐名称进行自由文本搜索（部分匹配，不区分大小写）。",
            "in": "query",
            "name": "q",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "按一个商业标签筛选。与存储时使用相同的规范化方式：去除多余空格、转为小写并使用连字符，因此 `Ban Le` 与 `ban-le` 是同一标签。",
            "in": "query",
            "name": "tag",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "流量模型：`daily` | `fixed` | `unlimited`，替代旧 `supports_topup`。未知值返回 `internal.invalid_filter`（400）。",
            "in": "query",
            "name": "data_model",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "最低流量，单位为**字节**。按日套餐以每日额度比较；无限流量套餐始终满足下限条件。",
            "in": "query",
            "name": "data_min_bytes",
            "required": false,
            "schema": {
              "format": "int64",
              "type": "integer"
            }
          },
          {
            "description": "最大流量，单位为**字节**。不包含无限流量套餐：流量上限不适用于无限套餐，若允许其通过筛选，寻找最小流量套餐的人也会获得无限套餐。",
            "in": "query",
            "name": "data_max_bytes",
            "required": false,
            "schema": {
              "format": "int64",
              "type": "integer"
            }
          },
          {
            "description": "最短有效期，单位为天。",
            "in": "query",
            "name": "days_min",
            "required": false,
            "schema": {
              "format": "int64",
              "type": "integer"
            }
          },
          {
            "description": "最长有效期，单位为天。",
            "in": "query",
            "name": "days_max",
            "required": false,
            "schema": {
              "format": "int64",
              "type": "integer"
            }
          },
          {
            "description": "最低价格（VND），与您所属组织的价格比较。此筛选在服务器分页后执行，因此页面记录减少不代表数据已经结束。",
            "in": "query",
            "name": "price_min",
            "required": false,
            "schema": {
              "format": "int64",
              "type": "integer"
            }
          },
          {
            "description": "最高价格（VND），规则与 `price_min` 相同。",
            "in": "query",
            "name": "price_max",
            "required": false,
            "schema": {
              "format": "int64",
              "type": "integer"
            }
          },
          {
            "description": "仅查询支持该网络代际（`2g` | `3g` | `4g` | `5g`）的套餐。未知值返回 `internal.invalid_filter`（400）。",
            "in": "query",
            "name": "network_gen",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "`true` 仅筛选明确支持热点的套餐，`false` 仅筛选明确不支持的套餐。未声明（`features.hotspot = null`）两边都不匹配。只接受字符串 `true`/`false`。",
            "in": "query",
            "name": "hotspot",
            "required": false,
            "schema": {
              "enum": [
                "true",
                "false"
              ],
              "type": "string"
            }
          },
          {
            "description": "仅返回声明在至少一个操作系统上支持此应用的套餐（`app=tiktok`）。未声明的套餐不匹配，沉默不代表承诺。目前仅接受 `tiktok`，其他代码返回 `internal.invalid_filter`（400）。",
            "in": "query",
            "name": "app",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "`true` 仅筛选明确支持语音的套餐，`false` 仅筛选明确不支持的套餐。未声明两边都不匹配。只接受字符串 `true`/`false`。",
            "in": "query",
            "name": "voice",
            "required": false,
            "schema": {
              "enum": [
                "true",
                "false"
              ],
              "type": "string"
            }
          },
          {
            "description": "原样传回 `next_cursor`。**仅在其为 `null` 时停止，不要因页面条目少而停止。** 密钥目录限制、组织定价、价格范围筛选均在分页之后执行。游标含筛选条件指纹，条件改变或游标损坏返回 `catalog.cursor_mismatch`（400），避免拼接不同查询的页面。",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PackageListResponse"
                }
              }
            },
            "description": "成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.validation_failed`, `internal.invalid_filter`, `catalog.cursor_mismatch`"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.invalid_key`, `partner.invalid_signature`, `partner.timestamp_expired`, `partner.nonce_reused`"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.ip_not_allowed`, `partner.scope_denied`, `partner.key_suspended`, `partner.key_revoked`, `org.suspended`"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.rate_limited`"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.endpoint_disabled`, `internal.service_unavailable`"
          }
        },
        "summary": "列出套餐",
        "tags": [
          "catalog"
        ],
        "x-tke-modes": [
          "live",
          "test"
        ],
        "x-tke-owner-types": [
          "organization",
          "member"
        ]
      }
    },
    "/v1/catalog/packages/{code}": {
      "get": {
        "description": "所需权限范围: `catalog:read`.\n\n按公开代码获取一个套餐的详情。`data` 的字段与 `GET /v1/catalog/packages` 单项相同，仅增加 `mode`；没有详情专属字段，因此只需定义一个 `Package` 类型。\n\n无权查看的代码统一返回 `partner.package_not_visible`（404），无论原因是代码不存在、超出密钥目录限制、组织未定价或套餐失去供应关联。区分这些原因会让外部人员枚举整个目录。",
        "operationId": "get_catalog_packages__code_",
        "parameters": [
          {
            "description": "套餐代码，即目录中的 `code`（`public_sku`）。每个套餐不可变，更换底层供应商时不变，可保存为对账键。超出密钥目录限制或组织未定价的代码，与不存在的代码一样返回 `404 partner.package_not_visible`。",
            "in": "path",
            "name": "code",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PackageDetail"
                }
              }
            },
            "description": "成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.validation_failed`"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.invalid_key`, `partner.invalid_signature`, `partner.timestamp_expired`, `partner.nonce_reused`"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.ip_not_allowed`, `partner.scope_denied`, `partner.key_suspended`, `partner.key_revoked`, `org.suspended`"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.package_not_visible`"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.rate_limited`"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.endpoint_disabled`, `internal.service_unavailable`"
          }
        },
        "summary": "获取单个套餐",
        "tags": [
          "catalog"
        ],
        "x-tke-modes": [
          "live",
          "test"
        ],
        "x-tke-owner-types": [
          "organization",
          "member"
        ]
      }
    },
    "/v1/esims": {
      "get": {
        "description": "所需权限范围: `esims:read`.",
        "operationId": "get_esims",
        "parameters": [
          {
            "description": "每页记录数，默认 50，上限 200；超过上限时限制为 200，不报错。",
            "in": "query",
            "name": "page_size",
            "required": false,
            "schema": {
              "default": 50,
              "maximum": 200,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "按 `esim_status` 筛选。列表之外的值返回 `internal.invalid_filter`（400），而非空列表，以免将拼写错误（如 `cancelled` 少写一个 `l` 的 `canceled`）误认为该客户没有此状态的 eSIM。",
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "enum": [
                "pending",
                "available",
                "reserved",
                "sold",
                "delivered",
                "in_use",
                "used_up",
                "expired",
                "suspended",
                "cancelled",
                "provider_failed"
              ],
              "type": "string"
            }
          },
          {
            "description": "仅查询同一订单的 eSIM。",
            "in": "query",
            "name": "order_id",
            "required": false,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          },
          {
            "description": "按 ICCID 筛选（字符串，精确匹配）。",
            "in": "query",
            "name": "iccid",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "带有您的订单引用（下单时发送的 `external_ref`，精确匹配）的所有订单 eSIM。",
            "in": "query",
            "name": "external_ref",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "ISO-8601 UTC 时间。按升序返回所有满足 `updated_at >= updated_since` 的记录，是标准主动查询式对账路径（§8.5）；即使遗漏 webhook，也可从状态重建。格式错误返回 `internal.invalid_filter`（400）。",
            "in": "query",
            "name": "updated_since",
            "required": false,
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          },
          {
            "description": "下一页游标，请原样传回上一页的 `next_cursor`。畸形游标不会报错，而会从列表开头读取，以兼容游标编码变更。请确认新游标与刚发送的值不同，避免无限循环读取第一页。",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "用逗号分隔额外区块：`lpa` 返回 `install`，`qr` 额外返回 `install.qr_code_base64`（仅详情端点）。**返回代码即披露**，响应中所有 eSIM 将永久不可取消（`cancellable.allowed = false`，`reason = code_disclosed`）。立即交付客户时再请求；提前订购时省略可保留取消权。未知值返回 `internal.invalid_filter`（400，`field: \"include\"`）。",
            "in": "query",
            "name": "include",
            "required": false,
            "schema": {
              "example": "lpa",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EsimListResponse"
                }
              }
            },
            "description": "成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.validation_failed`, `internal.invalid_filter`"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.invalid_key`, `partner.invalid_signature`, `partner.timestamp_expired`, `partner.nonce_reused`"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.ip_not_allowed`, `partner.scope_denied`, `partner.key_suspended`, `partner.key_revoked`, `org.suspended`"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.rate_limited`"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.endpoint_disabled`, `internal.service_unavailable`"
          }
        },
        "summary": "列出 eSIM（主动查询式对账）",
        "tags": [
          "esims"
        ],
        "x-tke-modes": [
          "live",
          "test"
        ],
        "x-tke-owner-types": [
          "organization",
          "member"
        ]
      }
    },
    "/v1/esims/{id}": {
      "get": {
        "description": "所需权限范围: `esims:read`.",
        "operationId": "get_esims__id_",
        "parameters": [
          {
            "description": "已售 eSIM 的稳定 ID，不是可能复用的 ICCID。",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "用逗号分隔额外区块：`lpa` 返回 `install`，`qr` 额外返回 `install.qr_code_base64`（仅详情端点）。**返回代码即披露**，响应中所有 eSIM 将永久不可取消（`cancellable.allowed = false`，`reason = code_disclosed`）。立即交付客户时再请求；提前订购时省略可保留取消权。未知值返回 `internal.invalid_filter`（400，`field: \"include\"`）。",
            "in": "query",
            "name": "include",
            "required": false,
            "schema": {
              "example": "lpa",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Esim"
                }
              }
            },
            "description": "成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.validation_failed`, `internal.invalid_filter`"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.invalid_key`, `partner.invalid_signature`, `partner.timestamp_expired`, `partner.nonce_reused`"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.ip_not_allowed`, `partner.scope_denied`, `partner.key_suspended`, `partner.key_revoked`, `org.suspended`"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.not_found`"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.rate_limited`"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.endpoint_disabled`, `internal.service_unavailable`"
          }
        },
        "summary": "获取单个 eSIM",
        "tags": [
          "esims"
        ],
        "x-tke-modes": [
          "live",
          "test"
        ],
        "x-tke-owner-types": [
          "organization",
          "member"
        ]
      }
    },
    "/v1/esims/{id}/cancel": {
      "post": {
        "description": "所需权限范围: `esims:write`.",
        "operationId": "post_esims__id__cancel",
        "parameters": [
          {
            "description": "已售 eSIM 的稳定 ID，不是可能复用的 ICCID。",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "客户端生成的字符串：相同密钥和请求体只执行一次，重试返回原结果。范围为 `api_key_id`（§11），不同密钥属于不同命令。",
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CancelResponse"
                }
              }
            },
            "description": "成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.validation_failed`"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.invalid_key`, `partner.invalid_signature`, `partner.timestamp_expired`, `partner.nonce_reused`"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.ip_not_allowed`, `partner.scope_denied`, `partner.key_suspended`, `partner.key_revoked`, `org.suspended`"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `esim.not_cancellable`, `idempotency.conflict`"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `capability.not_supported`"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.rate_limited`"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.endpoint_disabled`, `internal.service_unavailable`"
          }
        },
        "summary": "取消未使用的 eSIM",
        "tags": [
          "esims"
        ],
        "x-tke-modes": [
          "live",
          "test"
        ],
        "x-tke-owner-types": [
          "organization",
          "member"
        ]
      }
    },
    "/v1/esims/{id}/change-plan": {
      "post": {
        "description": "所需权限范围: `esims:write`.",
        "operationId": "post_esims__id__change-plan",
        "parameters": [
          {
            "description": "已售 eSIM 的稳定 ID，不是可能复用的 ICCID。",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "客户端生成的字符串：相同密钥和请求体只执行一次，重试返回原结果。范围为 `api_key_id`（§11），不同密钥属于不同命令。",
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChangePlanRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChangePlanResponse"
                }
              }
            },
            "description": "成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.validation_failed`"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.invalid_key`, `partner.invalid_signature`, `partner.timestamp_expired`, `partner.nonce_reused`"
          },
          "402": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `wallet.insufficient_balance`"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.ip_not_allowed`, `partner.scope_denied`, `partner.key_suspended`, `partner.key_revoked`, `org.suspended`"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.package_not_visible`"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `esim.topup_not_supported`, `esim.topup_provider_mismatch`, `esim.not_eligible`, `idempotency.conflict`"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `capability.not_supported`"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.rate_limited`"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.endpoint_disabled`, `internal.service_unavailable`"
          }
        },
        "summary": "为 eSIM 加购",
        "tags": [
          "esims"
        ],
        "x-tke-modes": [
          "live",
          "test"
        ],
        "x-tke-owner-types": [
          "organization",
          "member"
        ]
      }
    },
    "/v1/esims/{id}/plan-options": {
      "get": {
        "description": "所需权限范围: `esims:read`.\n\n返回仅适用于此 eSIM 的可追加套餐。系统根据 `id` 确认所属供应商，只返回该供应商的套餐。`/v1` 不暴露 `provider_id`，此接口代为筛选，从结构上杜绝误选其他供应商的套餐。直接向 `POST /v1/esims/{id}/change-plan` 提交不在此列表中的套餐代码将返回 `409 esim.topup_provider_mismatch`。\n\n从未关联供应商的 eSIM（纯导入或缺少来源信息）返回空列表（`total: 0`），这是正常结果而非错误。",
        "operationId": "get_esims__id__plan-options",
        "parameters": [
          {
            "description": "已售 eSIM 的稳定 ID，不是可能复用的 ICCID。",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "每页记录数，默认 50，上限 200；超过上限时限制为 200，不报错。",
            "in": "query",
            "name": "page_size",
            "required": false,
            "schema": {
              "default": 50,
              "maximum": 200,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "下一页游标，请原样传回上一页的 `next_cursor`。畸形游标不会报错，而会从列表开头读取，以兼容游标编码变更。请确认新游标与刚发送的值不同，避免无限循环读取第一页。",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlanOptionsResponse"
                }
              }
            },
            "description": "成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.validation_failed`"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.invalid_key`, `partner.invalid_signature`, `partner.timestamp_expired`, `partner.nonce_reused`"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.ip_not_allowed`, `partner.scope_denied`, `partner.key_suspended`, `partner.key_revoked`, `org.suspended`"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.not_found`"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.rate_limited`"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.endpoint_disabled`, `internal.service_unavailable`"
          }
        },
        "summary": "此 eSIM 可用的加购套餐",
        "tags": [
          "esims"
        ],
        "x-tke-modes": [
          "live",
          "test"
        ],
        "x-tke-owner-types": [
          "organization",
          "member"
        ]
      }
    },
    "/v1/esims/{id}/refund-requests": {
      "get": {
        "description": "所需权限范围: `esims:read`.\n\n仅限已授权的正式会员密钥。按最新优先返回会员eSIM最多50条退款申请；next_cursor和total为null。has_open_request表示存在待审核申请。组织及测试密钥返回capability.not_supported。",
        "operationId": "get_esims__id__refund-requests",
        "parameters": [
          {
            "description": "已售 eSIM 的稳定 ID，不是可能复用的 ICCID。",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MemberRefundRequestListResponse"
                }
              }
            },
            "description": "成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.validation_failed`"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.invalid_key`, `partner.invalid_signature`, `partner.timestamp_expired`, `partner.nonce_reused`"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.ip_not_allowed`, `partner.scope_denied`, `partner.key_suspended`, `partner.key_revoked`, `org.suspended`"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.not_found`"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `capability.not_supported`"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.rate_limited`"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.endpoint_disabled`, `internal.service_unavailable`"
          }
        },
        "summary": "eSIM 退款申请记录（仅限会员）",
        "tags": [
          "esims"
        ],
        "x-tke-modes": [
          "live"
        ],
        "x-tke-owner-types": [
          "member"
        ]
      },
      "post": {
        "description": "所需权限范围: `esims:write`.\n\n仅限已授权的正式会员密钥。使用Idempotency-Key为会员自己的eSIM提交退款申请，管理员批准前不转移资金。组织及测试密钥返回capability.not_supported。测试模式请取消eSIM以验证虚拟钱包退款。",
        "operationId": "post_esims__id__refund-requests",
        "parameters": [
          {
            "description": "已售 eSIM 的稳定 ID，不是可能复用的 ICCID。",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "客户端生成的字符串：相同密钥和请求体只执行一次，重试返回原结果。范围为 `api_key_id`（§11），不同密钥属于不同命令。",
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MemberRefundRequestInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MemberRefundRequestResponse"
                }
              }
            },
            "description": "成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.validation_failed`, `internal.validation_failed`"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.invalid_key`, `partner.invalid_signature`, `partner.timestamp_expired`, `partner.nonce_reused`"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.ip_not_allowed`, `partner.scope_denied`, `partner.key_suspended`, `partner.key_revoked`, `org.suspended`"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.not_found`"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `esim.refund_not_eligible`, `esim.refund_request_pending`, `idempotency.conflict`"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `capability.not_supported`"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.rate_limited`"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.endpoint_disabled`, `internal.service_unavailable`"
          }
        },
        "summary": "创建 eSIM 退款申请（仅限会员）",
        "tags": [
          "esims"
        ],
        "x-tke-modes": [
          "live"
        ],
        "x-tke-owner-types": [
          "member"
        ]
      }
    },
    "/v1/esims/{id}/usage": {
      "get": {
        "description": "所需权限范围: `esims:read`.\n\n读取 eSIM 的已用与剩余流量，并附带数据时间戳 `updated_at`（真实新鲜度）。对于仅按需查询的供应商（目前为 SkyFi）的 eSIM，此调用会将一次扫描加入队列并最多等待约 15 秒获取结果，因此响应最长可能需要 ~15 秒，返回的数据来自刚完成的那次扫描。若扫描失败、同一 eSIM 距上次扫描不足 15 秒或等待超时，不会返回错误，而是返回最近保存的数据，请查看 `updated_at`。其他供应商返回定期更新的已保存数据。",
        "operationId": "get_esims__id__usage",
        "parameters": [
          {
            "description": "已售 eSIM 的稳定 ID，不是可能复用的 ICCID。",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EsimUsage"
                }
              }
            },
            "description": "成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.validation_failed`"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.invalid_key`, `partner.invalid_signature`, `partner.timestamp_expired`, `partner.nonce_reused`"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.ip_not_allowed`, `partner.scope_denied`, `partner.key_suspended`, `partner.key_revoked`, `org.suspended`"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `capability.not_supported`"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.rate_limited`"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.endpoint_disabled`, `internal.service_unavailable`"
          }
        },
        "summary": "已使用流量",
        "tags": [
          "esims"
        ],
        "x-tke-modes": [
          "live",
          "test"
        ],
        "x-tke-owner-types": [
          "organization",
          "member"
        ]
      }
    },
    "/v1/orders": {
      "get": {
        "description": "所需权限范围: `orders:read`.",
        "operationId": "get_orders",
        "parameters": [
          {
            "description": "每页记录数，默认 50，上限 200；超过上限时限制为 200，不报错。",
            "in": "query",
            "name": "page_size",
            "required": false,
            "schema": {
              "default": 50,
              "maximum": 200,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "按订单状态筛选。列表之外的值返回 `internal.invalid_filter`（400）。",
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "enum": [
                "completed",
                "pending_provider",
                "provider_failed",
                "cancelled"
              ],
              "type": "string"
            }
          },
          {
            "description": "按提交订单时发送的参考编号筛选（精确匹配）。",
            "in": "query",
            "name": "external_ref",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "ISO-8601 UTC 时间。按升序返回所有满足 `updated_at >= updated_since` 的记录，是标准主动查询式对账路径（§8.5）；即使遗漏 webhook，也可从状态重建。格式错误返回 `internal.invalid_filter`（400）。",
            "in": "query",
            "name": "updated_since",
            "required": false,
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          },
          {
            "description": "下一页游标，请原样传回上一页的 `next_cursor`。畸形游标不会报错，而会从列表开头读取，以兼容游标编码变更。请确认新游标与刚发送的值不同，避免无限循环读取第一页。",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderListResponse"
                }
              }
            },
            "description": "成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.validation_failed`, `internal.invalid_filter`"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.invalid_key`, `partner.invalid_signature`, `partner.timestamp_expired`, `partner.nonce_reused`"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.ip_not_allowed`, `partner.scope_denied`, `partner.key_suspended`, `partner.key_revoked`, `org.suspended`"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.rate_limited`"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.endpoint_disabled`, `internal.service_unavailable`"
          }
        },
        "summary": "列出订单（主动查询式对账）",
        "tags": [
          "orders"
        ],
        "x-tke-modes": [
          "live",
          "test"
        ],
        "x-tke-owner-types": [
          "organization",
          "member"
        ]
      },
      "post": {
        "description": "所需权限范围: `orders:write`.",
        "operationId": "post_orders",
        "parameters": [
          {
            "description": "客户端生成的字符串：相同密钥和请求体只执行一次，重试返回原结果。范围为 `api_key_id`（§11），不同密钥属于不同命令。",
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateOrderRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderResponse"
                }
              }
            },
            "description": "24 小时内使用相同 `Idempotency-Key` 和请求体重放：响应体与首次完全相同，不重复扣款，并添加 `Idempotent-Replayed: true`。新建返回 `201`，请勿仅凭此状态码区分成功。"
          },
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderResponse"
                }
              }
            },
            "description": "成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.validation_failed`, `internal.invalid_filter`"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.invalid_key`, `partner.invalid_signature`, `partner.timestamp_expired`, `partner.nonce_reused`"
          },
          "402": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `wallet.insufficient_balance`"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.ip_not_allowed`, `partner.scope_denied`, `partner.key_suspended`, `partner.key_revoked`, `org.suspended`"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.package_not_visible`"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `esim.out_of_stock`, `idempotency.conflict`"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `invoice.buyer_invalid`"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.rate_limited`"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.endpoint_disabled`, `internal.service_unavailable`"
          }
        },
        "summary": "创建订单（直接购买）",
        "tags": [
          "orders"
        ],
        "x-tke-modes": [
          "live",
          "test"
        ],
        "x-tke-owner-types": [
          "organization",
          "member"
        ]
      }
    },
    "/v1/orders/bulk": {
      "post": {
        "description": "所需权限范围: `orders:write`.\n\n提交多行批次，每行独立生成一个订单，执行与 `POST /v1/orders` 相同的 quote→commit。\n\n部分成功：失败行不阻止其他行，只扣成功行款项。缺货、余额不足、套餐不可售、触发防滥用限制等业务错误位于 `lines[].error`，不影响批次整体 HTTP 状态。中途余额不足仍尝试后续行，因为较便宜的套餐可能仍可购买。\n\n状态始终为 `200`：结果是逐行混合结果而非单一新资源，故不是 `201`；批次在请求内处理完成，不使用 `202` 加轮询。\n\n相同 `Idempotency-Key` 加相同请求体再次调用，将加载旧批次、原样返回已完成行，仅继续处理 `pending` 行，不重复扣款。未执行任何行时附带 `Idempotent-Replayed: true`。同密钥但请求体不同则为 `idempotency.conflict`。\n\n同一组织在 10 分钟内提交内容相同的批次，即使幂等键不同，也视为误点重复提交：返回旧批次并带 `Idempotent-Replayed: true`，不再扣款。若确需为另一客户购买相同商品，请修改 `external_ref`；它属于签名内容，可区分批次并用于后续对账。全部失败、未产生任何订单的批次不会受此限制，超过 10 分钟也可正常重购。\n\n行级 `external_ref` 原样返回于 `lines[].external_ref`，批次级参考编号返回于响应顶部。\n\n响应不包含 LPA/QR，请按各 `order_id` 从 `GET /v1/orders/{order_id}` 获取。",
        "operationId": "post_orders_bulk",
        "parameters": [
          {
            "description": "客户端生成的字符串：相同密钥和请求体只执行一次，重试返回原结果。范围为 `api_key_id`（§11），不同密钥属于不同命令。",
            "in": "header",
            "name": "Idempotency-Key",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BulkRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkBatchResponse"
                }
              }
            },
            "description": "成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.validation_failed`"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.invalid_key`, `partner.invalid_signature`, `partner.timestamp_expired`, `partner.nonce_reused`"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.ip_not_allowed`, `partner.scope_denied`, `partner.key_suspended`, `partner.key_revoked`, `org.suspended`"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.package_not_visible`"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `idempotency.conflict`"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.limit_exceeded`"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.rate_limited`"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.endpoint_disabled`, `internal.service_unavailable`"
          }
        },
        "summary": "提交多行批量订单（每行一个订单）",
        "tags": [
          "orders"
        ],
        "x-tke-modes": [
          "live",
          "test"
        ],
        "x-tke-owner-types": [
          "organization"
        ]
      }
    },
    "/v1/orders/bulk/{id}": {
      "get": {
        "description": "所需权限范围: `orders:read`.\n\n重新读取已提交批次的逐行结果，可在原始响应丢失时恢复，无须重发请求体。其他组织或其他环境（正式／测试）的批次返回 `404`。",
        "operationId": "get_orders_bulk__id_",
        "parameters": [
          {
            "description": "POST /v1/orders/bulk 返回的批次 ID（UUID）。",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BulkBatchResponse"
                }
              }
            },
            "description": "成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.validation_failed`"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.invalid_key`, `partner.invalid_signature`, `partner.timestamp_expired`, `partner.nonce_reused`"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.ip_not_allowed`, `partner.scope_denied`, `partner.key_suspended`, `partner.key_revoked`, `org.suspended`"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.not_found`"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.rate_limited`"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.endpoint_disabled`, `internal.service_unavailable`"
          }
        },
        "summary": "批量订单结果",
        "tags": [
          "orders"
        ],
        "x-tke-modes": [
          "live",
          "test"
        ],
        "x-tke-owner-types": [
          "organization"
        ]
      }
    },
    "/v1/orders/{id}": {
      "get": {
        "description": "所需权限范围: `orders:read`.",
        "operationId": "get_orders__id_",
        "parameters": [
          {
            "description": "订单 ID（UUID）。",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "用逗号分隔额外区块：`lpa` 返回 `install`，`qr` 额外返回 `install.qr_code_base64`（仅详情端点）。**返回代码即披露**，响应中所有 eSIM 将永久不可取消（`cancellable.allowed = false`，`reason = code_disclosed`）。立即交付客户时再请求；提前订购时省略可保留取消权。未知值返回 `internal.invalid_filter`（400，`field: \"include\"`）。",
            "in": "query",
            "name": "include",
            "required": false,
            "schema": {
              "example": "lpa",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderResponse"
                }
              }
            },
            "description": "成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.validation_failed`, `internal.invalid_filter`"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.invalid_key`, `partner.invalid_signature`, `partner.timestamp_expired`, `partner.nonce_reused`"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.ip_not_allowed`, `partner.scope_denied`, `partner.key_suspended`, `partner.key_revoked`, `org.suspended`"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.not_found`"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.rate_limited`"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.endpoint_disabled`, `internal.service_unavailable`"
          }
        },
        "summary": "订单详情及 eSIM",
        "tags": [
          "orders"
        ],
        "x-tke-modes": [
          "live",
          "test"
        ],
        "x-tke-owner-types": [
          "organization",
          "member"
        ]
      }
    },
    "/v1/orders/{id}/resend": {
      "post": {
        "description": "所需权限范围: `orders:write`.",
        "operationId": "post_orders__id__resend",
        "parameters": [
          {
            "description": "订单 ID（UUID）。",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResendResponse"
                }
              }
            },
            "description": "成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.validation_failed`"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.invalid_key`, `partner.invalid_signature`, `partner.timestamp_expired`, `partner.nonce_reused`"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.ip_not_allowed`, `partner.scope_denied`, `partner.key_suspended`, `partner.key_revoked`, `org.suspended`"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `order.not_deliverable`"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.rate_limited`"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.endpoint_disabled`, `internal.service_unavailable`"
          }
        },
        "summary": "重新发送订单邮件／二维码",
        "tags": [
          "orders"
        ],
        "x-tke-modes": [
          "live",
          "test"
        ],
        "x-tke-owner-types": [
          "organization",
          "member"
        ]
      }
    },
    "/v1/testmode/esims/{id}/simulate": {
      "post": {
        "description": "所需权限范围: `esims:write`.\n\n仅限tke_test_或tke_member_test_测试密钥。对所有者的测试eSIM设置用量、安装状态、到期、限速或下一操作的模拟供应商拒绝。正文至少包含一个字段；空正文返回422 testmode.invalid_scenario。与正式模式相同，通过GET /v1/esims/{id}和/usage读取结果。套餐变更及取消规则共用，不调用真实供应商。",
        "operationId": "post_testmode_esims__id__simulate",
        "parameters": [
          {
            "description": "已售 eSIM 的稳定 ID，不是可能复用的 ICCID。",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TestModeSimulateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TestModeEsimState"
                }
              }
            },
            "description": "成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.validation_failed`"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.invalid_key`, `partner.invalid_signature`, `partner.timestamp_expired`, `partner.nonce_reused`"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.ip_not_allowed`, `partner.scope_denied`, `partner.key_suspended`, `partner.key_revoked`, `org.suspended`, `testmode.live_key_forbidden`"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.not_found`"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `testmode.invalid_scenario`"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.rate_limited`"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.endpoint_disabled`, `internal.service_unavailable`"
          }
        },
        "summary": "模拟测试 eSIM 生命周期（仅限测试密钥）",
        "tags": [
          "testmode"
        ],
        "x-tke-modes": [
          "test"
        ],
        "x-tke-owner-types": [
          "organization",
          "member"
        ]
      }
    },
    "/v1/testmode/reset": {
      "post": {
        "description": "所需权限范围: `orders:write`.",
        "operationId": "post_testmode_reset",
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TestModeResetInput"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TestModeReset"
                }
              }
            },
            "description": "成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.validation_failed`"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.invalid_key`, `partner.invalid_signature`, `partner.timestamp_expired`, `partner.nonce_reused`"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.ip_not_allowed`, `partner.scope_denied`, `partner.key_suspended`, `partner.key_revoked`, `org.suspended`, `testmode.live_key_forbidden`"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.rate_limited`"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.endpoint_disabled`, `internal.service_unavailable`"
          }
        },
        "summary": "重置测试数据（仅限测试密钥）",
        "tags": [
          "testmode"
        ],
        "x-tke-idempotency-owner-types": [
          "member"
        ],
        "x-tke-modes": [
          "test"
        ],
        "x-tke-owner-types": [
          "organization",
          "member"
        ],
        "x-tke-required-body-owner-types": [
          "member"
        ]
      }
    },
    "/v1/testmode/seed": {
      "post": {
        "description": "所需权限范围: `orders:write`.",
        "operationId": "post_testmode_seed",
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TestModeSeed"
                }
              }
            },
            "description": "成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.validation_failed`"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.invalid_key`, `partner.invalid_signature`, `partner.timestamp_expired`, `partner.nonce_reused`"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.ip_not_allowed`, `partner.scope_denied`, `partner.key_suspended`, `partner.key_revoked`, `org.suspended`, `testmode.live_key_forbidden`"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `testmode.no_sellable_package`"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.rate_limited`"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.endpoint_disabled`, `internal.service_unavailable`"
          }
        },
        "summary": "生成测试示例数据（仅限测试密钥）",
        "tags": [
          "testmode"
        ],
        "x-tke-idempotency-owner-types": [
          "member"
        ],
        "x-tke-modes": [
          "test"
        ],
        "x-tke-owner-types": [
          "organization",
          "member"
        ]
      }
    },
    "/v1/testmode/status": {
      "get": {
        "description": "所需权限范围: `esims:read`.",
        "operationId": "get_testmode_status",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TestModeStatus"
                }
              }
            },
            "description": "成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.validation_failed`"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.invalid_key`, `partner.invalid_signature`, `partner.timestamp_expired`, `partner.nonce_reused`"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.ip_not_allowed`, `partner.scope_denied`, `partner.key_suspended`, `partner.key_revoked`, `org.suspended`, `testmode.live_key_forbidden`"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.rate_limited`"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.endpoint_disabled`, `internal.service_unavailable`"
          }
        },
        "summary": "测试模式概览（仅限测试密钥）",
        "tags": [
          "testmode"
        ],
        "x-tke-modes": [
          "test"
        ],
        "x-tke-owner-types": [
          "organization",
          "member"
        ]
      }
    },
    "/v1/testmode/webhooks/fail-next": {
      "post": {
        "description": "所需权限范围: `webhook:manage`.",
        "operationId": "post_testmode_webhooks_fail-next",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TestModeFailNextRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TestModeFailNextResponse"
                }
              }
            },
            "description": "成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.validation_failed`, `internal.validation_failed`"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.invalid_key`, `partner.invalid_signature`, `partner.timestamp_expired`, `partner.nonce_reused`"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.ip_not_allowed`, `partner.scope_denied`, `partner.key_suspended`, `partner.key_revoked`, `org.suspended`, `testmode.live_key_forbidden`"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.not_found`"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.rate_limited`"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.endpoint_disabled`, `internal.service_unavailable`"
          }
        },
        "summary": "模拟下一次 webhook 失败（仅限测试密钥）",
        "tags": [
          "webhook"
        ],
        "x-tke-modes": [
          "test"
        ],
        "x-tke-owner-types": [
          "organization"
        ]
      }
    },
    "/v1/testmode/webhooks/fire": {
      "post": {
        "description": "所需权限范围: `webhook:manage`.",
        "operationId": "post_testmode_webhooks_fire",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TestModeWebhookFireRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SimulateResponse"
                }
              }
            },
            "description": "成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.validation_failed`"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.invalid_key`, `partner.invalid_signature`, `partner.timestamp_expired`, `partner.nonce_reused`"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.ip_not_allowed`, `partner.scope_denied`, `partner.key_suspended`, `partner.key_revoked`, `org.suspended`, `testmode.live_key_forbidden`"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `webhook.not_configured`, `internal.not_found`"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.rate_limited`"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.endpoint_disabled`, `internal.service_unavailable`"
          }
        },
        "summary": "发送测试 webhook 事件（仅限测试密钥）",
        "tags": [
          "webhook"
        ],
        "x-tke-modes": [
          "test"
        ],
        "x-tke-owner-types": [
          "organization"
        ]
      }
    },
    "/v1/wallet/balance": {
      "get": {
        "description": "所需权限范围: `wallet:read`.",
        "operationId": "get_wallet_balance",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WalletBalance"
                }
              }
            },
            "description": "成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.validation_failed`"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.invalid_key`, `partner.invalid_signature`, `partner.timestamp_expired`, `partner.nonce_reused`"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.ip_not_allowed`, `partner.scope_denied`, `partner.key_suspended`, `partner.key_revoked`, `org.suspended`"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.rate_limited`"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.endpoint_disabled`, `internal.service_unavailable`"
          }
        },
        "summary": "钱包余额",
        "tags": [
          "wallet"
        ],
        "x-tke-modes": [
          "live",
          "test"
        ],
        "x-tke-owner-types": [
          "organization",
          "member"
        ]
      }
    },
    "/v1/webhooks": {
      "get": {
        "description": "所需权限范围: `webhook:manage`.\n\n仅返回调用 API 密钥的端点。密钥绝不查看其他密钥的端点，即使两个密钥属于同一组织（§5.11：绑定于 `api_key_id`，测试与正式环境不共享）。\n\n尚未配置时返回 `200` 和空数组，而非 `404`；集合始终存在，只是当前没有元素。",
        "operationId": "get_webhooks",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookListResponse"
                }
              }
            },
            "description": "成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.validation_failed`"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.invalid_key`, `partner.invalid_signature`, `partner.timestamp_expired`, `partner.nonce_reused`"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.ip_not_allowed`, `partner.scope_denied`, `partner.key_suspended`, `partner.key_revoked`, `org.suspended`"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.rate_limited`"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.endpoint_disabled`, `internal.service_unavailable`"
          }
        },
        "summary": "列出 webhook 端点",
        "tags": [
          "webhook"
        ],
        "x-tke-modes": [
          "live",
          "test"
        ],
        "x-tke-owner-types": [
          "organization"
        ]
      },
      "post": {
        "description": "所需权限范围: `webhook:manage`.\n\n为调用密钥创建 webhook 端点。保存前，服务器会向 URL POST 一个已签名的 `ping` 事件（CHECK_HEALTH）。未获 2xx 则不保存并返回 `422 webhook.health_check_failed`。必须使用公开 `https` URL，内部或元数据 IP 返回 `422 webhook.url_not_allowed`。\n\n`webhook_secret` 仅在创建时显示一次，无法再次读取。丢失后须在面板轮换，旧密钥还会并行有效 24 小时（§8.4）。\n\n密钥已有端点时返回 `409 webhook.already_configured`，即使端点已暂停（`is_active: false`）。暂停仍保留 URL、密钥及日志。若需重建，先 `DELETE /v1/webhooks/{id}` 再创建。",
        "operationId": "post_webhooks",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateWebhookResponse"
                }
              }
            },
            "description": "成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.validation_failed`"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.invalid_key`, `partner.invalid_signature`, `partner.timestamp_expired`, `partner.nonce_reused`"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.ip_not_allowed`, `partner.scope_denied`, `partner.key_suspended`, `partner.key_revoked`, `org.suspended`"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `webhook.already_configured`"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `webhook.health_check_failed`, `webhook.url_not_allowed`"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.rate_limited`"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.endpoint_disabled`, `internal.service_unavailable`"
          }
        },
        "summary": "创建 Webhook 端点",
        "tags": [
          "webhook"
        ],
        "x-tke-modes": [
          "live",
          "test"
        ],
        "x-tke-owner-types": [
          "organization"
        ]
      }
    },
    "/v1/webhooks/deliveries": {
      "get": {
        "description": "所需权限范围: `webhook:manage`.",
        "operationId": "get_webhooks_deliveries",
        "parameters": [
          {
            "description": "页码从 1 开始。超出数据末尾时返回 `items: []` 和真实 `total`（200，非 404）。",
            "in": "query",
            "name": "page",
            "required": false,
            "schema": {
              "default": 1,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "每页记录数，默认 50，上限 200；超过上限时限制为 200，不报错。",
            "in": "query",
            "name": "page_size",
            "required": false,
            "schema": {
              "default": 50,
              "maximum": 200,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "按事件类型筛选（参见 webhook 事件目录）。",
            "in": "query",
            "name": "event_type",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "按投递状态筛选。`?status=failed` 用于主动查询式 webhook 对账（§13）。未知值不会报错，筛选条件会被忽略并返回完整日志。",
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "enum": [
                "pending",
                "delivered",
                "failed"
              ],
              "type": "string"
            }
          },
          {
            "description": "同一事件的所有投递尝试（包括重放）。",
            "in": "query",
            "name": "event_id",
            "required": false,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeliveryListResponse"
                }
              }
            },
            "description": "成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.validation_failed`"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.invalid_key`, `partner.invalid_signature`, `partner.timestamp_expired`, `partner.nonce_reused`"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.ip_not_allowed`, `partner.scope_denied`, `partner.key_suspended`, `partner.key_revoked`, `org.suspended`"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `webhook.not_configured`"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.rate_limited`"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.endpoint_disabled`, `internal.service_unavailable`"
          }
        },
        "summary": "Webhook 投递日志",
        "tags": [
          "webhook"
        ],
        "x-tke-modes": [
          "live",
          "test"
        ],
        "x-tke-owner-types": [
          "organization"
        ]
      }
    },
    "/v1/webhooks/deliveries/{id}/replay": {
      "post": {
        "description": "所需权限范围: `webhook:manage`.",
        "operationId": "post_webhooks_deliveries__id__replay",
        "parameters": [
          {
            "description": "单次 webhook 投递 ID（来自 `GET /v1/webhooks/deliveries` 的 `items[].id`）。",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeliveryReplayResponse"
                }
              }
            },
            "description": "成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.validation_failed`"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.invalid_key`, `partner.invalid_signature`, `partner.timestamp_expired`, `partner.nonce_reused`"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.ip_not_allowed`, `partner.scope_denied`, `partner.key_suspended`, `partner.key_revoked`, `org.suspended`"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `webhook.delivery_not_found`, `webhook.not_configured`"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.rate_limited`"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.endpoint_disabled`, `internal.service_unavailable`"
          }
        },
        "summary": "重新投递 webhook",
        "tags": [
          "webhook"
        ],
        "x-tke-modes": [
          "live",
          "test"
        ],
        "x-tke-owner-types": [
          "organization"
        ]
      }
    },
    "/v1/webhooks/{id}": {
      "delete": {
        "description": "所需权限范围: `webhook:manage`.\n\n删除端点后，调用密钥不再接收新事件。\n\n`webhook_secret` 会随端点删除而失去。通过 `POST /v1/webhooks` 重建会生成新 `id` 和新密钥，必须更新签名验证函数。若只需暂停并保留密钥，请使用面板中的“暂停”。\n\n完整投递日志保留用于对账，但被删端点的投递记录无法重放。\n\n等待重试的 `pending` 投递会以 `endpoint_disabled` 原因停止，并保留日志（§8.5）。\n\n不属于调用密钥或已删除的 `id` 返回 `404 webhook.not_found`，绝不会静默返回 200。",
        "operationId": "delete_webhooks__id_",
        "parameters": [
          {
            "description": "Webhook 端点 ID（`POST /v1/webhooks` 或 `GET /v1/webhooks` 返回的 `id`）。",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeleteWebhookResponse"
                }
              }
            },
            "description": "成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.validation_failed`"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.invalid_key`, `partner.invalid_signature`, `partner.timestamp_expired`, `partner.nonce_reused`"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.ip_not_allowed`, `partner.scope_denied`, `partner.key_suspended`, `partner.key_revoked`, `org.suspended`"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `webhook.not_found`"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.rate_limited`"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.endpoint_disabled`, `internal.service_unavailable`"
          }
        },
        "summary": "删除 webhook 端点（停止接收新事件）",
        "tags": [
          "webhook"
        ],
        "x-tke-modes": [
          "live",
          "test"
        ],
        "x-tke-owner-types": [
          "organization"
        ]
      },
      "get": {
        "description": "所需权限范围: `webhook:manage`.",
        "operationId": "get_webhooks__id_",
        "parameters": [
          {
            "description": "Webhook 端点 ID（`POST /v1/webhooks` 或 `GET /v1/webhooks` 返回的 `id`）。",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookConfig"
                }
              }
            },
            "description": "成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.validation_failed`"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.invalid_key`, `partner.invalid_signature`, `partner.timestamp_expired`, `partner.nonce_reused`"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.ip_not_allowed`, `partner.scope_denied`, `partner.key_suspended`, `partner.key_revoked`, `org.suspended`"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `webhook.not_found`"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.rate_limited`"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.endpoint_disabled`, `internal.service_unavailable`"
          }
        },
        "summary": "获取单个 webhook 端点",
        "tags": [
          "webhook"
        ],
        "x-tke-modes": [
          "live",
          "test"
        ],
        "x-tke-owner-types": [
          "organization"
        ]
      },
      "put": {
        "description": "所需权限范围: `webhook:manage`.",
        "operationId": "put_webhooks__id_",
        "parameters": [
          {
            "description": "Webhook 端点 ID（`POST /v1/webhooks` 或 `GET /v1/webhooks` 返回的 `id`）。",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebhookConfig"
                }
              }
            },
            "description": "成功"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `internal.validation_failed`"
          },
          "401": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.invalid_key`, `partner.invalid_signature`, `partner.timestamp_expired`, `partner.nonce_reused`"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.ip_not_allowed`, `partner.scope_denied`, `partner.key_suspended`, `partner.key_revoked`, `org.suspended`"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `webhook.not_found`"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `webhook.health_check_failed`, `webhook.url_not_allowed`"
          },
          "429": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.rate_limited`"
          },
          "503": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            },
            "description": "错误: `partner.endpoint_disabled`, `internal.service_unavailable`"
          }
        },
        "summary": "更新 Webhook 端点",
        "tags": [
          "webhook"
        ],
        "x-tke-modes": [
          "live",
          "test"
        ],
        "x-tke-owner-types": [
          "organization"
        ]
      }
    }
  },
  "security": [
    {
      "TkeHmac": []
    }
  ],
  "servers": [
    {
      "description": "Live",
      "url": "https://api.tongkhoesim.com"
    },
    {
      "description": "测试模式",
      "url": "https://api-testing.tongkhoesim.com"
    }
  ],
  "tags": [
    {
      "description": "套餐目录为两个供应系统提供统一接口。供应系统通过字段（`market`: `domestic` | `international`）和筛选（`?market=`）区分，不再使用两个独立路径。\n\n没有库存概念：不包含数量或 `available`／`low`／`out_of_stock` 等等级。套餐直接展示，若供应商无法交付，下单时由 `POST /v1/orders` 返回明确错误（如 `esim.out_of_stock`），而非目录提前告知。\n\n统一使用游标分页。仅在统计成本低时（筛选国内系统）提供 `total`，否则为 `null`。",
      "name": "catalog"
    },
    {
      "description": "下单及对账",
      "name": "orders"
    },
    {
      "description": "eSIM 记录、用量、加购及取消",
      "name": "esims"
    },
    {
      "description": "钱包余额",
      "name": "wallet"
    },
    {
      "description": "Webhook 配置、投递日志及模拟器",
      "name": "webhook"
    },
    {
      "description": "仅在api-testing主机使用tke_test_或tke_member_test_测试密钥。模拟所有者的测试eSIM和数据，不使用真实余额或供应商。会员测试模式不支持Webhook、批量订单或人工审核退款申请。",
      "name": "testmode"
    }
  ]
}