Changelog

v1.0.2（当前）

接口（Breaking）

• OrderItemVo 精简：移除 items[].iccid / qrCodeUrl / activationCode（卡信息统一在 items[].profiles[]）
• itemNo 格式：对外改为子项主键 id 字符串（如 2075463266738958341），不再暴露 {orderNo}-I-{id}
• ProfileVo 嵌套精简：在查单/Webhook 的 items[].profiles[] 内不再重复 orderNo、itemNo、套餐字段
• 退款 items[].itemNo 入参/出参同步为新格式；仍兼容库内旧格式 {orderNo}-I-{id}

接口（Enhancement）

• 下单统一 items[]：POST /esim/order 仅通过 items[] 下单（单商品一行）；必填 amount 与各行的 price
• 退款部分退：items[] 必带 itemNo；profiles 为空退整子项，非空按 profileId 或 iccid 部分退；不传 items 为整单退。不暴露供应商 esimTranNo
• 退款响应 items[] 返回 profileIds、iccids

v1.0.1

接口

• Webhook 新增 REFUND_COMPLETED（退款入账完成，含 BALANCE 同步退与异步售后放款）
• 回调 payload 增加 refundAmount、currency

文档

• Health status 与实现对齐为 UP
• 鉴权错误码与业务错误码分表说明
• openapi.yaml 补全 PackageVo 字段与 WebhookCallbackPayload

---

v1.0.0

接口

• 初始 Open API：health、套餐、下单、查单、Profile 运维、余额、充值申请、Webhook、地区列表
• 订单退款 POST /open-api/v1/esim/refund
• 出站回调：ORDER_PAID、DELIVERY_UPDATED

文档

• 在线对接文档 + OpenAPI 3.0 规范
• Apifox 前置签名脚本
• 各接口明细页（eSIM Access 风格参数表）
• 中英文切换（导航栏右上角）

约定

• 对外接口统一呈现平台订单/Profile 模型；部分操作可能返回 asyncStatus=PENDING 或退款 status=REFUNDING，属正常异步流程

---

计划（Roadmap）

• SMS 发送能力
• Outbox 失败监控 / 管理端重推