API 文件

iRoamly Shop API 參考文件：驗證、方案、購買與交付、續約及用量。

概覽

基本說明

為確保伺服器傳輸資訊的安全，採用以下安全機制：

1.所有介面皆透過 HTTPS secure 安全連線傳輸。
2.核發給您的 AuthKey，用於 API 身分驗證（最長 32 個字元）。
3.核發給您的 AuthSecret，用於產生請求雜湊值（最長 50 個字元）。
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 端點

直接購買 QR Code

請求 URL：https://api.iroamly.shop/openapi/purchaseqrcode

請求方法：POST

請求參數：

參數說明類型

email接收 QR Code 的電子郵件信箱。若留空，則不會寄送郵件。String

productList產品集合Object[]

productList 欄位：

欄位說明類型

plan方案名稱。請提供 plan 或 productCode 其中之一。String

productCode方案 ID（取自「取得區域方案清單」的 productCode）。請提供 productCode 或 plan 其中之一。String

quantity數量Int

測試方案：iRoamly-Test-10GB

下一步：使用「查詢 QR Code」（https://api.iroamly.shop/openapi/qrcodeQuery）取得 QR Code

參數範例

{
  "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 端點

轉換為 QR Code

（注意：轉換完成後，QR Code 會寄送至指定的電子郵件。批次越大，處理時間可能越長。）

請求 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 端點

查詢 QR Code

請求 URL：https://api.iroamly.shop/openapi/qrcodeQuery

請求方法：POST

請求參數：

參數說明類型

redeemCode兌換碼String

回應欄位說明：

欄位說明類型

redeemCode兌換碼String

qrcodeQR Code 圖片 URLString

status兌換碼狀態（請參閱「兌換碼狀態定義」）Int

qrcode_contentQR Code 內容（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，或無限量）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）

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"
}

程式碼參考

轉換為 QR Code（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"}

程式碼參考

查詢 QR Code（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"
}