Documentazione API

Riferimento per l’API di iRoamly Shop: autenticazione, piani, acquisto e consegna, rinnovo e consumi.

Panoramica

Spiegazione di base

Per garantire la sicurezza delle informazioni trasmesse dal server, vengono adottati i seguenti meccanismi di sicurezza:

1.Tutte le interfacce comunicano tramite connessioni sicure HTTPS secure.
2.AuthKey assegnata, usata per l’autenticazione API (lunghezza massima: 32 caratteri).
3.AuthSecret assegnato, usato per generare l’hash della richiesta (lunghezza massima: 50 caratteri).
4.Le richieste usano hash SHA-256 per l’autenticazione.

Panoramica

Standard dell’interfaccia

Percorso base:https://api.iroamly.shop/

Protocollo della richiesta:HTTPS

Metodo della richiesta:GET / POST

Formato di trasferimento dei dati:application/json

Parametri dell’header della richiesta:

AuthKey: chiave di autenticazione del cliente, di tipo stringa (String)

Certification: stringa (String) contenente l’hash SHA-256 di AuthKey+AuthSecret concatenati in quest’ordine.

/common/getPlanItem non richiede l’header AuthKey né Certification.

Endpoint API

Get Regional Plan List

URL della richiesta:https://api.iroamly.shop/common/getPlanItem

Metodo della richiesta:GET

Non è richiesto alcun header AuthKey o Certification.

Parametri della richiesta:

ParametroDescrizioneTipo

regionAccetta codici ISO2, nomi di paesi (senza distinzione tra maiuscole e minuscole) o formati standardizzati (ad es. united-states).String

Formato della risposta:

Successo: HTTP 200. I piani vengono restituiti in data.list.

Restituisce sempre HTTP 200. Quando non ci sono dati, data.list è un array vuoto e msg è Success.

Descrizione dei campi della risposta:

CampoDescrizioneTipo

planNome del piano (include regione, tipo, volume di dati e durata).String

productCodeID univoco del piano per acquisti o interrogazioni.String

dataVolume di dati (ad es. 10GB, Unlimited, 500MB).String

typeTipo di piano (ad es. Total, Daily, Unlimited).String

plan_typeCategoria del piano (ad es. default).String

package_typeTipo di pacchetto (ad es. Data Only).String

durationPeriodo di validità in giorni (ad es. 10).String

speedVelocità di rete (ad es. 4G / 5G).String

operatorOperatori supportati (ad es. T-Mobile/AT&T).String

regionNome ufficiale della regione (ad es. United States).String

region_indexIdentificativo standardizzato della regione (minuscolo con trattini, ad es. united-states).String

creditPrezzo del piano in crediti (non in dollari USA).Float

remarkNote aggiuntive (ad es. regole di limitazione della velocità).String

created_atData e ora di creazione del piano (formato ISO 8601).String

Esempio di richiesta

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

Risposta di esempio

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

Endpoint API

Acquisto diretto del codice QR

URL della richiesta:https://api.iroamly.shop/openapi/purchaseqrcode

Metodo della richiesta:POST

Parametri della richiesta:

ParametroDescrizioneTipo

emailCasella di posta che riceve i codici QR. Se è vuota, non viene inviata alcuna e-mail.String

productListInsieme di prodottiObject[]

Campi di productList:

CampoDescrizioneTipo

planNome del piano. Indica plan oppure productCode.String

productCodeID del piano (productCode da Get Regional Plan List). Indica productCode oppure plan.String

quantityQuantitàInt

Piano di test:iRoamly-Test-10GB

Passaggio successivo: usa Query QR Code (https://api.iroamly.shop/openapi/qrcodeQuery) per ottenere il codice QR

Parametri di esempio

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

Risposta di esempio

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

Endpoint API

Acquisto del codice di riscatto

URL della richiesta:https://api.iroamly.shop/openapi/purchaseCode

Metodo della richiesta:POST

Parametri della richiesta:

ParametroDescrizioneTipo

emailE-mailString

productListInsieme di prodottiObject[]

Campi di productList:

CampoDescrizioneTipo

planNome del piano. Indica plan oppure productCode.String

productCodeID del piano (productCode da Get Regional Plan List). Indica productCode oppure plan.String

quantityQuantitàInt

Piano di test:iRoamly-Test-10GB

Parametri di esempio

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

Risposta di esempio

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

Endpoint API

Interrogazione del codice di riscatto

URL della richiesta:https://api.iroamly.shop/openapi/codeQuery

Metodo della richiesta:POST

Parametri della richiesta:

ParametroDescrizioneTipo

orderIdNumero d’ordineString

Parametri di esempio

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

Risposta di esempio

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

Endpoint API

Converti in codice QR

(Nota: i codici QR vengono inviati all’indirizzo e-mail indicato dopo la conversione. L’elaborazione di lotti più grandi può richiedere più tempo.)

URL della richiesta:https://api.iroamly.shop/openapi/redeemQRcode

Metodo della richiesta:POST

Parametri della richiesta:

ParametroDescrizioneTipo

emailE-mailString

codeListInsieme di codici di riscattoObject[]

Campi di productList:

CampoDescrizioneTipo

redeemCodeCodice di riscattoString

Parametri di esempio

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

Risposta di esempio

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

Endpoint API

Interrogazione del codice QR

URL della richiesta:https://api.iroamly.shop/openapi/qrcodeQuery

Metodo della richiesta:POST

Parametri della richiesta:

ParametroDescrizioneTipo

redeemCodeCodice di riscattoString

Descrizione dei campi della risposta:

CampoDescrizioneTipo

redeemCodeCodice di riscattoString

qrcodeURL dell’immagine del codice QRString

statusStato del codice di riscatto (vedi Definizioni degli stati del codice di riscatto)Int

qrcode_contentContenuto del codice QR (stringa di attivazione LPA, ad es. LPA:1$…)String

iscouldrenewalIndica se l’eSIM può essere rinnovata: 1 - può essere rinnovata 0 - non può essere rinnovataInt

Parametri di esempio

{
  "redeemCode": "m8hed7h2fed",
}

Risposta di esempio

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

Endpoint API

Stato del piano di rinnovo

URL della richiesta:https://api.iroamly.shop/openapi/getRenewPlanStatus

Metodo della richiesta:POST

Parametri della richiesta:

ParametroDescrizioneTipo

redeemCodeCodice di riscattoString

Descrizione dei campi della risposta:

Il code di primo livello della risposta indica se il codice di riscatto può essere rinnovato: 0 - rinnovo possibile, -1 - rinnovo non possibile. Le opzioni di rinnovo sono elencate in data.renewList:

CampoDescrizioneTipo

renewtypeTipo di rinnovo: 0 - Attivazione alla scadenza del piano attuale 1 - Attivazione immediata (azzera i dati residui) 2 - Attivazione a un orario specificatoInt

starttimeInizio della finestra di attivazione facoltativa: il primo orario di attivazione che puoi scegliere (tipo di rinnovo 2).String

endtimeFine della finestra di attivazione facoltativa: l’ultimo orario di attivazione che puoi scegliere (tipo di rinnovo 2).String

Parametri di esempio

{
  "redeemCode": "3cd2m3f23f3f3",
}

Risposta di esempio

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

Endpoint API

Codice di rinnovo

(Nota: durante il rinnovo, il gruppo di rinnovo del piano selezionato deve corrispondere a quello del piano originale.)

URL della richiesta:https://api.iroamly.shop/openapi/renewcode

Metodo della richiesta:POST

Parametri della richiesta:

ParametroDescrizioneTipo

redeemCodeCodice da rinnovareString

planPiano di rinnovoString

renewtypeTipo di rinnovo: 0 - Attivazione alla scadenza del piano attuale 1 - Attivazione immediata (azzera i dati residui) 2 - Attivazione a un orario specificatoInt

renewtimeData e ora di decorrenza (obbligatorio). Formato: YYYY-MM-DDTHH:mm:ssZString

Parametri di esempio

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

Risposta di esempio

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

Endpoint API

Statistiche del piano

URL della richiesta:https://api.iroamly.shop/openapi/getnetworkflow

Metodo della richiesta:GET

Parametri della richiesta:

ParametroDescrizioneTipo

redeemCodeCodice di riscatto da interrogare.String

Descrizione dei campi della risposta:

ParametroDescrizioneTipo

status0 - Inattivo 1 - Attivo 2 - Scaduto 9 - Non validoInt

flow_useDati utilizzati nel ciclo di fatturazione (in MB)String

flow_totalDati totali nel ciclo di fatturazione (in MB, o unlimited)String

start_dataOra di inizio del pianoString

end_dataOra di fine del pianoString

installDeviceDispositivo di installazioneString

installCountNumero di installazioniString

installTimeOra di installazioneString

Esempio valido

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

Esempio non valido

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

Definizioni

Definizioni dei codici di stato della risposta

CodiceDescrizione

1Successo

2Autenticazione dei parametri della richiesta non riuscita

3Parametri non forniti come richiesto

4Il codice prodotto non esiste

5Crediti insufficienti

6Il codice di riscatto non esiste

7Il codice di riscatto è già stato riscattato o non esiste

-1Richiesta non riuscita

Il successo è code 1, tranne per /common/getPlanItem e /openapi/getRenewPlanStatus, che restituiscono code 0 in caso di successo.

Definizioni

Definizioni degli stati del codice di riscatto

StatoDescrizione

0Non riscattato

1Riscatto in corso

2Riscattato

3Riscatto non riuscito

Riferimento del codice

Riferimento del codice (Python)

Riferimento del codice

Acquisto del codice di riscatto (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"
}

Riferimento del codice

Interrogazione del codice di riscatto (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"
}

Riferimento del codice

Converti in codice 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"}

Riferimento del codice

Interrogazione del codice 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"
}