MeSIM 分销 API

顶级上游对接

全球 eSIM 顶级上游，支援平台、代理自动化业务接入。

登录后查看 API 专属价格

欢迎您随时联系商务对接，完整接入流程登录后开放。

登录联系商务

接入说明

API 作用

分销 API 是方便您实现批次购买 eSIM 服务的介面，购买费用直接从账户余额中扣除，请保持余额充足。若介面返回余额不足，请及时充值。

介面基本信息

Base URL	`https://mesimgo.com/api/v1`
请求方式	POST / GET
返回格式	JSON
认证方式	Token 请透过请求头部传递：`Authorization: Bearer {token}`

当前有效 Token

warning 登录后可获取 Token

获取型别ID（categoryId）

呼叫购买、详情、库存等介面时，需要传入 categoryId 引数。以下是当前全部可购买产品：

warning 登录后可查看价格并复制 categoryId。

categoryId	名称	商品详情	原价	分销价	库存
登录后可复制	CSL 30G	登录后可查看	登录后可见	登录后可见	缺货
登录后可复制	CSL 40G	登录后可查看	登录后可见	登录后可见	缺货
登录后可复制	MeSIM 12国吃到饱 100G	登录后可查看	登录后可见	登录后可见	缺货
登录后可复制	MeSIM 12国吃到饱 50G	登录后可查看	登录后可见	登录后可见	缺货
登录后可复制	CMLink 吃到饱10G	登录后可查看	登录后可见	登录后可见	缺货
登录后可复制	乐天吃到饱4G	登录后可查看	登录后可见	登录后可见	缺货
登录后可复制	CMLink 52国吃到饱10g	登录后可查看	登录后可见	登录后可见	缺货
登录后可复制	CMLink 52国吃到饱20G	登录后可查看	登录后可见	登录后可见	缺货
登录后可复制	大众电讯 30G	登录后可查看	登录后可见	登录后可见	缺货
登录后可复制	orange 20g	登录后可查看	登录后可见	登录后可见	缺货
登录后可复制	3HK 15G	登录后可查看	登录后可见	登录后可见	缺货
登录后可复制	3HK 24G	登录后可查看	登录后可见	登录后可见	缺货
登录后可复制	True 6G	登录后可查看	登录后可见	登录后可见	缺货

通用响应格式

{
    "status": true,       // 请求状态：true 成功，false 失败
    "code": 0,            // 状态码，0 表示成功
    "msg": "获取成功",     // 请求说明
    "data": { ... }       // 请求数据（失败时可能无此栏位）
}

全域性状态码

状态码	说明
`0`	请求成功
`40000`	API 功能未启用
`24002`	Token 缺失、无效、已禁用或已过期
`40001`	IP 不在白名单内
`42900`	请求频率超限
`24001`	型别不存在
`40003`	账号已被冻结
`24005`	引数错误
`22003`	库存不足
`22004`	订单生成失败
`21006`	发货失败
`21010`	余额不足
`50010`	系统配置异常，请联系平台处理
`20000`	订单生成成功（正式已发货 / 测试）
`20001`	订单已建立，等待人工发货；请轮询订单详情

请以本页列出的公开介面为准。

异次元对接

play_arrow 介面操作

配置方式

异次元发卡网可透过共享平台介面直接拉取本站分销商品、查询库存并下单。异次元后台新增共享平台时，请填写以下引数：

平台型别	预设共享平台介面（type 0）
平台地址	`https://mesimgo.com`
app_id	如果您用邮箱登录，请绑定 Telegram 后即可显示 app_id
app_key	填写上方“当前有效 Token”里的 API Token

同步范围

会同步	已上架、已设定分销价的自动发货商品
不会同步	人工/实体发货商品、未设定分销价的商品、已下架商品
库存显示	上游库存新鲜且有货时返回虚拟库存 `999`；缺货、同步超时或状态异常时返回 `0`
扣款方式	异次元下单成功后，从本站账户余额扣除分销价

注意事项

重新生成本站分销 API Token 后，异次元后台的 app_key 必须同步更换。
请保持本站账户余额充足，余额不足时异次元下单会失败。
如果设定了 IP 白名单，请把异次元伺服器出口 IP 加入白名单。
同一笔订单重试时，异次元应保持相同请求单号，避免重复下单。
异次元官方汇入流程不会同步“发送邮件”开关；需要邮件发货时，请在下游商品编辑页手动开启。

IP白名单

设定 IP 白名单后，仅限白名单内 IP 才可发起请求。不设定则不限制。

白名单按服务端识别到的当前请求 IP 精确匹配，不支援 CIDR、网段或万用字元；为空或 null 表示不限制。白名单校验发生在 Token 认证之后。

play_arrow 线上测试

查看白名单

GET https://mesimgo.com/api/v1/whitelist

Headers

Header 名	型别	必填	说明
`Authorization`	string	是	`Bearer {token}`，用于身份认证

* 请勿将 token 放在 query/body 引数中，预设配置不读取引数 token。

请求引数（Query / Body）

引数名	型别	必填	说明
无

响应数据

{
    "status": true,
    "code": 0,
    "msg": "获取成功",
    "data": {
        "ips": ["1.2.3.4", "5.6.7.8"],
        "currentIp": "1.2.3.4"
    }
}

响应栏位说明

栏位	型别	说明
`status`	boolean	请求状态：true 成功，false 失败
`code`	number	状态码
`msg`	string	请求说明
`data.ips`	array	当前白名单 IP 列表
`data.currentIp`	string	当前请求 IP

更新白名单

POST https://mesimgo.com/api/v1/whitelist

Headers

Header 名	型别	必填	说明
`Authorization`	string	是	`Bearer {token}`，用于身份认证

* 请勿将 token 放在 query/body 引数中，预设配置不读取引数 token。

请求引数（Query / Body）

引数名	型别	必填	说明
`ips`	array	否	IP 地址阵列，传空阵列 [] 清空白名单
`clear`	number	否	传 1 时清空白名单；建议清空时使用 clear=1，避免空阵列编码差异

响应数据

{
    "status": true,
    "code": 0,
    "msg": "白名单更新成功",
    "data": {
        "ips": ["1.2.3.4"]
    }
}

响应栏位说明

栏位	型别	说明
`status`	boolean	请求状态：true 成功，false 失败
`code`	number	状态码
`msg`	string	请求说明
`data.ips`	array	更新后的白名单 IP 列表

eSIM购买

science 为方便开发除错，我们提供测试介面用于余额支付除错。测试介面除错余额不会被实际扣除，实际部署务必使用正式介面。

测试介面	`https://mesimgo.com/api/v1/payTest`
正式介面	`https://mesimgo.com/api/v1/pay`

play_arrow 线上测试

产品 (categoryId)

客户端订单号（可选）

介面型别

测试正式

请求数量

请求介面

POST https://mesimgo.com/api/v1/pay 测试：https://mesimgo.com/api/v1/payTest

Headers

Header 名	型别	必填	说明
`Authorization`	string	是	`Bearer {token}`，用于身份认证

* 请勿将 token 放在 query/body 引数中，预设配置不读取引数 token。

请求引数（Query / Body）

引数名	型别	必填	说明
`categoryId`	number	是	eSIM 型别 ID（参见接入说明中的产品列表）
`clientOrderNo`	string	否	客户端订单号，1-64位字母/数字/点/下划线/短横线；仅正式介面 /api/v1/pay 生效，用于超时重试幂等；/api/v1/payTest 不支援也不保证幂等

响应数据

{
    "status": true,
    "code": 20000,
    "msg": "订单生成成功",
    "data": {
        "sn": "APIxxxxxxxxxxx",
        "verifyCode": "123456",
        "currency": "USD",
        "categoryId": 31,
        "consumption": 5.5,
        "carrier": "运营商名称",
        "brand": "品牌名称",
        "lpa": "LPA:1$xxx.prod.example.com$XXXXXX",
        "number": "86866878",
        "balance": 77.5,
        "qrcode": "data:image/png;base64,iVBORw0KGgo..."
    }
}

响应栏位说明

栏位	型别	说明
`status`	boolean	请求状态：true 成功，false 失败
`code`	number	状态码
`msg`	string	请求说明
`data.sn`	string	订单号
`data.currency`	string	货币型别
`data.categoryId`	number	eSIM 型别 ID
`data.consumption`	number	本次消耗余额
`data.carrier`	string	运营商
`data.brand`	string	品牌
`data.lpa`	string	eSIM 配置（用于生成安装二维码）
`data.number`	string	eSIM 卡号码
`data.verifyCode`	string	eSIM 配置验证码
`data.balance`	number	账户剩余余额
`data.qrcode`	string	eSIM 安装二维码 base64，可直接作为 <img src="..."> 使用

介面状态码

状态码	说明
`20000`	订单生成成功（正式已发货）
`20001`	订单已建立，等待人工发货；请轮询订单详情
`20000`	订单生成成功（测试，余额未扣除）
`24001`	型别不存在
`24005`	引数错误
`22003`	库存不足；预检失败时直接返回，已生成订单后缺货会非同步触发库存不足回拨
`22004`	订单生成失败
`21010`	余额不足
`21006`	发货失败（订单已记录；如原因为库存不足，会触发库存不足回拨）
`50010`	系统配置异常，请联系平台处理

warning 重要：正式购买会扣除余额；如发货异常，平台会根据订单实际处理结果完成发货、退款或转人工处理，请以订单查询结果为准。

webhook 正式购买库存预检失败时直接返回 22003；如果订单已建立但发货阶段确认库存不足无法供货，系统会向该商品配置的 HTTPS 回拨地址传送 stock_insufficient JSON 通知。测试介面 /payTest 不触发该通知。完整栏位和安全边界见“回拨通知”。

clientOrderNo 只在正式介面 /api/v1/pay 生效；测试介面 /api/v1/payTest 每次呼叫都可能生成新的 TEST 订单，不支援也不保证幂等。

回拨通知

公共说明

平台会向您配置的 HTTPS 回拨地址以 POST 方式传送 JSON。请接收方返回 2xx，并自行按订单号或事件 ID 做幂等处理。

security 回拨通知暂不作为唯一可信依据，请以订单查询结果为准，并做好 HTTPS、幂等和访问控制。

普通订单完成回拨

触发条件：订单完成后，平台向您配置的回拨地址传送完成通知。/api/v1/pay 直接成功返回不代表一定会触发此普通完成回拨，API 订单最终状态请优先透过 /api/v1/order 轮询确认。

请求方式	`POST`
Content-Type	`application/json`
响应要求	请返回 2xx，并透过订单查询介面做结果补偿。

{
    "title": "商品名称 x 1",
    "order_sn": "APIxxxxxxxxxxxxx",
    "email": "[email protected]",
    "actual_price": "5.50",
    "order_info": "LPA:1$xxx.prod.example.com$XXXXXX",
    "good_id": 31,
    "gd_name": "商品名称"
}

栏位	型别	说明
`title`	string	订单标题
`order_sn`	string	订单号；接收方应以此做幂等
`email`	string	订单邮箱，可能为空
`actual_price`	number\|string	订单实付金额
`order_info`	string	发货内容或订单备注，具体格式随商品型别变化
`good_id`	number	商品 ID
`gd_name`	string	商品名称

库存不足回拨（stock_insufficient）

触发条件：正式介面 /api/v1/pay 下单后已建立订单，但发货阶段确认库存不足或无法供货。预检阶段直接返回 22003 时不会传送该回拨；测试介面 /api/v1/payTest 不触发该回拨。

请求方式	`POST`
Content-Type	`application/json`，并带 `Accept: application/json`
地址限制	仅允许 `https://`；拒绝 localhost、私有 IP 和保留 IP。
响应要求	请返回 2xx，并透过订单查询介面确认最终状态。

{
    "event": "stock_insufficient",
    "status": false,
    "code": 22003,
    "msg": "库存不足，订单无法供货",
    "categoryId": 31,
    "good_id": 31,
    "gd_name": "商品名称",
    "clientOrderNo": "your-order-001",
    "eventId": "sha256-event-id",
    "occurredAt": "2026-04-30T12:34:56+00:00",
    "sn": "APIxxxxxxxxxxxxx"
}

栏位	型别	说明
`event`	string	固定为 `stock_insufficient`
`status`	boolean	固定为 `false`
`code`	number	固定为 `22003`
`msg`	string	库存不足说明
`categoryId`	number	eSIM 型别 ID
`good_id`	number	商品 ID
`gd_name`	string	商品名称
`clientOrderNo`	string\|null	正式下单传入的客户端订单号；未传时为 `null`
`eventId`	string	事件 ID；用于接收方幂等去重
`occurredAt`	string	ISO 8601 时间
`sn`	string	已建立订单的订单号；仅订单已建立时存在

该通知只包含上方栏位。收到回拨后建议呼叫 /api/v1/order 按 sn 查询最终订单状态。

余额查询

play_arrow 线上测试

代理商系统下单前需确认余额是否充足，避免下单失败。

GET https://mesimgo.com/api/v1/balance

Headers

Header 名	型别	必填	说明
`Authorization`	string	是	`Bearer {token}`，用于身份认证

* 请勿将 token 放在 query/body 引数中，预设配置不读取引数 token。

请求引数（Query / Body）

引数名	型别	必填	说明
无

响应数据

{
    "status": true,
    "code": 0,
    "msg": "获取成功",
    "data": {
        "balance": 252.05,
        "currency": "USD"
    }
}

响应栏位说明

栏位	型别	说明
`status`	boolean	请求状态：true 成功，false 失败
`code`	number	状态码
`msg`	string	请求说明
`data.balance`	number	账户余额
`data.currency`	string	货币型别

库存查询

play_arrow 线上测试

代理商系统下单前需确认库存是否充足，避免下单失败。

GET https://mesimgo.com/api/v1/esimStore

Headers

Header 名	型别	必填	说明
`Authorization`	string	是	`Bearer {token}`，用于身份认证

* 请勿将 token 放在 query/body 引数中，预设配置不读取引数 token。

请求引数（Query / Body）

引数名	型别	必填	说明
`categoryId`	number	是	eSIM 型别 ID

响应数据

{
    "status": true,
    "code": 0,
    "msg": "获取成功",
    "data": {
        "esimStore": 1,
        "categoryId": "31"
    }
}

响应栏位说明

栏位	型别	说明
`status`	boolean	请求状态：true 成功，false 失败
`code`	number	状态码
`msg`	string	请求说明
`data.esimStore`	number	是否有库存：1 有，0 无
`data.categoryId`	string	eSIM 型别 ID

产品列表

play_arrow 线上测试

GET https://mesimgo.com/api/v1/products

Headers

Header 名	型别	必填	说明
`Authorization`	string	是	`Bearer {token}`，用于身份认证

* 请勿将 token 放在 query/body 引数中，预设配置不读取引数 token。

请求引数（Query / Body）

引数名	型别	必填	说明
无

响应数据

{
    "status": true,
    "code": 0,
    "msg": "获取成功",
    "data": [
        {
            "id": 31,
            "name": "产品名称",
            "vipPrice": 6.5,
            "sellCurrency": "USD",
            "note": "产品说明",
            "hasNumber": 0,
            "needRealname": 0,
            "highSpeedFlow": 0,
            "trafficType": 1,
            "renew": 0,
            "lifetime": 365,
            "periodType": "month",
            "esimStore": 1,
            "brandInfo": {
                "id": 18,
                "brand": "品牌名称"
            },
            "regionCode": "HK",
            "roamingRegionList": []
        }
    ]
}

响应栏位说明

栏位	型别	说明
`status`	boolean	请求状态：true 成功，false 失败
`code`	number	状态码
`msg`	string	请求说明
`data[].id`	number	eSIM 型别 ID（即 categoryId）
`data[].name`	string	eSIM 名称
`data[].vipPrice`	number	您的会员价格
`data[].sellCurrency`	string	货币型别
`data[].note`	string	产品说明
`data[].hasNumber`	number	是否有号码：1 有，0 无
`data[].needRealname`	number	是否需要实名：1 需要，0 不需要
`data[].highSpeedFlow`	number	高速流量（单位：MB）
`data[].trafficType`	number	流量型别
`data[].renew`	number	是否可续费：1 可，0 不可
`data[].lifetime`	number	有效期（单位：天）
`data[].periodType`	string	流量计算周期：month 每月，day 每日，total 总量
`data[].esimStore`	number	是否有库存：1 有，0 无
`data[].brandInfo`	object	品牌信息：id - 品牌ID，brand - 品牌名称
`data[].regionCode`	string	卡归属地程式码（ISO 3166-1）
`data[].roamingRegionList`	array	可用漫游地程式码列表

产品详情

play_arrow 线上测试

GET https://mesimgo.com/api/v1/product

Headers

Header 名	型别	必填	说明
`Authorization`	string	是	`Bearer {token}`，用于身份认证

* 请勿将 token 放在 query/body 引数中，预设配置不读取引数 token。

请求引数（Query / Body）

引数名	型别	必填	说明
`categoryId`	number	是	eSIM 型别 ID

响应数据

{
    "status": true,
    "code": 0,
    "msg": "获取成功",
    "data": {
        "id": 31,
        "name": "产品名称",
        "vipPrice": 6.5,
        "sellCurrency": "USD",
        "note": "产品说明",
        "hasNumber": 0,
        "needRealname": 0,
        "highSpeedFlow": 0,
        "trafficType": 1,
        "renew": 0,
        "lifetime": 365,
        "periodType": "month",
        "esimStore": 1,
        "brandInfo": {
            "id": 18,
            "brand": "品牌名称"
        },
        "regionCode": "HK",
        "roamingRegionList": []
    }
}

响应栏位说明

栏位	型别	说明
`status`	boolean	请求状态：true 成功，false 失败
`code`	number	状态码
`msg`	string	请求说明
`data`	object	产品详情，栏位同产品列表中的单个产品物件

介面状态码

状态码	说明
`0`	获取成功
`24001`	型别不存在
`24005`	引数错误：缺少 categoryId

订单列表

play_arrow 线上测试

页码

每页数量

订单型别

订单状态

GET https://mesimgo.com/api/v1/orders

Headers

Header 名	型别	必填	说明
`Authorization`	string	是	`Bearer {token}`，用于身份认证

* 请勿将 token 放在 query/body 引数中，预设配置不读取引数 token。

请求引数（Query / Body）

引数名	型别	必填	说明
`page`	number	否	页码（预设 1）
`pageSize`	number	否	每页数量（预设 20，最大 100）
`genre`	string	否	订单型别：purchase - 购买订单（当前 API 仅开放购买订单查询）
`status`	string	否	订单状态：pending - 待支付/待处理/处理中，payed - 已完成，closed - 已关闭，refused - 异常/已拒绝

响应数据

{
    "status": true,
    "code": 0,
    "msg": "获取成功",
    "data": {
        "page": 1,
        "total": 9,
        "totalPage": 1,
        "results": [
            {
                "sn": "APIxxxxxxxxxxx",
                "member": 123456,
                "payFrom": "balance",
                "status": "payed",
                "currency": "USD",
                "targetId": 31,
                "addtime": 20260305162723,
                "genre": "purchase",
                "totalFee": 6.5,
                "voucherInfo": [ ... ],
                "categoryInfo": {
                    "id": 31,
                    "name": "产品名称",
                    "vipPrice": 6.5,
                    "sellCurrency": "USD",
                    "regionCode": "HK",
                    "roamingRegionList": []
                },
                "brandInfo": {
                    "id": 18,
                    "brand": "品牌名称"
                }
            }
        ]
    }
}

响应栏位说明

栏位	型别	说明
`status`	boolean	请求状态：true 成功，false 失败
`code`	number	状态码
`msg`	string	请求说明
`data.page`	number	当前页码
`data.total`	number	总订单数
`data.totalPage`	number	总页数
`data.results`	array	订单列表
`results[].sn`	string	订单编号
`results[].status`	string	订单状态：payed / pending / closed / refused；pending 包含待支付、待处理、处理中
`results[].genre`	string	订单型别：purchase 购买
`results[].addtime`	number	建立时间（YYYYMMDDHHmmss 格式）
`results[].totalFee`	number	订单金额
`results[].currency`	string	货币型别
`results[].voucherInfo`	array	eSIM 凭证（已支付含 lpa/number/verifyCode/qrcode）
`results[].categoryInfo`	object	eSIM 型别信息
`results[].brandInfo`	object	品牌信息

订单详情

play_arrow 线上测试

GET https://mesimgo.com/api/v1/order

Headers

Header 名	型别	必填	说明
`Authorization`	string	是	`Bearer {token}`，用于身份认证

* 请勿将 token 放在 query/body 引数中，预设配置不读取引数 token。

请求引数（Query / Body）

引数名	型别	必填	说明
`sn`	string	是	订单编号

响应数据

{
    "status": true,
    "code": 0,
    "msg": "获取成功",
    "data": {
        "sn": "APIxxxxxxxxxxx",
        "member": 123456,
        "payFrom": "balance",
        "totalFee": 6.5,
        "genre": "purchase",
        "status": "payed",
        "currency": "USD",
        "targetId": 31,
        "addtime": 20260210170728,
        "voucherInfo": {
            "orderSn": "APIxxxxxxxxxxx",
            "categoryId": 31,
            "lpa": "LPA:1$xxx.prod.example.com$XXXXXX",
            "status": 1,
            "number": "86866878",
            "verifyCode": "123456",
            "qrcode": "data:image/png;base64,iVBORw0KGgo..."
        },
        "categoryInfo": {
            "id": 31,
            "name": "产品名称",
            "vipPrice": 6.5,
            "sellCurrency": "USD",
            "regionCode": "HK",
            "roamingRegionList": []
        },
        "brandInfo": {
            "id": 18,
            "brand": "品牌名称"
        }
    }
}

响应栏位说明

栏位	型别	说明
`status`	boolean	请求状态：true 成功，false 失败
`code`	number	状态码
`msg`	string	请求说明
`data.sn`	string	订单编号
`data.status`	string	订单状态：payed / pending / closed / refused
`data.totalFee`	number	订单金额
`data.addtime`	number	订单建立时间
`data.voucherInfo`	object	eSIM 凭证信息（详情为物件，列表为阵列）
`voucherInfo.lpa`	string	eSIM 配置（用于生成安装二维码）
`voucherInfo.number`	string	eSIM 号码
`voucherInfo.verifyCode`	string	验证码
`voucherInfo.qrcode`	string	eSIM 安装二维码（base64）
`data.categoryInfo`	object	eSIM 型别信息
`data.brandInfo`	object	品牌信息

介面状态码

状态码	说明
`0`	获取成功
`24001`	订单不存在
`24005`	引数错误：缺少 sn

账号登录

登录成功！

顶级上游对接

接入说明

API 作用

介面基本信息

当前有效 Token

获取型别ID（categoryId）

通用响应格式

全域性状态码

异次元对接

play_arrow 介面操作

配置方式

同步范围

注意事项

IP白名单

play_arrow 线上测试

查看白名单

Headers

请求引数（Query / Body）

响应数据

响应栏位说明

更新白名单

Headers

请求引数（Query / Body）

响应数据

响应栏位说明

eSIM购买

play_arrow 线上测试

请求介面

Headers

请求引数（Query / Body）

响应数据

响应栏位说明

介面状态码

回拨通知

公共说明

普通订单完成回拨

库存不足回拨（stock_insufficient）

余额查询

play_arrow 线上测试

Headers

请求引数（Query / Body）

响应数据

响应栏位说明

库存查询

play_arrow 线上测试

Headers

请求引数（Query / Body）

响应数据

响应栏位说明

产品列表

play_arrow 线上测试

Headers

请求引数（Query / Body）

响应数据

响应栏位说明

产品详情

play_arrow 线上测试

Headers

请求引数（Query / Body）

响应数据

响应栏位说明

介面状态码

订单列表

play_arrow 线上测试

Headers

请求引数（Query / Body）

响应数据

响应栏位说明

订单详情

play_arrow 线上测试

Headers

请求引数（Query / Body）

响应数据

响应栏位说明

介面状态码