Documentação da API

Referência da API da iRoamly Shop: autenticação, planos, compra e entrega, renovação e uso.

Visão geral

Explicação básica

Para garantir a segurança das informações transmitidas ao servidor, são adotados os seguintes mecanismos de segurança:

1.Todas as interfaces usam links HTTPS secure.
2.AuthKey atribuída, usada para autenticação na API (comprimento máximo: 32 caracteres).
3.AuthSecret atribuída, usada para gerar o hash da requisição (comprimento máximo: 50 caracteres).
4.As requisições usam hashes SHA-256 para autenticação.

Visão geral

Padrões da interface

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

Protocolo da requisição:HTTPS

Método da requisição:GET / POST

Formato de transferência de dados:application/json

Parâmetros do header da requisição:

AuthKey: chave de autenticação do cliente, tipo texto (String)

Certification: string com o hash SHA-256 de AuthKey+AuthSecret concatenados nessa ordem.

/common/getPlanItem não exige o header AuthKey nem Certification.

Endpoints da API

Obter lista de planos regionais

URL da requisição:https://api.iroamly.shop/common/getPlanItem

Método da requisição:GET

Não é necessário o header AuthKey nem Certification.

Parâmetros da requisição:

ParâmetroDescriçãoTipo

regionAceita códigos ISO2, nomes de países (sem diferenciar maiúsculas e minúsculas) ou formatos padronizados (ex.: united-states).String

Formato da resposta:

Sucesso: HTTP 200. Os planos são retornados em data.list.

Sempre retorna HTTP 200. Quando não há dados, data.list é um array vazio e msg é Success.

Descrição dos campos da resposta:

CampoDescriçãoTipo

planNome do plano (inclui região, tipo, franquia de dados e duração).String

productCodeID único do plano para compras ou consultas.String

dataFranquia de dados (ex.: 10GB, Unlimited, 500MB).String

typeTipo de plano (ex.: Total, Daily, Unlimited).String

plan_typeCategoria do plano (ex.: default).String

package_typeTipo de pacote (ex.: Data Only).String

durationPeríodo de validade em dias (ex.: 10).String

speedVelocidade da rede (ex.: 4G / 5G).String

operatorOperadoras compatíveis (ex.: T-Mobile/AT&T).String

regionNome oficial da região (ex.: United States).String

region_indexIdentificador padronizado da região (minúsculas com hífens, ex.: united-states).String

creditPreço do plano em créditos (não em dólares).Float

remarkObservações adicionais (ex.: regras de redução de velocidade).String

created_atData e hora de criação do plano (formato ISO 8601).String

Exemplo de requisição

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

Exemplo de retorno

{
  "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 da API

Compra direta de QR code

URL da requisição:https://api.iroamly.shop/openapi/purchaseqrcode

Método da requisição:POST

Parâmetros da requisição:

ParâmetroDescriçãoTipo

emailCaixa de e-mail que receberá os QR codes. Se estiver vazio, nenhum e-mail será enviado.String

productListConjunto de produtosObject[]

Campos de productList:

CampoDescriçãoTipo

planNome do plano. Informe plan ou productCode.String

productCodeID do plano (productCode de Obter lista de planos regionais). Informe productCode ou plan.String

quantityQuantidadeInt

Plano de teste:iRoamly-Test-10GB

Próximo passo: use Consultar QR code (https://api.iroamly.shop/openapi/qrcodeQuery) para obter o QR code

Exemplo de parâmetros

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

Exemplo de retorno

{
  "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 da API

Comprar código de resgate

URL da requisição:https://api.iroamly.shop/openapi/purchaseCode

Método da requisição:POST

Parâmetros da requisição:

ParâmetroDescriçãoTipo

emailE-mailString

productListConjunto de produtosObject[]

Campos de productList:

CampoDescriçãoTipo

planNome do plano. Informe plan ou productCode.String

productCodeID do plano (productCode de Obter lista de planos regionais). Informe productCode ou plan.String

quantityQuantidadeInt

Plano de teste:iRoamly-Test-10GB

Exemplo de parâmetros

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

Exemplo de retorno

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

Endpoints da API

Consultar código de resgate

URL da requisição:https://api.iroamly.shop/openapi/codeQuery

Método da requisição:POST

Parâmetros da requisição:

ParâmetroDescriçãoTipo

orderIdNúmero do pedidoString

Exemplo de parâmetros

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

Exemplo de retorno

{
  "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 da API

Converter em QR code

(Observação: os QR codes são enviados para o e-mail especificado após a conversão. Lotes maiores podem levar mais tempo para serem processados.)

URL da requisição:https://api.iroamly.shop/openapi/redeemQRcode

Método da requisição:POST

Parâmetros da requisição:

ParâmetroDescriçãoTipo

emailE-mailString

codeListConjunto de códigos de resgateObject[]

Campos de productList:

CampoDescriçãoTipo

redeemCodeCódigo de resgateString

Exemplo de parâmetros

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

Exemplo de retorno

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

Endpoints da API

Consultar QR code

URL da requisição:https://api.iroamly.shop/openapi/qrcodeQuery

Método da requisição:POST

Parâmetros da requisição:

ParâmetroDescriçãoTipo

redeemCodeCódigo de resgateString

Descrição dos campos da resposta:

CampoDescriçãoTipo

redeemCodeCódigo de resgateString

qrcodeURL da imagem do QR codeString

statusStatus do código de resgate (veja Definições de status do código de resgate)Int

qrcode_contentConteúdo do QR code (string de ativação LPA, ex.: LPA:1$…)String

iscouldrenewalSe a eSIM pode ser renovada: 1 - pode ser renovada 0 - não pode ser renovadaInt

Exemplo de parâmetros

{
  "redeemCode": "m8hed7h2fed",
}

Exemplo de retorno

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

Endpoints da API

Obter status do plano de renovação

URL da requisição:https://api.iroamly.shop/openapi/getRenewPlanStatus

Método da requisição:POST

Parâmetros da requisição:

ParâmetroDescriçãoTipo

redeemCodeCódigo de resgateString

Descrição dos campos da resposta:

O code de nível superior da resposta indica se o código de resgate pode ser renovado: 0 - renovação possível, -1 - renovação não possível. As opções de renovação estão listadas em data.renewList:

CampoDescriçãoTipo

renewtypeTipo de renovação: 0 - Ativar quando o plano atual expirar 1 - Ativar imediatamente (apaga os dados restantes) 2 - Ativar em um horário especificadoInt

starttimeInício da janela de ativação opcional: o horário de ativação mais cedo que você pode escolher (tipo de renovação 2).String

endtimeFim da janela de ativação opcional: o horário de ativação mais tarde que você pode escolher (tipo de renovação 2).String

Exemplo de parâmetros

{
  "redeemCode": "3cd2m3f23f3f3",
}

Exemplo de retorno

{
  "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 da API

Código de renovação

(Observação: ao renovar, o grupo de renovação do plano selecionado deve corresponder ao grupo de renovação do plano original.)

URL da requisição:https://api.iroamly.shop/openapi/renewcode

Método da requisição:POST

Parâmetros da requisição:

ParâmetroDescriçãoTipo

redeemCodeCódigo que precisa ser renovadoString

planPlano de renovaçãoString

renewtypeTipo de renovação: 0 - Ativar quando o plano atual expirar 1 - Ativar imediatamente (apaga os dados restantes) 2 - Ativar em um horário especificadoInt

renewtimeData e hora de entrada em vigor (obrigatório). Formato: YYYY-MM-DDTHH:mm:ssZString

Exemplo de parâmetros

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

Exemplo de retorno

{
  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 da API

Obter estatísticas do plano

URL da requisição:https://api.iroamly.shop/openapi/getnetworkflow

Método da requisição:GET

Parâmetros da requisição:

ParâmetroDescriçãoTipo

redeemCodeCódigo de resgate a consultar.String

Descrição dos campos da resposta:

ParâmetroDescriçãoTipo

status0 - Inativo 1 - Ativo 2 - Expirado 9 - InválidoInt

flow_useDados usados no ciclo de cobrança (em MB)String

flow_totalTotal de dados no ciclo de cobrança (em MB, ou ilimitado)String

start_dataHorário de início do planoString

end_dataHorário de término do planoString

installDeviceAparelho instaladoString

installCountNúmero de instalaçõesString

installTimeData de instalaçãoString

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

Exemplo inválido

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

Definições

Definições dos códigos de status da resposta

CódigoDescrição

1Sucesso

2Falha na autenticação dos parâmetros da requisição

3Os parâmetros não foram informados conforme exigido

4O código do produto não existe

5Créditos insuficientes

6O código de resgate não existe

7O código de resgate já foi resgatado ou não existe

-1Falha na requisição

O sucesso é code 1, exceto em /common/getPlanItem e /openapi/getRenewPlanStatus, que retornam code 0 em caso de sucesso.

Definições

Definições de status do código de resgate

StatusDescrição

0Não resgatado

1Resgatando

2Resgatado

3Falha no resgate

Referência de código

Referência de código (Python)

Referência de código

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

Referência de código

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

Referência de código

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

Referência de código

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