API-Dokumentation

Referenz der iRoamly Shop API: Authentifizierung, Tarife, Kauf und Zustellung, Verlängerung und Nutzung.

Überblick

Grundlagen

Um die Sicherheit der übertragenen Serverdaten zu gewährleisten, werden folgende Sicherheitsmechanismen eingesetzt:

1.Alle Schnittstellen nutzen verschlüsselte HTTPS secure-Verbindungen.
2.Zugewiesener AuthKey für die API-Authentifizierung (maximale Länge: 32 Zeichen).
3.Zugewiesenes AuthSecret zur Erzeugung des Anfrage-Hashs (maximale Länge: 50 Zeichen).
4.Anfragen werden über SHA-256-Hashes authentifiziert.

Überblick

Schnittstellenstandards

Basispfad:https://api.iroamly.shop/

Anfrageprotokoll:HTTPS

Anfragemethode:GET / POST

Datenübertragungsformat:application/json

Header-Parameter der Anfrage:

AuthKey: Authentifizierungsschlüssel des Kunden, Typ Zeichenkette (String)

Certification: String mit dem SHA-256-Hash von AuthKey+AuthSecret, in dieser Reihenfolge verkettet.

/common/getPlanItem benötigt weder den Header AuthKey noch Certification.

API-Endpunkte

Regionale Tarifliste abrufen

Anfrage-URL:https://api.iroamly.shop/common/getPlanItem

Anfragemethode:GET

Es ist weder der Header AuthKey noch Certification erforderlich.

Anfrageparameter:

ParameterBeschreibungTyp

regionAkzeptiert ISO2-Codes, Ländernamen (ohne Beachtung der Groß-/Kleinschreibung) oder standardisierte Formate (z. B. united-states).String

Antwortformat:

Erfolg: HTTP 200. Die Tarife werden in data.list zurückgegeben.

Gibt immer HTTP 200 zurück. Wenn keine Daten vorhanden sind, ist data.list ein leeres Array und msg ist Success.

Beschreibung der Antwortfelder:

FeldBeschreibungTyp

planTarifname (enthält Region, Typ, Datenvolumen und Laufzeit).String

productCodeEindeutige Tarif-ID für Käufe oder Abfragen.String

dataDatenvolumen (z. B. 10GB, Unlimited, 500MB).String

typeTariftyp (z. B. Total, Daily, Unlimited).String

plan_typeTarifkategorie (z. B. default).String

package_typePakettyp (z. B. Data Only).String

durationGültigkeitsdauer in Tagen (z. B. 10).String

speedNetzgeschwindigkeit (z. B. 4G / 5G).String

operatorUnterstützte Netzbetreiber (z. B. T-Mobile/AT&T).String

regionOffizieller Name der Region (z. B. United States).String

region_indexStandardisierte Regionskennung (Kleinbuchstaben mit Bindestrichen, z. B. united-states).String

creditTarifpreis in Credits (nicht in USD).Float

remarkZusätzliche Hinweise (z. B. Regeln zur Drosselung).String

created_atErstellungszeitpunkt des Tarifs (Format ISO 8601).String

Anfragebeispiel

"https://api.iroamly.shop/common/getPlanItem?region=US"

Beispielantwort

{
  "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-Endpunkte

QR-Code direkt kaufen

Anfrage-URL:https://api.iroamly.shop/openapi/purchaseqrcode

Anfragemethode:POST

Anfrageparameter:

ParameterBeschreibungTyp

emailDas Postfach, an das die QR-Codes gesendet werden. Ist es leer, wird keine E-Mail gesendet.String

productListProduktsammlungObject[]

Felder von productList:

FeldBeschreibungTyp

planTarifname. Geben Sie entweder plan oder productCode an.String

productCodeTarif-ID (productCode aus „Regionale Tarifliste abrufen“). Geben Sie entweder productCode oder plan an.String

quantityMengeInt

Testtarif:iRoamly-Test-10GB

Nächster Schritt: Verwenden Sie „QR-Code abfragen“ (https://api.iroamly.shop/openapi/qrcodeQuery), um den QR-Code abzurufen

Beispielparameter

{
  "email": "2m827n32d@gmail.com",
  "productList": [
    {
      "plan": "United States-eSIM-10GB-10 Days-Total",
      "quantity": 2
    },
    {
      "plan": "Albania-10GB-15 Days-Total",
      "quantity": 1
    }
  ]
}

Beispielantwort

{
  "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-Endpunkte

Einlösecode kaufen

Anfrage-URL:https://api.iroamly.shop/openapi/purchaseCode

Anfragemethode:POST

Anfrageparameter:

ParameterBeschreibungTyp

emailE-MailString

productListProduktsammlungObject[]

Felder von productList:

FeldBeschreibungTyp

planTarifname. Geben Sie entweder plan oder productCode an.String

productCodeTarif-ID (productCode aus „Regionale Tarifliste abrufen“). Geben Sie entweder productCode oder plan an.String

quantityMengeInt

Testtarif:iRoamly-Test-10GB

Beispielparameter

{
  "email": "2m827n32d@gmail.com",
  "productList": [
    {
      "plan": "United States-eSIM-10GB-10 Days-Total",
      "quantity": 2
    },
    {
      "plan": "Albania-10GB-15 Days-Total",
      "quantity": 1
    }
  ]
}

Beispielantwort

{
  "code": 1,
  "msg": "success",
  "orderId": "xxx-xxxx-sd9hn8df333" // Order number, can be used to query redeem code
}

API-Endpunkte

Einlösecode abfragen

Anfrage-URL:https://api.iroamly.shop/openapi/codeQuery

Anfragemethode:POST

Anfrageparameter:

ParameterBeschreibungTyp

orderIdBestellnummerString

Beispielparameter

{
  "orderId": "xxx-xxx-dh239jdu28",
}

Beispielantwort

{
  "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-Endpunkte

In QR-Code umwandeln

(Hinweis: Die QR-Codes werden nach der Umwandlung an die angegebene E-Mail-Adresse gesendet. Größere Mengen können länger dauern.)

Anfrage-URL:https://api.iroamly.shop/openapi/redeemQRcode

Anfragemethode:POST

Anfrageparameter:

ParameterBeschreibungTyp

emailE-MailString

codeListSammlung von EinlösecodesObject[]

Felder von productList:

FeldBeschreibungTyp

redeemCodeEinlösecodeString

Beispielparameter

{
  "email": "2m827n32d@gmail.com",
  "codeList": [
    {
      "redeemCode": "m8hed7h2fed",
    },
    {
      "redeemCode": "cn88beg9edj",
    }
  ]
}

Beispielantwort

{
  "code": 1,
  "msg": "success",
}

API-Endpunkte

QR-Code abfragen

Anfrage-URL:https://api.iroamly.shop/openapi/qrcodeQuery

Anfragemethode:POST

Anfrageparameter:

ParameterBeschreibungTyp

redeemCodeEinlösecodeString

Beschreibung der Antwortfelder:

FeldBeschreibungTyp

redeemCodeEinlösecodeString

qrcodeURL des QR-Code-BildsString

statusStatus des Einlösecodes (siehe Definitionen der Einlösecode-Status)Int

qrcode_contentInhalt des QR-Codes (LPA-Aktivierungsstring, z. B. LPA:1$…)String

iscouldrenewalOb die eSIM verlängert werden kann: 1 - kann verlängert werden 0 - kann nicht verlängert werdenInt

Beispielparameter

{
  "redeemCode": "m8hed7h2fed",
}

Beispielantwort

{
  "code": 1,
  "msg": "success",
  "redeemCode": "m8hed7h2fed",
  "qrcode": "https://dsfjigewafe/qrcode.jpg"
}

API-Endpunkte

Verlängerungsstatus des Tarifs abrufen

Anfrage-URL:https://api.iroamly.shop/openapi/getRenewPlanStatus

Anfragemethode:POST

Anfrageparameter:

ParameterBeschreibungTyp

redeemCodeEinlösecodeString

Beschreibung der Antwortfelder:

Der code auf oberster Ebene der Antwort gibt an, ob der Einlösecode verlängert werden kann: 0 - Verlängerung möglich, -1 - Verlängerung nicht möglich. Die Verlängerungsoptionen sind in data.renewList aufgeführt:

FeldBeschreibungTyp

renewtypeVerlängerungsart: 0 - Aktivierung bei Ablauf des aktuellen Tarifs 1 - Sofortige Aktivierung (verbleibende Daten werden gelöscht) 2 - Aktivierung zu einem festgelegten ZeitpunktInt

starttimeBeginn des wählbaren Aktivierungszeitraums: der früheste wählbare Aktivierungszeitpunkt (Verlängerungsart 2).String

endtimeEnde des wählbaren Aktivierungszeitraums: der späteste wählbare Aktivierungszeitpunkt (Verlängerungsart 2).String

Beispielparameter

{
  "redeemCode": "3cd2m3f23f3f3",
}

Beispielantwort

{
  "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-Endpunkte

Code verlängern

(Hinweis: Bei der Verlängerung muss die Verlängerungsgruppe des gewählten Tarifs mit der des ursprünglichen Tarifs übereinstimmen.)

Anfrage-URL:https://api.iroamly.shop/openapi/renewcode

Anfragemethode:POST

Anfrageparameter:

ParameterBeschreibungTyp

redeemCodeZu verlängernder CodeString

planVerlängerungstarifString

renewtypeVerlängerungsart: 0 - Aktivierung bei Ablauf des aktuellen Tarifs 1 - Sofortige Aktivierung (verbleibende Daten werden gelöscht) 2 - Aktivierung zu einem festgelegten ZeitpunktInt

renewtimeDatum und Uhrzeit des Inkrafttretens (erforderlich). Format: YYYY-MM-DDTHH:mm:ssZString

Beispielparameter

{
  redeemCode: "DEF456UVW",
  plan: "basic_yearly",
  renewtype: 0,
  renewtime: "2024-12-31T23:59:59Z"
}

Beispielantwort

{
  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-Endpunkte

Tarifstatistik abrufen

Anfrage-URL:https://api.iroamly.shop/openapi/getnetworkflow

Anfragemethode:GET

Anfrageparameter:

ParameterBeschreibungTyp

redeemCodeAbzufragender Einlösecode.String

Beschreibung der Antwortfelder:

ParameterBeschreibungTyp

status0 - Inaktiv 1 - Aktiv 2 - Abgelaufen 9 - UngültigInt

flow_useIm Abrechnungszeitraum verbrauchte Daten (in MB)String

flow_totalGesamtdaten im Abrechnungszeitraum (in MB oder unbegrenzt)String

start_dataStartzeit des TarifsString

end_dataEndzeit des TarifsString

installDeviceInstalliertes GerätString

installCountAnzahl der InstallationenString

installTimeInstallationszeitString

Gültiges Beispiel

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

Ungültiges Beispiel

{
  code: -1,
  msg: "error message"
}

Definitionen

Definitionen der Antwort-Statuscodes

CodeBeschreibung

1Erfolg

2Authentifizierung der Anfrageparameter fehlgeschlagen

3Parameter wurden nicht wie erforderlich übergeben

4Produktcode existiert nicht

5Nicht genügend Credits

6Einlösecode existiert nicht

7Einlösecode wurde bereits eingelöst oder existiert nicht

-1Anfrage fehlgeschlagen

Erfolg ist code 1, außer bei /common/getPlanItem und /openapi/getRenewPlanStatus, die bei Erfolg code 0 zurückgeben.

Definitionen

Definitionen der Einlösecode-Status

StatusBeschreibung

0Nicht eingelöst

1Wird eingelöst

2Eingelöst

3Einlösung fehlgeschlagen

Code-Referenz

Code-Referenz (Python)

Code-Referenz

Einlösecode kaufen (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"
}

Code-Referenz

Einlösecode abfragen (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"
}

Code-Referenz

In QR-Code umwandeln (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"}

Code-Referenz

QR-Code abfragen (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"
}