RedEx eSIM Open API — 开发者对接文档

👉 交互式 API 文档(在线调试 / 完整 schema): https://openapi.redex.vip/docs/

RedEx eSIM 开放平台 · B2B 开发者文档(V1)

面向接入 RedEx 旅行数据 eSIM 供货能力的分销/转售合作伙伴。Base URL、appid、secret 由 RedEx 在开户时通过安全渠道提供。

快速开始 Quick Start

  1. 向 RedEx 申请开户,提供商户名称与回调地址 webhookUrl。
  2. 获得 appid + secret + Base URL。
  3. 按「鉴权」算出签名头,发起首个调用(示例:拉取套餐分类)。
# 首个调用(以套餐分类为例)
TS=$(date +%s000)
SIGN=$(printf "%s" "${TS}${SECRET}" | md5sum | awk '{print $1}')
curl -X POST "https://openapi.redex.vip/api/esim/package/category" \
  -H "X-Appid: ${APPID}" -H "X-Timestamp: ${TS}" -H "X-Sign: ${SIGN}" \
  -H "Content-Type: application/json" -d '{}'

环境 Environments

  • 生产 Production:https://openapi.redex.vip
  • 沙盒 Sandbox:暂无独立沙盒;联调测试账号/测试套餐由 RedEx 单独提供。
  • 所有业务接口均为 郵政 + JSON;Content-Type: application/json; charset=utf-8。

鉴权 Authentication

每个请求必带以下请求头:

Header 必填 说明
X-Appid 是 商户 appid
X-Timestamp 是 当前 毫秒级时间戳(字符串)
X-Sign 是 签名 = MD5(timestamp + secret),十六进制,大小写不敏感

签名计算:把 X-Timestamp 的值与你的 secret 直接拼接后做 MD5。鉴权失败返回 code=401(缺少头)或 code=403(签名不匹配)。

通用约定 Standards

  • 统一响应体:{ "code": 0, "data": {...}, "message": "ok", "timestamp": 1718...};code=0 成功,非 0 为错误。
  • 金额:整数,单位为最小货币单位(美分,USD),如 1130 = $11.30。
  • 时间:毫秒级时间戳;流量:字节(Byte)。
  • 幂等:下单以你方 transactionId 去重,务必全局唯一。

状态码 / 错误码

code 含义
0 成功
401 缺少鉴权请求头(X-Appid/X-Timestamp/X-Sign)
403 签名不匹配 / appid 无效
余额不足类 (预付钱包上线后)商户余额不足,拒单
其它 业务错误,见 message

接口 API

1. 套餐分类(树形)

POST /api/esim/package/category · 无业务入参 · 返回启用中的分类树。

// data: 分类节点树
{ "id": 7, "pid": 0, "category": "Japan", "children": [ ... ] }

2. 套餐列表(分页 / 筛选)

POST /api/esim/package

请求参数:

字段 类型 说明
categoryId int 分类 ID(可选)
productType int 产品类型(可选)
dataType string 数据类型(可选,如 fixed/unlimited)
withCall / withSMS bool 筛选带通话 / 短信套餐
volume / volumeUnit long / string 容量 + 单位(GB/MB)
validity int 有效天数
packageCode / productId string 精确查指定套餐
pageNum / pageSize int 分页(默认 1 / 20)

响应 data: { packageList: [...], total },套餐字段:

字段 说明
packageCode 套餐码(下单用)
productName / productId 名称 / 产品ID
geography / region / regionName 覆蓋範圍
dataType / volume / validity 类型 / 容量(字节)/ 有效天数
price 价格(分)
withCall / withSMS 是否含通话 / 短信
locationNetworkList 覆盖地区+运营商:[{locationName, locationCode, operatorList:[{operatorName, networkType}]}]
apn / ipExport / throttle APN / 出口IP国 / 限速策略(FUP)
activation / unusedValidTime 激活策略 / 未使用有效期

3. 创建订单

POST /api/order/create

{
  "transactionId": "你方唯一单号(幂等键)",
  "packageInfoList": [
    { "packageCode": "PKG_xxx", "count": 1, "price": 1130, "periodNum": 1, "startDate": "2026-07-01" }
  ],
  "additionalInfo": {}
}
  • count:数量;periodNum:周期数(默认 1,Day Pass 类按天数);price:分(展示用,服务端以我方定价为准)。
  • startDate:仅出行日期/预约款必填(指定激活日,异步出卡)。

响应:{ "orderNo": "RX...", "transactionId": "...", "price": 1130 }

4. 获取配置文件(出卡 / QR)

POST /api/esim/profile · 入参 { orderNo, esimTranNo, pageNum, pageSize }

返回字段 说明
esimTranNo eSIM 流水号(后续查询/充值用)
ac 激活码 LPA/QR 字符串(生成二维码)
iccid / imsi / eid / msisdn 卡标识 / 号码
installStatus / smsStatus 安装状态 / 短信状态
actualStartTime / plannedEndTime 实际激活 / 计划到期(毫秒)
dataUsage / totalData 已用 / 总流量(字节)

5. 查询安装/使用状态

POST /api/esim/status · 入参 esimTranNo 或 iccid · 返回 { eid, iccid, qrStatus, installStatus, esimTranNo }

6. 查询流量

POST /api/esim/usage · 返回 { esimUsageList: [{ esimTranNo, dataUsage, totalData, plannedEndTime }] }(流量单位字节)

7. 充值(Top-up)

  • 可充值套餐:POST /api/esim/topup/package(入参 esimTranNo 或 packageCode)→ { topUpData: [...] }
  • 执行充值:POST /api/esim/topup → { transactionId, orderNo, plannedEndTime }

回调 Webhook(RedEx → 你方 webhookUrl)

eSIM 生命周期事件以 郵政 推送到你方登记的 webhookUrl:

{
  "notifyType": "DATA_USAGE",            // ESIM_STATUS / DATA_USAGE / SMDP_EVENT
  "notifyId": "唯一通知ID(幂等去重)",
  "eventGenerateTime": 1718533200000,
  "content": {
    "orderNo": "RX...", "transactionId": "...", "esimTranNo": "...",
    "iccid": "...", "totalData": 1073741824, "dataUsage": 52428800,
    "remain": 1021313024, "lastUpdateTime": 1718533200000
  }
}
notifyType 触发
ESIM_STATUS 安装/使用状态变更
DATA_USAGE 流量用量更新
SMDP_EVENT SM-DP+ 下载/激活事件

要求:你方在 ~5 秒内返回 2xx;用 notifyId 幂等去重;失败 RedEx 会重试。

对接时序

  1. 拉分类/套餐 → 选 packageCode
  2. order/create(带 transactionId)→ 得 orderNo
  3. esim/profile 取 ac(QR)交付终端用户(预约款等异步出卡+回调)
  4. 监听 webhook ESIM_STATUS/DATA_USAGE,或轮询 status/usage
  5. 续费 → topup

字段字典

  • installStatus:未安装 / 已安装 / 已启用(具体枚举随响应)。
  • networkType:运营商网络制式(4G/5G)。
  • throttle:FUP 限速(到量后降速)套餐的限速参数。
  • ipExport:出口 IP 所在国(USIP/本地 IP 场景)。

更新日志 Changelog

  • V1(2026-06):首版 —— 套餐分类/列表、下单、出卡(QR)、状态、流量、充值、Webhook(ESIM_STATUS/DATA_USAGE/SMDP_EVENT)。
  • 规划中:商户预付余额查询(/api/merchant/balance)、低余额告警、签名升级 HMAC-SHA256(签 body + nonce)。

对接支持:联系 RedEx 对接人获取 Base URL、测试凭据与沙盒套餐。