Przejdź do treści
iRoamly Shop

Dokumentacja API

Dokumentacja API iRoamly Shop: uwierzytelnianie, pakiety, zakup i dostawa, odnowienie i zużycie.

Przegląd

Podstawowe informacje

Aby zapewnić bezpieczeństwo danych przesyłanych do serwera, stosowane są następujące mechanizmy:

  1. 1.Wszystkie interfejsy przesyłają dane przez bezpieczne połączenie HTTPS secure.
  2. 2.Przydzielony AuthKey używany do uwierzytelniania w API (maksymalna długość: 32 znaki).
  3. 3.Przydzielony AuthSecret używany do generowania skrótu (hash) żądania (maksymalna długość: 50 znaków).
  4. 4.Żądania są uwierzytelniane za pomocą skrótów SHA-256.
Przegląd

Standardy interfejsu

Ścieżka bazowa:https://api.iroamly.shop/
Protokół żądania:HTTPS
Metoda żądania:GET / POST
Format przesyłania danych:application/json

Parametry nagłówka żądania:

AuthKey: klucz uwierzytelniania klienta, typ: ciąg znaków (String)

Certification: ciąg typu String zawierający skrót SHA-256 połączonych w tej kolejności AuthKey+AuthSecret.

/common/getPlanItem nie wymaga nagłówka AuthKey ani Certification.

Endpointy API

Pobierz listę pakietów regionu

URL żądania:https://api.iroamly.shop/common/getPlanItem
Metoda żądania:GET

Nagłówek AuthKey ani Certification nie jest wymagany.

Parametry żądania:

ParametrOpisTyp
regionAkceptuje kody ISO2, nazwy krajów (bez rozróżniania wielkości liter) lub formaty standardowe (np. united-states).String

Format odpowiedzi:

Sukces: HTTP 200. Pakiety są zwracane w data.list.

Zawsze zwraca HTTP 200. Gdy brak danych, data.list jest pustą tablicą, a msg ma wartość Success.

Opis pól odpowiedzi:

PoleOpisTyp
planNazwa pakietu (zawiera region, typ, limit danych i okres).String
productCodeUnikalny ID pakietu do zakupu lub zapytań.String
dataLimit danych (np. 10GB, Unlimited, 500MB).String
typeTyp pakietu (np. Total, Daily, Unlimited).String
plan_typeKategoria pakietu (np. default).String
package_typeTyp pakietu (np. Data Only).String
durationOkres ważności w dniach (np. 10).String
speedPrędkość sieci (np. 4G / 5G).String
operatorObsługiwani operatorzy (np. T-Mobile/AT&T).String
regionOficjalna nazwa regionu (np. United States).String
region_indexStandardowy identyfikator regionu (małe litery z łącznikami, np. united-states).String
creditCena pakietu w kredytach (nie w USD).Float
remarkDodatkowe uwagi (np. zasady ograniczania prędkości).String
created_atZnacznik czasu utworzenia pakietu (format ISO 8601).String
Przykład żądania
"https://api.iroamly.shop/common/getPlanItem?region=US"
Przykładowa odpowiedź
{
  "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"
     }
    ]
  }
}
Endpointy API

Bezpośredni zakup kodu QR

URL żądania:https://api.iroamly.shop/openapi/purchaseqrcode
Metoda żądania:POST

Parametry żądania:

ParametrOpisTyp
emailSkrzynka, na którą wysyłane są kody QR. Jeśli pole jest puste, e-mail nie zostanie wysłany.String
productListKolekcja produktówObject[]

Pola productList:

PoleOpisTyp
planNazwa pakietu. Podaj plan albo productCode.String
productCodeID pakietu (productCode z Get Regional Plan List). Podaj productCode albo plan.String
quantityIlośćInt
Pakiet testowy:iRoamly-Test-10GB

Następny krok: użyj Query QR Code (https://api.iroamly.shop/openapi/qrcodeQuery), aby pobrać kod QR

Przykładowe parametry
{
  "email": "2m827n32d@gmail.com",
  "productList": [
    {
      "plan": "United States-eSIM-10GB-10 Days-Total",
      "quantity": 2
    },
    {
      "plan": "Albania-10GB-15 Days-Total",
      "quantity": 1
    }
  ]
}
Przykładowa odpowiedź
{
  "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"
}
Endpointy API

Zakup kodu wymiany

URL żądania:https://api.iroamly.shop/openapi/purchaseCode
Metoda żądania:POST

Parametry żądania:

ParametrOpisTyp
emailE-mailString
productListKolekcja produktówObject[]

Pola productList:

PoleOpisTyp
planNazwa pakietu. Podaj plan albo productCode.String
productCodeID pakietu (productCode z Get Regional Plan List). Podaj productCode albo plan.String
quantityIlośćInt
Pakiet testowy:iRoamly-Test-10GB
Przykładowe parametry
{
  "email": "2m827n32d@gmail.com",
  "productList": [
    {
      "plan": "United States-eSIM-10GB-10 Days-Total",
      "quantity": 2
    },
    {
      "plan": "Albania-10GB-15 Days-Total",
      "quantity": 1
    }
  ]
}
Przykładowa odpowiedź
{
  "code": 1,
  "msg": "success",
  "orderId": "xxx-xxxx-sd9hn8df333" // Order number, can be used to query redeem code
}
Endpointy API

Zapytanie o kod wymiany

URL żądania:https://api.iroamly.shop/openapi/codeQuery
Metoda żądania:POST

Parametry żądania:

ParametrOpisTyp
orderIdNumer zamówieniaString
Przykładowe parametry
{
  "orderId": "xxx-xxx-dh239jdu28",
}
Przykładowa odpowiedź
{
  "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
    }
  ]
}
Endpointy API

Zamień na kod QR

(Uwaga: po zamianie kody QR są wysyłane na wskazany adres e-mail. Przetwarzanie większych partii może potrwać dłużej.)

URL żądania:https://api.iroamly.shop/openapi/redeemQRcode
Metoda żądania:POST

Parametry żądania:

ParametrOpisTyp
emailE-mailString
codeListKolekcja kodów wymianyObject[]

Pola productList:

PoleOpisTyp
redeemCodeKod wymianyString
Przykładowe parametry
{
  "email": "2m827n32d@gmail.com",
  "codeList": [
    {
      "redeemCode": "m8hed7h2fed",
    },
    {
      "redeemCode": "cn88beg9edj",
    }
  ]
}
Przykładowa odpowiedź
{
  "code": 1,
  "msg": "success",
}
Endpointy API

Zapytanie o kod QR

URL żądania:https://api.iroamly.shop/openapi/qrcodeQuery
Metoda żądania:POST

Parametry żądania:

ParametrOpisTyp
redeemCodeKod wymianyString

Opis pól odpowiedzi:

PoleOpisTyp
redeemCodeKod wymianyString
qrcodeURL obrazu kodu QRString
statusStatus kodu wymiany (zob. Definicje statusów kodów wymiany)Int
qrcode_contentZawartość kodu QR (ciąg aktywacyjny LPA, np. LPA:1$…)String
iscouldrenewalCzy eSIM można odnowić: 1 - można odnowić 0 - nie można odnowićInt
Przykładowe parametry
{
  "redeemCode": "m8hed7h2fed",
}
Przykładowa odpowiedź
{
  "code": 1,
  "msg": "success",
  "redeemCode": "m8hed7h2fed",
  "qrcode": "https://dsfjigewafe/qrcode.jpg"
}
Endpointy API

Pobierz status pakietu odnowienia

URL żądania:https://api.iroamly.shop/openapi/getRenewPlanStatus
Metoda żądania:POST

Parametry żądania:

ParametrOpisTyp
redeemCodeKod wymianyString

Opis pól odpowiedzi:

Pole code najwyższego poziomu w odpowiedzi określa, czy kod wymiany można odnowić: 0 - odnowienie możliwe, -1 - odnowienie niemożliwe. Opcje odnowienia są wymienione w data.renewList:

PoleOpisTyp
renewtypeTyp odnowienia: 0 - aktywacja po wygaśnięciu bieżącego pakietu 1 - aktywacja natychmiastowa (pozostałe dane są usuwane) 2 - aktywacja w określonym czasieInt
starttimePoczątek opcjonalnego okna aktywacji: najwcześniejszy czas aktywacji, jaki możesz wybrać (typ odnowienia 2).String
endtimeKoniec opcjonalnego okna aktywacji: najpóźniejszy czas aktywacji, jaki możesz wybrać (typ odnowienia 2).String
Przykładowe parametry
{
  "redeemCode": "3cd2m3f23f3f3",
}
Przykładowa odpowiedź
{
  "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"
}
Endpointy API

Kod odnowienia

(Uwaga: przy odnawianiu grupa odnowień wybranego pakietu musi być zgodna z grupą odnowień pierwotnego pakietu.)

URL żądania:https://api.iroamly.shop/openapi/renewcode
Metoda żądania:POST

Parametry żądania:

ParametrOpisTyp
redeemCodeKod wymagający odnowieniaString
planPakiet odnowieniaString
renewtypeTyp odnowienia: 0 - aktywacja po wygaśnięciu bieżącego pakietu 1 - aktywacja natychmiastowa (pozostałe dane są usuwane) 2 - aktywacja w określonym czasieInt
renewtimeData i godzina rozpoczęcia (wymagane). Format: YYYY-MM-DDTHH:mm:ssZString
Przykładowe parametry
{
  redeemCode: "DEF456UVW",
  plan: "basic_yearly",
  renewtype: 0,
  renewtime: "2024-12-31T23:59:59Z"
}
Przykładowa odpowiedź
{
  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"
}
Endpointy API

Pobierz statystyki pakietu

URL żądania:https://api.iroamly.shop/openapi/getnetworkflow
Metoda żądania:GET

Parametry żądania:

ParametrOpisTyp
redeemCodeKod wymiany, którego dotyczy zapytanie.String

Opis pól odpowiedzi:

ParametrOpisTyp
status0 - nieaktywny 1 - aktywny 2 - wygasły 9 - nieważnyInt
flow_useDane wykorzystane w okresie rozliczeniowym (w MB)String
flow_totalŁączne dane w okresie rozliczeniowym (w MB lub unlimited)String
start_dataCzas rozpoczęcia pakietuString
end_dataCzas zakończenia pakietuString
installDeviceUrządzenie z instalacjąString
installCountLiczba instalacjiString
installTimeCzas instalacjiString
Poprawny przykład
{
  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"
}
Niepoprawny przykład
{
  code: -1,
  msg: "error message"
}
Definicje

Definicje kodów statusu odpowiedzi

KodOpis
1Sukces
2Uwierzytelnienie parametrów żądania nie powiodło się
3Parametry nie zostały podane zgodnie z wymaganiami
4Kod produktu nie istnieje
5Niewystarczająca liczba kredytów
6Kod wymiany nie istnieje
7Kod wymiany został już wymieniony lub nie istnieje
-1Żądanie nie powiodło się

Sukces to code 1, z wyjątkiem /common/getPlanItem i /openapi/getRenewPlanStatus, które przy powodzeniu zwracają code 0.

Definicje

Definicje statusów kodów wymiany

StatusOpis
0Niewymieniony
1W trakcie wymiany
2Wymieniony
3Wymiana nie powiodła się
Przykłady kodu

Zakup kodu wymiany (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"
}
Przykłady kodu

Zapytanie o kod wymiany (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"
}
Przykłady kodu

Zamień na kod QR (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"}
Przykłady kodu

Zapytanie o kod QR (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"
}