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

同步範圍

會同步	已上架、已設定分銷價、非實體發貨的商品
不會同步	實體發貨商品、未設定分銷價的商品、已下架商品
庫存顯示	共享介面對異次元返回虛擬庫存 `9999`，實際是否可發貨以下單時結果為準
扣款方式	異次元下單成功後，從本站賬戶餘額扣除分銷價

注意事項

重新生成本站分銷 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）

響應資料

響應欄位說明

介面狀態碼