eSIM Open API

简体中文

English

简体中文

English

Appearance

Webhook 回调 ​

平台在关键事件发生时，向合作伙伴配置的 callback URL 发送 POST 请求。验签方式与入站 Open API 相同。

配置 ​

  • 后台「API 凭证」页面填写回调 URL
  • 或通过 API：POST /open-api/v1/webhook/set
json
{ "callbackUrl": "https://your-server.com/openapi/callback" }

事件类型 ​

对外 Webhook 仅 3 种 eventType（与 eSIM Access / 亿点等供应商入站 notifyType 不同）。平台将多种履约/Profile 变更聚合为 DELIVERY_UPDATED，payload 结构与 查单 一致，请根据 orderStatus / deliveryStatus / items[].profiles[] 判断具体变化。

eventType说明
ORDER_PAID余额支付成功，订单进入履约
DELIVERY_UPDATED订单发货或 Profile 状态变更（见下方触发场景）。仅在该订单实际发生变更时推送
REFUND_COMPLETED退款已入账（含同步退款与异步亿点售后完成）

如何识别 DELIVERY_UPDATED 具体含义 ​

Webhook Body 是全量订单快照（与查单一致），不是增量 patch。除阅读下方状态字段外，请优先看 changeHints 数组：

  • 平台将本次 payload 与同一 orderNo + 同一 eventType 上一次成功投递的快照对比，生成变更摘要
  • 首次 DELIVERY_UPDATED 或无历史快照时，按「相对空快照」推断（例如首次出现 iccid → ICCID_READY）
  • 一次推送可含多个 hint（如同时 ICCID_READY + DELIVERY_STATUS_CHANGED）
  • 重试投递时 changeHints 与首次相同（基于同一快照对比结果）

changeHints 取值说明 ​

changeHints含义建议对接动作
ICCID_READY子项或 Profile 首次出现 ICCID展示卡号、触发安装引导
QR_CODE_READY首次出现安装二维码 URL展示 QR
ACTIVATION_CODE_READY首次出现 SM-DP+ 激活码展示 LPA 串
DELIVERY_STATUS_CHANGED主单 deliveryStatus 变化更新发货进度 UI
ORDER_STATUS_CHANGED主单 orderStatus 变化更新订单态
ITEM_STATUS_CHANGED子项 itemStatus 变化更新子单态
PROFILE_LIFECYCLE_CHANGEDProfile lifecycleStatus 变化更新单卡生命周期
ESIM_STATUS_CHANGEDProfile esimStatus 变化记录供应商 eSIM 态
SMDP_STATUS_CHANGEDProfile smdpStatus 变化记录安装过程态
PLAN_USE_STARTEDplanUseStatus 变为 STARTED套餐开始使用
PLAN_USE_ENDEDplanUseStatus 变为 ENDED套餐结束
USAGE_UPDATED流量字段变化更新用量展示（实时用量可调 profile/usage）
PROFILE_CANCELLEDProfile cancelled 变为 true标记卡已取消
ORDER_SNAPSHOT_SYNC有推送但未命中更细规则全量覆盖本地快照
ORDER_PAIDORDER_PAID 事件标记已支付
REFUND_COMPLETEDREFUND_COMPLETED 事件标记退款完成
REFUND_AMOUNT_UPDATED累计退款额增加更新退款金额

状态字段枚举（平台归一化） ​

主单 deliveryStatus

值含义
PENDING未发货
PARTIAL部分 Profile 已就绪
DELIVERED全部 Profile 已就绪
FAILED发货失败

主单 orderStatus（节选）

值含义
PAID已支付，待履约
FULFILLING履约中
COMPLETED订单完成
REFUNDING退款处理中（通常不单独推 Webhook，以查单为准）
REFUNDED已退款

子项 itemStatus

值含义
PENDING待发码
DELIVERED已发码
ACTIVATING激活中
ACTIVATED已激活
FAILED失败
REFUNDED已退款

Profile lifecycleStatus（推荐对接方优先使用）

值含义
PENDING待发码
DELIVERED已发码（有 iccid/qr）
ACTIVATING安装/激活进行中
ACTIVATED已激活
CANCELLED已取消

esimStatus / smdpStatus 为供应商原文，不同渠道取值不同，仅作补充；判断业务阶段请优先 lifecycleStatus + changeHints。

对接建议（伪代码） ​

text
on webhook(payload):
  if payload.eventType == "DELIVERY_UPDATED":
    for hint in payload.changeHints:
      handle(hint)          // 按 hint 表分支
    upsertLocalSnapshot(payload)   // 仍建议存全量快照，便于对账
  elif payload.eventType == "REFUND_COMPLETED":
    markRefunded(payload)
  elif payload.eventType == "ORDER_PAID":
    markPaid(payload)

DELIVERY_UPDATED 触发场景（平台内部） ​

以下场景在平台侧都会以 DELIVERY_UPDATED 推送（不会单独再发 ESIM_STATUS、DATA_USAGE 等 eventType）：

场景典型 payload 变化
ICCID / 二维码 / 激活码就绪items[].iccid、qrCodeUrl、activationCode；deliveryStatus 可能变为 PARTIAL / DELIVERED
Profile 安装 / eSIM 状态变更items[].profiles[].esimStatus、smdpStatus
套餐开始使用 / 结束items[].profiles[].planUseStatus、planUseStartTime、planUseEndTime
流量 / 有效期告警items[].profiles[].dataUsageBytes、remainDataBytes、usagePercent 等
Profile 激活 / 生命周期items[].profiles[].activated、lifecycleStatus
退款审核拒绝等导致 Profile 状态回写items[].profiles[].cancelled 等；退款入账另见 REFUND_COMPLETED

当前不会单独推送的事件 ​

期望场景说明
REFUNDING 退款处理中退款接口可能返回 REFUNDING；入账前不会单独 Webhook，请轮询查单或等 REFUND_COMPLETED
充值审核通过账户充值走独立流程，不在订单 Webhook 范围
订单支付失败下单失败不落单，无 Webhook

推送原则 ​

  • 平台按订单维度推送，对外统一为平台订单 / Profile 模型
  • 仅推送该订单实际发生的状态变更；无变更则不推送
  • 不同套餐可能支持的状态字段不同，以 payload 中 items[].profiles[] 实际返回为准

请求格式 ​

Header 与入站一致（平台使用同一 AppKey 对应 Secret 签名）。

Body 示例（支付成功）：

json
{
  "eventType": "ORDER_PAID",
  "transactionId": "your-transaction-id",
  "orderNo": "ORD20260101001",
  "orderId": 123456,
  "payStatus": "PAID",
  "deliveryStatus": "PENDING",
  "orderStatus": "PAID",
  "currency": "USD",
  "items": [
    {
      "itemNo": "ITEM001",
      "packageCode": "PKG001",
      "quantity": 1,
      "itemStatus": "PAID"
    }
  ]
}

发货 / Profile 变更示例（DELIVERY_UPDATED）：

json
{
  "eventType": "DELIVERY_UPDATED",
  "transactionId": "your-transaction-id",
  "orderNo": "ORD20260101001",
  "orderId": 123456,
  "payStatus": "PAID",
  "deliveryStatus": "DELIVERED",
  "orderStatus": "COMPLETED",
  "currency": "USD",
  "changeHints": ["ICCID_READY", "QR_CODE_READY", "DELIVERY_STATUS_CHANGED", "PROFILE_LIFECYCLE_CHANGED"],
  "items": [
    {
      "itemNo": "ITEM001",
      "packageCode": "PKG001",
      "quantity": 1,
      "itemStatus": "DELIVERED",
      "iccid": "8901234567890123456",
      "qrCodeUrl": "https://cdn.example.com/qr/xxx.png",
      "profiles": [
        {
          "iccid": "8901234567890123456",
          "esimTranNo": "E202506180001",
          "esimStatus": "IN_USE",
          "lifecycleStatus": "ACTIVATED",
          "planUseStatus": "STARTED",
          "dataUsageBytes": 524288000
        }
      ]
    }
  ]
}

退款完成示例：

json
{
  "eventType": "REFUND_COMPLETED",
  "transactionId": "your-transaction-id",
  "orderNo": "ORD20260101001",
  "orderId": 123456,
  "payStatus": "REFUNDED",
  "deliveryStatus": "DELIVERED",
  "orderStatus": "REFUNDED",
  "refundAmount": 3.50,
  "currency": "USD",
  "items": [
    {
      "itemNo": "ITEM001",
      "packageCode": "PKG001",
      "quantity": 1,
      "itemStatus": "REFUNDED"
    }
  ]
}

完整 Schema 见 OpenAPI Schema 中 WebhookCallbackPayload。

重试 ​

投递失败会写入 Outbox 并重试（默认最多 8 次，指数退避）。请保证接口 幂等（按 orderNo + eventType 去重）。

接入建议 ​

  1. 验签通过后再处理业务
  2. 快速返回 HTTP 200
  3. 异步处理内部逻辑

eSIM Dealer Open API v1

Copyright © eSIM Platform