合作夥伴 API
把旅遊 eSIM 整合進你的產品
用一套 REST API，從你自己的應用程式或網站銷售 eSIM。搜尋目錄、下單，並以你的品牌將可直接安裝的 eSIM 交付給顧客。
API 呼叫api.roamgo.net
你可以打造什麼
完整的 eSIM 生命週期，全在你自己的產品裡
從挑選方案到旅途中加值，顧客的每一步都是由你掌控的 API 呼叫。
銷售目錄中的任何方案
依國家、區域、流量和天數篩選方案，再用一次呼叫為顧客下單。每個方案回傳時，都會附上你需為它支付的價格。
- 依國家、區域、流量和天數篩選
- 訂單從你的預付儲值金扣款
- 冪等金鑰確保重試安全
在你自己的流程中交付 eSIM
訂單完成開通後，你可以透過 Webhook 或讀取訂單，取得 ICCID、LPA 啟用字串和 QR 碼。
- 已簽章的 order.fulfilled Webhook
- PNG 格式的 QR 碼，可直接顯示或以電子郵件寄送
- LPA 字串，可在你的應用程式中一鍵安裝
售後也讓旅客保持連線
提供流量加值、將 eSIM 移轉到新手機、為符合資格的訂單退款並下載發票，全都透過同一套 API。
- 依你的帳戶定價的加值方案
- 在新裝置上重新安裝 eSIM
- 每筆訂單的退款與 PDF 發票
為開發者打造
安心上線所需的一切
免費 Sandbox
測試金鑰可跑完整個流程，從訂單、eSIM 到 Webhook，不會呼叫電信網路，也不會動用儲值金。
簽章請求
每個請求都以 HMAC-SHA256 和時間戳記簽章，重放的請求會被拒絕。金鑰也可限定只接受你伺服器的 IP 位址。
自動重試的 Webhook
訂單、eSIM、加值與儲值金的簽章事件，會以逐步拉長的間隔重試超過一天，並提供可重新傳送的投遞紀錄。
可安全重試
下單和加值時附上 Idempotency-Key。24 小時內的重複請求會回傳第一次的回應，不會重複扣款。
OpenAPI 3.1 規格
將規格匯入 Postman 或產生具型別的用戶端，也可以從說明文件中的 curl、Node 和 Python 範例開始。
權限分明的金鑰，清楚的限制
為每把金鑰設定讀取、下單或完整權限。速率限制以金鑰為單位，每個通過驗證的回應都會顯示剩餘額度。
說明文件
探索說明文件
每個端點都附有可直接複製的請求與回應。用你的金鑰簽章、指向 Sandbox，就能開始。
請求
curl --request GET \
--url 'https://api.roamgo.net/api/partner/v1/plans?country=JP&minDays=7' \
--header 'Authorization: Roamgo-HMAC-SHA256 keyId=<KEY_ID>, ts=<UNIX>, sig=<SIGNATURE>'回應
{
"plans": [{
"id": "cm...",
"name": "Japan · 10 GB · 30 days",
"region": "Japan",
"countries": ["JP"],
"dataAmountMB": 10240,
"validityDays": 30,
"yourPriceCents": 1840,
"currency": "USD"
}],
"page": 1,
"pageSize": 24,
"total": 18
}請求
curl --request POST \
--url 'https://api.roamgo.net/api/partner/v1/orders' \
--header 'Authorization: Roamgo-HMAC-SHA256 keyId=<KEY_ID>, ts=<UNIX>, sig=<SIGNATURE>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <UNIQUE_KEY>' \
--data '{"planId":"cm_plan_id","quantity":1,"customerEmail":"traveler@example.com","externalRef":"BOOKING-49102"}'回應
HTTP/1.1 202 Accepted
{
"order": {
"id": "cm_order_id",
"status": "PAID",
"customerEmail": "traveler@example.com",
"totalCents": 1840,
"currency": "USD"
}
}請求
curl --request GET \
--url 'https://api.roamgo.net/api/partner/v1/esims/cm_esim_id/qr' \
--header 'Authorization: Roamgo-HMAC-SHA256 keyId=<KEY_ID>, ts=<UNIX>, sig=<SIGNATURE>' \
--output esim-qr.png回應
HTTP/1.1 200 OK
Content-Type: image/png
Cache-Control: private, max-age=3600請求
curl --request POST \
--url 'https://api.roamgo.net/api/partner/v1/esims/cm_esim_id/topups' \
--header 'Authorization: Roamgo-HMAC-SHA256 keyId=<KEY_ID>, ts=<UNIX>, sig=<SIGNATURE>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <UNIQUE_KEY>' \
--data '{"topUpProviderPlanId":"tu_q3J9v0cX2mBf7Lr1sPz8Kd","externalRef":"BOOKING-49102-TOPUP-1"}'回應
HTTP/1.1 201 Created
{
"topUp": {
"id": "cm_topup_id",
"status": "COMPLETED",
"priceCents": 480,
"currency": "USD"
}
}請求
import crypto from "node:crypto";
// X-Roamgo-Signature: t=<unix>,v1=<hex>
export function verifyRoamgoSignature(rawBody: string, header: string, secret: string) {
const match = header.match(/^t=(\d+),v1=([0-9a-f]+)$/);
if (!match) return false;
const [, ts, v1] = match;
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(`${ts}.${rawBody}`)
.digest("hex");
return crypto.timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(v1, "hex"));
}回應
{
"id": "evt_8d…",
"type": "order.fulfilled",
"createdAt": "2026-09-30T09:14:02.118Z",
"livemode": true,
"data": {
"order": {
"id": "cm_order_id",
"status": "FULFILLED",
"items": [{
"esims": [{
"iccid": "8910…",
"lpaString": "LPA:1$...",
"status": "ISSUED"
}]
}]
}
}
}API 參考
一套 API，涵蓋銷售的每個環節
每項資源都連結到對應的參考文件，包含參數、錯誤和範例。
選擇你的方式
整合 API，或不寫程式直接上線
API 只是其中一種銷售方式。以下選項都使用同一份目錄、同一筆儲值金與同樣的開通流程。