Documentación de la API

Referencia de la API de iRoamly Shop: autenticación, planes, compra y entrega, renovación y consumo.

Descripción general

Explicación básica

Para garantizar la seguridad de la información transmitida por el servidor, se aplican los siguientes mecanismos de seguridad:

1.Todas las interfaces usan conexiones HTTPS secure.
2.AuthKey asignada, usada para la autenticación en la API (longitud máxima: 32 caracteres).
3.AuthSecret asignada, usada para generar el hash de la solicitud (longitud máxima: 50 caracteres).
4.Las solicitudes usan hashes SHA-256 para la autenticación.

Descripción general

Estándares de la interfaz

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

Protocolo de la solicitud:HTTPS

Método de la solicitud:GET / POST

Formato de transferencia de datos:application/json

Parámetros del header de la solicitud:

AuthKey: clave de autenticación del cliente, tipo cadena (String)

Certification: cadena con el hash SHA-256 de AuthKey+AuthSecret concatenados en ese orden.

/common/getPlanItem no requiere el header AuthKey ni Certification.

Endpoints de la API

Obtener la lista de planes regionales

URL de la solicitud:https://api.iroamly.shop/common/getPlanItem

Método de la solicitud:GET

No se requiere el header AuthKey ni Certification.

Parámetros de la solicitud:

ParámetroDescripciónTipo

regionAcepta códigos ISO2, nombres de países (sin distinguir mayúsculas y minúsculas) o formatos normalizados (p. ej., united-states).String

Formato de la respuesta:

Éxito: HTTP 200. Los planes se devuelven en data.list.

Siempre devuelve HTTP 200. Cuando no hay datos, data.list es un array vacío y msg es Success.

Descripción de los campos de la respuesta:

CampoDescripciónTipo

planNombre del plan (incluye región, tipo, volumen de datos y duración).String

productCodeID único del plan para compras o consultas.String

dataVolumen de datos (p. ej., 10GB, Unlimited, 500MB).String

typeTipo de plan (p. ej., Total, Daily, Unlimited).String

plan_typeCategoría del plan (p. ej., default).String

package_typeTipo de paquete (p. ej., Data Only).String

durationPeriodo de validez en días (p. ej., 10).String

speedVelocidad de red (p. ej., 4G / 5G).String

operatorOperadores compatibles (p. ej., T-Mobile/AT&T).String

regionNombre oficial de la región (p. ej., United States).String

region_indexIdentificador normalizado de la región (en minúsculas con guiones, p. ej., united-states).String

creditPrecio del plan en créditos (no en dólares).Float

remarkNotas adicionales (p. ej., reglas de reducción de velocidad).String

created_atMarca de tiempo de creación del plan (formato ISO 8601).String

Ejemplo de solicitud

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

Respuesta de ejemplo

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

Endpoints de la API

Compra directa de código QR

URL de la solicitud:https://api.iroamly.shop/openapi/purchaseqrcode

Método de la solicitud:POST

Parámetros de la solicitud:

ParámetroDescripciónTipo

emailBuzón que recibe los códigos QR. Si está vacío, no se envía ningún correo.String

productListColección de productosObject[]

Campos de productList:

CampoDescripciónTipo

planNombre del plan. Indica plan o productCode.String

productCodeID del plan (productCode de Get Regional Plan List). Indica productCode o plan.String

quantityCantidadInt

Plan de prueba:iRoamly-Test-10GB

Siguiente paso: usa Query QR Code (https://api.iroamly.shop/openapi/qrcodeQuery) para obtener el código QR

Parámetros de ejemplo

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

Respuesta de ejemplo

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

Endpoints de la API

Comprar código de canje

URL de la solicitud:https://api.iroamly.shop/openapi/purchaseCode

Método de la solicitud:POST

Parámetros de la solicitud:

ParámetroDescripciónTipo

emailCorreo electrónicoString

productListColección de productosObject[]

Campos de productList:

CampoDescripciónTipo

planNombre del plan. Indica plan o productCode.String

productCodeID del plan (productCode de Get Regional Plan List). Indica productCode o plan.String

quantityCantidadInt

Plan de prueba:iRoamly-Test-10GB

Parámetros de ejemplo

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

Respuesta de ejemplo

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

Endpoints de la API

Consultar código de canje

URL de la solicitud:https://api.iroamly.shop/openapi/codeQuery

Método de la solicitud:POST

Parámetros de la solicitud:

ParámetroDescripciónTipo

orderIdNúmero de pedidoString

Parámetros de ejemplo

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

Respuesta de ejemplo

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

Endpoints de la API

Convertir en código QR

(Nota: los códigos QR se envían al correo indicado tras la conversión. Los lotes más grandes pueden tardar más en procesarse.)

URL de la solicitud:https://api.iroamly.shop/openapi/redeemQRcode

Método de la solicitud:POST

Parámetros de la solicitud:

ParámetroDescripciónTipo

emailCorreo electrónicoString

codeListColección de códigos de canjeObject[]

Campos de productList:

CampoDescripciónTipo

redeemCodeCódigo de canjeString

Parámetros de ejemplo

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

Respuesta de ejemplo

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

Endpoints de la API

Consultar código QR

URL de la solicitud:https://api.iroamly.shop/openapi/qrcodeQuery

Método de la solicitud:POST

Parámetros de la solicitud:

ParámetroDescripciónTipo

redeemCodeCódigo de canjeString

Descripción de los campos de la respuesta:

CampoDescripciónTipo

redeemCodeCódigo de canjeString

qrcodeURL de la imagen del código QRString

statusEstado del código de canje (consulta Definiciones de estados del código de canje)Int

qrcode_contentContenido del código QR (cadena de activación LPA, p. ej., LPA:1$…)String

iscouldrenewalIndica si la eSIM se puede renovar: 1 - se puede renovar 0 - no se puede renovarInt

Parámetros de ejemplo

{
  "redeemCode": "m8hed7h2fed",
}

Respuesta de ejemplo

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

Endpoints de la API

Obtener el estado de los planes de renovación

URL de la solicitud:https://api.iroamly.shop/openapi/getRenewPlanStatus

Método de la solicitud:POST

Parámetros de la solicitud:

ParámetroDescripciónTipo

redeemCodeCódigo de canjeString

Descripción de los campos de la respuesta:

El code de nivel superior de la respuesta indica si el código de canje se puede renovar: 0 - renovación posible, -1 - renovación no posible. Las opciones de renovación se enumeran en data.renewList:

CampoDescripciónTipo

renewtypeTipo de renovación: 0 - Activar cuando caduque el plan actual 1 - Activar de inmediato (borra los datos restantes) 2 - Activar en una fecha indicadaInt

starttimeInicio del periodo de activación opcional: la hora de activación más temprana que puedes elegir (tipo de renovación 2).String

endtimeFin del periodo de activación opcional: la hora de activación más tardía que puedes elegir (tipo de renovación 2).String

Parámetros de ejemplo

{
  "redeemCode": "3cd2m3f23f3f3",
}

Respuesta de ejemplo

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

Endpoints de la API

Código de renovación

(Nota: al renovar, el grupo de renovación del plan seleccionado debe coincidir con el grupo de renovación del plan original.)

URL de la solicitud:https://api.iroamly.shop/openapi/renewcode

Método de la solicitud:POST

Parámetros de la solicitud:

ParámetroDescripciónTipo

redeemCodeCódigo que se quiere renovarString

planPlan de renovaciónString

renewtypeTipo de renovación: 0 - Activar cuando caduque el plan actual 1 - Activar de inmediato (borra los datos restantes) 2 - Activar en una fecha indicadaInt

renewtimeFecha y hora de entrada en vigor (obligatorio). Formato: YYYY-MM-DDTHH:mm:ssZString

Parámetros de ejemplo

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

Respuesta de ejemplo

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

Endpoints de la API

Obtener estadísticas del plan

URL de la solicitud:https://api.iroamly.shop/openapi/getnetworkflow

Método de la solicitud:GET

Parámetros de la solicitud:

ParámetroDescripciónTipo

redeemCodeCódigo de canje que se consulta.String

Descripción de los campos de la respuesta:

ParámetroDescripciónTipo

status0 - Inactivo 1 - Activo 2 - Caducado 9 - No válidoInt

flow_useDatos usados en el ciclo de facturación (en MB)String

flow_totalDatos totales del ciclo de facturación (en MB, o ilimitado)String

start_dataHora de inicio del planString

end_dataHora de fin del planString

installDeviceDispositivo instaladoString

installCountNúmero de instalacionesString

installTimeFecha de instalaciónString

Ejemplo válido

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

Ejemplo no válido

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

Definiciones

Definiciones de los códigos de estado de la respuesta

CódigoDescripción

1Éxito

2Error de autenticación de los parámetros de la solicitud

3Los parámetros no se proporcionaron como se requiere

4El código de producto no existe

5Créditos insuficientes

6El código de canje no existe

7El código de canje ya se canjeó o no existe

-1La solicitud falló

El éxito es code 1, excepto en /common/getPlanItem y /openapi/getRenewPlanStatus, que devuelven code 0 si tienen éxito.

Definiciones

Definiciones de estados del código de canje

EstadoDescripción

0No canjeado

1Canjeando

2Canjeado

3Error en el canje

Referencia de código

Referencia de código (Python)

Referencia de código

Comprar código de canje (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"
}

Referencia de código

Consultar código de canje (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"
}

Referencia de código

Convertir en código 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"}

Referencia de código

Consultar código 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"
}