跳到正文
iRoamly Shop
开发者

API 文档

iRoamly Shop API 参考：身份验证、套餐、购买与交付、续费及用量。

概述

基本说明

为确保服务器传输信息的安全，采用以下安全机制：

  1. 1.所有接口均通过 HTTPS secure 安全连接传输。
  2. 2.分配给您的 AuthKey，用于 API 身份验证（最长 32 个字符）。
  3. 3.分配给您的 AuthSecret，用于生成请求哈希（最长 50 个字符）。
  4. 4.请求使用 SHA-256 哈希进行身份验证。
概述

接口规范

基础路径：https://api.iroamly.shop/
请求协议：HTTPS
请求方法：GET / POST
数据传输格式：application/json

请求头参数：

AuthKey：客户身份验证密钥，类型为字符串（String）

Certification：字符串，内容为 AuthKey+AuthSecret 按此顺序拼接后的 SHA-256 哈希值。

/common/getPlanItem 无需 AuthKey 或 Certification 请求头。

API 接口

获取区域套餐列表

请求 URL：https://api.iroamly.shop/common/getPlanItem
请求方法：GET

无需 AuthKey 或 Certification 请求头。

请求参数：

参数说明类型
region支持 ISO2 代码、国家名称（不区分大小写）或标准化格式（例如 united-states）。String

响应格式：

成功：HTTP 200。套餐列表在 data.list 中返回。

始终返回 HTTP 200。无数据时，data.list 为空数组，msg 为 Success。

响应字段说明：

字段说明类型
plan套餐名称（包含地区、类型、流量额度和时长）。String
productCode用于购买或查询的唯一套餐 ID。String
data流量额度（例如 10GB, Unlimited, 500MB）。String
type套餐类型（例如 Total, Daily, Unlimited）。String
plan_type套餐类别（例如 default）。String
package_type套餐包类型（例如 Data Only）。String
duration有效期天数（例如 10）。String
speed网络速率（例如 4G / 5G）。String
operator支持的运营商（例如 T-Mobile/AT&T）。String
region官方地区名称（例如 United States）。String
region_index标准化地区标识（小写并以连字符连接，例如 united-states）。String
credit套餐价格，单位为点（不是美元）。Float
remark附加说明（例如限速规则）。String
created_at套餐创建时间戳（ISO 8601 格式）。String
请求示例
"https://api.iroamly.shop/common/getPlanItem?region=US"
返回示例
{
  "code": 0,
  "data": {
    list:[
     {
       "plan": "United States-eSIM-10GB-10 Days-Total",
       "productCode": "iRoamly-unite-584535",
       "data": "10GB",
       "type": "Total",
       "package_type": "Data Only",
       "duration": "10",
       "speed": "4G / 5G",
       "operator": "T-Mobile/AT&T",
       "region": "United States",
       "region_index": "united-states",
       "credit": 6.43,
       "remark": "After accumulating 10GB, the speed will be reduced to 128 Kbps",
       "created_at": "2025-05-16T04:02:31Z"
     }
    ]
  }
}
API 接口

直接购买二维码

请求 URL：https://api.iroamly.shop/openapi/purchaseqrcode
请求方法：POST

请求参数：

参数说明类型
email接收二维码的邮箱。为空时不发送邮件。String
productList产品集合Object[]

productList 字段：

字段说明类型
plan套餐名称。plan 与 productCode 二选一。String
productCode套餐 ID（来自“获取区域套餐列表”的 productCode）。productCode 与 plan 二选一。String
quantity数量Int
测试套餐：iRoamly-Test-10GB

下一步：使用“查询二维码”（https://api.iroamly.shop/openapi/qrcodeQuery）获取二维码

示例参数
{
  "email": "2m827n32d@gmail.com",
  "productList": [
    {
      "plan": "United States-eSIM-10GB-10 Days-Total",
      "quantity": 2
    },
    {
      "plan": "Albania-10GB-15 Days-Total",
      "quantity": 1
    }
  ]
}
返回示例
{
  "code": 1,
  "data": {
    "orderId": "Open-Global-DXDWFBKG578913",
    "redeem_list": [
      {
        "productCode": "",
        "plan": "United States-eSIM-10GB-10 Days-Total",
        "redeemCode": "tjMxpYfvk5dFMQg",
        "status": 0,
        "expire_at": "2026-03-01"
      },
      {
        "productCode": "",
        "plan": "United States-eSIM-10GB-10 Days-Total",
        "redeemCode": "gKPzYhseX1wRmSi",
        "status": 0,
        "expire_at": "2026-03-01"
      },
      {
        "productCode": "",
        "plan": "Albania-10GB-15 Days-Total",
        "redeemCode": "sLSHNkAv2ojbNBG",
        "status": 0,
        "expire_at": "2026-03-01"
      }
    ]
  },
  "msg": "success"
}
API 接口

购买兑换码

请求 URL：https://api.iroamly.shop/openapi/purchaseCode
请求方法：POST

请求参数：

参数说明类型
email邮箱String
productList产品集合Object[]

productList 字段：

字段说明类型
plan套餐名称。plan 与 productCode 二选一。String
productCode套餐 ID（来自“获取区域套餐列表”的 productCode）。productCode 与 plan 二选一。String
quantity数量Int
测试套餐：iRoamly-Test-10GB
示例参数
{
  "email": "2m827n32d@gmail.com",
  "productList": [
    {
      "plan": "United States-eSIM-10GB-10 Days-Total",
      "quantity": 2
    },
    {
      "plan": "Albania-10GB-15 Days-Total",
      "quantity": 1
    }
  ]
}
返回示例
{
  "code": 1,
  "msg": "success",
  "orderId": "xxx-xxxx-sd9hn8df333" // Order number, can be used to query redeem code
}
API 接口

查询兑换码

请求 URL：https://api.iroamly.shop/openapi/codeQuery
请求方法：POST

请求参数：

参数说明类型
orderId订单号String
示例参数
{
  "orderId": "xxx-xxx-dh239jdu28",
}
返回示例
{
  "code": 1,
  "msg": "success",
  "data": [
    {
      "productCode": "m8hed7h2fed",
      "redeemCode": "3cd2m3f23f3f3",
      "expire_at": "2024-06-30", // Expiry date
      "plan": "United States-eSIM-10GB-10 Days-Total",
      "status": 0
    },
    {
      "productCode": "v2jf28dj2w",
      "redeemCode": "d923j29ef2323",
      "expire_at": "2024-06-30",
      "plan": "Albania-10GB-15 Days-Total",
      "status": 2
    }
  ]
}
API 接口

转换为二维码

（注：转换完成后，二维码将发送到指定邮箱。批量越大，处理时间可能越长。）

请求 URL：https://api.iroamly.shop/openapi/redeemQRcode
请求方法：POST

请求参数：

参数说明类型
email邮箱String
codeList兑换码集合Object[]

productList 字段：

字段说明类型
redeemCode兑换码String
示例参数
{
  "email": "2m827n32d@gmail.com",
  "codeList": [
    {
      "redeemCode": "m8hed7h2fed",
    },
    {
      "redeemCode": "cn88beg9edj",
    }
  ]
}
返回示例
{
  "code": 1,
  "msg": "success",
}
API 接口

查询二维码

请求 URL：https://api.iroamly.shop/openapi/qrcodeQuery
请求方法：POST

请求参数：

参数说明类型
redeemCode兑换码String

响应字段说明：

字段说明类型
redeemCode兑换码String
qrcode二维码图片 URLString
status兑换码状态（见“兑换码状态定义”）Int
qrcode_content二维码内容（LPA 激活字符串，例如 LPA:1$…）String
iscouldrenewaleSIM 是否可续费： 1 - 可续费 0 - 不可续费Int
示例参数
{
  "redeemCode": "m8hed7h2fed",
}
返回示例
{
  "code": 1,
  "msg": "success",
  "redeemCode": "m8hed7h2fed",
  "qrcode": "https://dsfjigewafe/qrcode.jpg"
}
API 接口

获取续费套餐状态

请求 URL：https://api.iroamly.shop/openapi/getRenewPlanStatus
请求方法：POST

请求参数：

参数说明类型
redeemCode兑换码String

响应字段说明：

响应顶层的 code 表示该兑换码能否续费：0 - 可以续费，-1 - 无法续费。续费选项列在 data.renewList 中：

字段说明类型
renewtype续费类型： 0 - 当前套餐到期时激活 1 - 立即激活（清除剩余流量） 2 - 在指定时间激活Int
starttime可选激活时间段的开始：可选择的最早激活时间（续费类型 2）。String
endtime可选激活时间段的结束：可选择的最晚激活时间（续费类型 2）。String
示例参数
{
  "redeemCode": "3cd2m3f23f3f3",
}
返回示例
{
  "code": 0,
  "data": {
    "renewList": [
      {
        "renewtype": 1,
        "starttime": "0001-01-01T00:00:00Z",
        "endtime": "0001-01-01T00:00:00Z"
      },
      {
        "renewtype": 2,
        "starttime": "2025-08-04 06:13:08",
        "endtime": "2025-09-20 14:23:51"
      }
    ],
    "lasttime": "0001-01-01T00:00:00Z"
  },
  "msg": "Success"
}
API 接口

续费兑换码

（注：续费时，所选套餐的续费组必须与原套餐的续费组一致。）

请求 URL：https://api.iroamly.shop/openapi/renewcode
请求方法：POST

请求参数：

参数说明类型
redeemCode需要续费的兑换码String
plan续费套餐String
renewtype续费类型： 0 - 当前套餐到期时激活 1 - 立即激活（清除剩余流量） 2 - 在指定时间激活Int
renewtime生效日期和时间（必填）。格式：YYYY-MM-DDTHH:mm:ssZString
示例参数
{
  redeemCode: "DEF456UVW",
  plan: "basic_yearly",
  renewtype: 0,
  renewtime: "2024-12-31T23:59:59Z"
}
返回示例
{
  code: 1,
  data: {
    orderId: "Open-Global-DXDWFBKG578913",
    plan: "United States-eSIM-10GB-10 Days-Total",
    redeemCode: "tjMxpYfvk5dFMQg",
    status: 0,
    expire_at: "2026-03-01"
  },
  msg: "success"
}
API 接口

获取套餐统计

请求 URL：https://api.iroamly.shop/openapi/getnetworkflow
请求方法：GET

请求参数：

参数说明类型
redeemCode要查询的兑换码。String

响应字段说明：

参数说明类型
status0 - 未激活 1 - 已激活 2 - 已过期 9 - 无效Int
flow_use计费周期内已用流量（单位 MB）String
flow_total计费周期内总流量（单位 MB，或 unlimited）String
start_data套餐开始时间String
end_data套餐结束时间String
installDevice安装设备String
installCount安装次数String
installTime安装时间String
有效示例
{
  code: 1,
  status: 0,
  flow_use: "300",
  flow_total: "1024",
  start_data: "2025-10-25T15:04:05Z07:00",
  end_data: "2025-11-25T15:04:05Z07:00",
  installDevice: "iPhone 15",
  installCount: "1",
  installTime: "2025-10-25T15:04:05Z06:00"
}
无效示例
{
  code: -1,
  msg: "error message"
}
定义

响应状态码定义

代码说明
1成功
2请求参数身份验证失败
3未按要求提供参数
4产品代码不存在
5点数不足
6兑换码不存在
7兑换码已兑换或不存在
-1请求失败

成功时 code 为 1，但 /common/getPlanItem 和 /openapi/getRenewPlanStatus 除外，二者成功时返回的 code 为 0。

定义

兑换码状态定义

状态说明
0未兑换
1兑换中
2已兑换
3兑换失败
代码参考

购买兑换码（Python）

python
import requests
import json
import hashlib

# URL for the request
url = "https://api.iroamly.shop/openapi/purchaseCode"

# Provided AuthKey and AuthSecret, remember to replace them with real values
auth_key = "YOUR_AUTH_KEY_HERE"
auth_secret = "YOUR_AUTH_SECRET_HERE" 


# Calculating Certification
combined = auth_key + auth_secret
certification = hashlib.sha256(combined.encode()).hexdigest()

# Header parameters for the request
headers = {
    "Content-Type": "application/json",
    "AuthKey": auth_key,
    "Certification": certification
}

# Example data for the request body
data = {
    "email": "2m827n32d@gmail.com",
    "productList": [
        {
            "productCode": "m8hed7h2fed2398dsnh",
            "quantity": 2
        },
        {
            "productCode": "cn88beg9edjdfj2sj0a",
            "quantity": 1
        }
    ]
}

# Sending POST request
response = requests.post(url, headers=headers, data=json.dumps(data))

# Printing the response content
print(response.text)

# Example of response
{
    "code":1,
    "msg":"success",
    "orderId":"xxx-xxxx-sd9hn8df333"
}
代码参考

查询兑换码（Python）

python
import requests
import json
import hashlib

# URL for the request
url = "https://api.iroamly.shop/openapi/codeQuery"

# Provided AuthKey and AuthSecret, remember to replace them with real values
auth_key = "YOUR_AUTH_KEY_HERE"
auth_secret = "YOUR_AUTH_SECRET_HERE" 


# Calculating Certification
combined = auth_key + auth_secret
certification = hashlib.sha256(combined.encode()).hexdigest()

# Header parameters for the request
headers = {
    "Content-Type": "application/json",
    "AuthKey": auth_key,
    "Certification": certification
}

# Example data for the request body
data = {
    "orderId":"xxx-xxx-dh239jdu28"
}

# Sending POST request
response = requests.post(url, headers=headers, data=json.dumps(data))

# Printing the response content
print(response.text)

# Example of response
{
 "code":1,
 "data":
    [
     {"productCode":"m8hed7h2fed2398dsnh","redeemCode":"nDb4TDCn6vMhbQv","status":0,"expire_at":"2024-07-04"},
     {"productCode":"m8hed7h2fed2398dsnh","redeemCode":"oA7AWAmo76BwoGj","status":0,"expire_at":"2024-07-04"},
     {"productCode":"cn88beg9edjdfj2sj0a","redeemCode":"XRdDeSxBVNbvCpU","status":0,"expire_at":"2024-07-04"}
    ],
 "msg":"success"
}
代码参考

转换为二维码（Python）

python
import requests
import json
import hashlib

# URL for the request
url = "https://api.iroamly.shop/openapi/redeemQRcode"

# Provided AuthKey and AuthSecret, remember to replace them with real values
auth_key = "YOUR_AUTH_KEY_HERE"
auth_secret = "YOUR_AUTH_SECRET_HERE" 


# Calculating Certification
combined = auth_key + auth_secret
certification = hashlib.sha256(combined.encode()).hexdigest()

# Header parameters for the request
headers = {
    "Content-Type": "application/json",
    "AuthKey": auth_key,
    "Certification": certification
}

# Example data for the request body
data = {
    "email": "2m827n32d@gmail.com",
    "codeList": [
        {
            "redeemCode": "nDb4TDCn6vMhbQv",
        },
        {
            "redeemCode": "XRdDeSxBVNbvCpU",
        }
    ]
}

# Sending POST request
response = requests.post(url, headers=headers, data=json.dumps(data))

# Printing the response content
print(response.text)

# Example of response
{"code":1,"msg":"success"}
代码参考

查询二维码（Python）

python
import requests
import json
import hashlib

# URL for the request
url = "https://api.iroamly.shop/openapi/qrcodeQuery"

# Provided AuthKey and AuthSecret, remember to replace them with real values
auth_key = "YOUR_AUTH_KEY_HERE"
auth_secret = "YOUR_AUTH_SECRET_HERE" 


# Calculating Certification
combined = auth_key + auth_secret
certification = hashlib.sha256(combined.encode()).hexdigest()

# Header parameters for the request
headers = {
    "Content-Type": "application/json",
    "AuthKey": auth_key,
    "Certification": certification
}

# Example data for the request body
data = {
    "redeemCode":"XRdDeSxBVNbvCpU"
}

# Sending POST request
response = requests.post(url, headers=headers, data=json.dumps(data))

# Printing the response content
print(response.text)

# Example of response
{
 "code":1,
 "qrcode":"https:/code.tokyoesim.com/20231220/1703048857317.65625d0a779f4598d55d77bda43ecd80.png",
 "msg":"success",
 "redeemCode":"XRdDeSxBVNbvCpU"
}