回调通知

部分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、二维码、号码等）。