回調通知

部分eSim開通非實時，下單後可能需要一段時間才能完成開通。下單時傳入notifyUrl回調通知地址，開通成功後系統會主動POST通知該地址；未傳入notifyUrl時可通過訂單詳情接口輪詢查詢開通狀態。

通知方式

請求方式：POST

Content-Type：application/json

通知地址：下單時傳入的notifyUrl參數

通知內容：JSON字符串，結構見下方示例

eSIM生成失敗時（notifyType=3），系統會推送該通知，同時訂單已支付金額將退回買家帳戶餘額，訂單狀態變更為已退款。

通知測試

* 填寫回調通知地址，係統會嚮該地址POST發送一條示例通知內容（與實際通知方式一緻，含 eventId、clientOrderNo 與真實簽名），用於驗證地址是否可正常接收通知

POST

通知內容示例

{
    "sn": "231013169",
    "clientOrderNo": "your-order-no-001",
    "eventId": "E20260810120000A1B2C3D4",
    "notifyType": 1,
    "activationStatus": "activated",
    "iccid": "89852070322460401234",
    "lpa": "LPA:1$xxx.prod.xxxxxxxxxxx.com$TEST1234567890",
    "number": "86866878",
    "verifyCode": "123456",
    "qrcode": "data:image/png;base64,...",
    "time": "20260810120000",
    "sign": "3a1f9c2d1e4b85f6a7c8d9e0f1a2b3c4"
}

示例中的 sign 值為佔位示意；實際 sign 需用你收到的通知 body 與你的 API token 計算得到。可點上方「發送測試」接收帶真實簽名的樣例進行驗簽自測。

通知字段說明

字段	類型	說明
sn	string	訂單號
clientOrderNo	string	客戶訂單號（下單時傳入的clientOrderNo原樣回顯，僅傳了才返回）
eventId	string	事件唯一ID，全局唯一且貫穿該事件的所有重發投遞（同一事件多次重試 eventId 不變）。格式：E+YmdHis+8位十六進制隨機。回調接收方應據此做冪等去重與問題追溯；參與簽名。
notifyType	number	【通知類型】 1 - 開卡成功 2 - 退訂 3 - 生成失敗
activationStatus	string	【eSim開通狀態】 activated - 已開通 unsubscribed - 已退訂 failed - 生成失敗
iccid	string	eSim卡ICCID
lpa	string	eSim配置(用於生成二維碼)，僅開卡成功通知返回
number	string	eSim卡號碼，僅開卡成功通知返回
verifyCode	string	eSim配置驗證碼，僅開卡成功通知返回
qrcode	string	eSim配置二維碼(base64格式)，僅開卡成功通知返回
time	string	通知時間（YmdHis，東八區 UTC+8 標準時間）
sign	string	通知簽名，用於回調方校驗請求來源與內容完整性；算法見下方「簽名校驗」。

簽名校驗

通知內容包含 sign 字段，回調接收方應校驗簽名以確保請求來源可信、內容未被篡改。

簽名算法：

1、將通知 JSON 解碼為關聯數組；

2、取出並保存 sign 字段值，然後從數組中移除 sign；

3、將本賬號的 API token（開發者中心可見）作為 token 鍵加入數組；

4、按 key 降序排序（krsort）後用 http_build_query 拼接成查詢串；

5、對上一步結果取 md5，與第 2 步保存的 sign 比對；不一致請拒絕處理該通知。

說明：token 僅參與簽名計算，不會隨通知外發；sign 本身不參與簽名。

重要：上述算法對通知 body 中實際存在的全部字段計算簽名（不固定字段清單），因此平台後續新增字段（如 eventId、clientOrderNo）時，按此實現的驗簽邏輯無需改動即可自動兼容。若你此前按固定字段清單實現驗簽，請務必將 eventId（以及回顯時的 clientOrderNo）納入參與簽名的字段集合，否則會校驗失敗。

PHP 驗簽示例：

<?php
// 1、通知以 Content-Type: application/json POST，必须读取原始请求体，不能用 $_POST
$rawBody = file_get_contents('php://input');
$payload = json_decode($rawBody, true);
if (!is_array($payload)) {
    http_response_code(400);
    exit('invalid json');
}

// 2、取出并移除 sign（sign 不参与自身签名）
$sign = $payload['sign'] ?? '';
unset($payload['sign']);

// 3、加入本账号 API token（开发者中心可见，仅参与签名、不随通知外发）
$payload['token'] = $myApiToken;

// 4、按 key 降序排序后拼接，分隔符固定使用 '&'（必须与平台算法保持一致）
krsort($payload);
$expected = md5(http_build_query($payload, '', '&'));

// 5、比对签名，不一致直接拒绝处理
if (!hash_equals($expected, $sign)) {
    http_response_code(400);
    exit('sign invalid');
}

// 6、验签通过后按 eventId 幂等去重（同一事件多次重试只处理一次），再执行业务
$eventId = $payload['eventId'] ?? '';
// TODO：查本地记录，若该 eventId 已处理过则直接返回 200，避免重复发货/重复对账

// 7、处理完成务必返回 HTTP 200，系统据此判定通知投递成功
http_response_code(200);
echo 'OK';

響應要求

1、收到通知後請返回HTTP狀態碼200，系統以此判斷通知成功。

2、返回非200或地址不可達時，系統會按間隔遞增重試，最多通知3次（首次失敗後約5分鐘重試第2次，第2次失敗後約10分鐘重試第3次）。

3、3次通知均失敗後不再重試，可通過訂單詳情接口查詢最新開通狀態；同一事件可能因重試收到多條通知，請依據 eventId 去重。

4、收到開卡成功通知後，可調用訂單詳情接口獲取完整的eSim卡信息（lpa、二維碼、號碼等）。