你可以构建什么
完整的 eSIM 生命周期，尽在你的产品之中
从选择套餐到旅途中充值，客户的每一步都是由你掌控的一次 API 调用。
销售目录中的任意套餐
按国家、地区、流量和时长筛选套餐，然后一次调用即可为客户下单。每个套餐都会返回你需要为它支付的价格。
- 按国家、地区、流量和天数筛选
- 订单从你的预付余额中扣款
- 幂等键让重试安全无虞
在你自己的流程中交付 eSIM
订单完成后，你可以通过 Webhook 或查询订单获取 ICCID、LPA 激活字符串和二维码。
- 带签名的 order.fulfilled Webhook
- PNG 格式二维码，可直接展示或通过邮件发送
- LPA 字符串，支持在你的 App 中一键安装
售后也让旅客保持连接
提供流量充值、将 eSIM 迁移到新手机、为符合条件的订单退款并下载发票，全部通过同一套 API 完成。
- 按你的账户定价的流量充值
- 在新设备上重新安装 eSIM
- 每笔订单的退款和 PDF 发票
为开发者打造
放心上线所需的一切
免费沙盒
测试密钥可跑通从下单到 eSIM 再到 Webhook 的完整流程，不调用运营商网络，也不消耗余额。
请求签名
每个请求都使用 HMAC-SHA256 和时间戳签名，重放请求会被拒绝。密钥可限制为仅允许你服务器的 IP 地址使用。
自动重试的 Webhook
订单、eSIM、充值和余额相关的签名事件会按退避策略重试一天以上，并提供可重新投递的投递日志。
重试无忧
为订单和充值请求附带 Idempotency-Key。24 小时内的重复请求会返回首次响应，而不会重复扣款。
OpenAPI 3.1 规范
将规范导入 Postman 或生成带类型的客户端，也可以从文档中的 curl、Node 和 Python 示例开始。
分级密钥，限额清晰
为每个密钥授予只读、下单或完全访问权限。速率限制按密钥计算，每个经过认证的响应都会显示剩余额度。
文档
浏览文档
每个端点都提供可复制的请求和响应示例。用你的密钥签名，指向沙盒，即可开始。
请求
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 只是销售方式之一。下面这些方案使用同一套目录、余额和履约体系。