API pubblica (/v1)

Elenca eSIM

GET /v1/esims — search eSIMs by country, duration and data, and get purchase URLs that carry your partner code.

On this page

Request
Query parameters
Filter rules
Risposta
The Esim object

Request#

GET/v1/esims

curl "https://api.esimoa.com/v1/esims?country=JP&days=7&sort=price&limit=3&lang=en" \
  -H "X-API-Key: esk_live_your_key_here"

const res = await fetch(
  'https://api.esimoa.com/v1/esims?country=JP&days=7&sort=price&limit=3&lang=en',
  { headers: { 'X-API-Key': process.env.ESIMOA_API_KEY } },
);
if (!res.ok) throw new Error(`esimoa API ${res.status}`);

const { items, total } = await res.json();
for (const esim of items) {
  console.log(esim.title, esim.priceKrw, esim.url);
}

import os
import requests

res = requests.get(
    "https://api.esimoa.com/v1/esims",
    params={"country": "JP", "days": 7, "sort": "price", "limit": 3, "lang": "en"},
    headers={"X-API-Key": os.environ["ESIMOA_API_KEY"]},
    timeout=10,
)
res.raise_for_status()

for esim in res.json()["items"]:
    print(esim["title"], esim["priceKrw"], esim["url"])

Query parameters#

Tutti i parametri sono facoltativi.

Parametro	Tipo	Descrizione
`country`	string	Codice paese (ISO 3166-1 alpha-2, es. JP)
`days`	integer	Validità esatta in giorni
`minDays`	integer	Validità minima (giorni)
`maxDays`	integer	Validità massima (giorni)
`dataGb`	number	Dati minimi (GB)
`unlimited`	boolean	true = solo piani illimitati
`countries`	string	Viaggio in più paesi — 2–8 codici paese separati da virgole (es. FR,IT,ES). Solo i piani che funzionano in tutti
`maxDataGb`	number	Dati massimi (GB)
`minPriceKrw / maxPriceKrw`	integer	Fascia di prezzo (KRW)
`dataType`	string	daily (il traffico si rinnova ogni giorno) \| total (un unico traffico per tutto il periodo)
`localNumber`	boolean	true = solo piani con numero di telefono locale (chiamate/SMS)
`network`	string	local (rete di un operatore locale) \| roaming (rete in roaming)
`multiCountry`	boolean	true = solo piani multipaese, false = solo piani per un singolo paese
`provider`	string	Codice dell’operatore — come restituito in provider
`hotspot / fiveG`	boolean	Supporto tethering / rete 5G (approssimativo — vedi regole sotto)
`sort`	string	recommended (predefinito) \| price (prima il più economico) \| data (prima più dati) \| price_per_gb (prima il prezzo per GB più basso) \| validity (prima la durata più lunga)
`limit`	integer	1–50, predefinito 10
`offset`	integer	Elementi da saltare — arrotondato per difetto a un multiplo di limit
`lang`	string	Lingua della risposta: uno tra ko, en, ja, zh-CN, zh-TW, es, fr, ar, vi, th, id, it, de (predefinito en)

Filter rules#

days sostituisce minDays e maxDays.
unlimited=true ignora dataGb.
countries sostituisce country.
hotspot · fiveG vengono verificati tra i primi 50 piani che soddisfano gli altri filtri. offset viene ignorato e la risposta include totalIsApproximate: true.
I valori booleani accettano solo true, false, 1 o 0; qualsiasi altro valore restituisce 400.
I risultati includono solo i prodotti venduti direttamente da esimoa; quelli fuori produzione sono esclusi.

Risposta#

200 OKjson

{
  "success": true,
  "items": [
    {
      "id": "partner_9VKPYQ3JRYVK5797",
      "title": "Japan · 100 MB · 7 days",
      "countryCode": "JP",
      "countryName": "Japan",
      "coverageCountries": ["JP"],
      "isMultiCountry": false,
      "dataAmount": "100 MB",
      "dataAmountGB": 0.1,
      "isUnlimited": false,
      "dataType": "total",
      "validityDays": 7,
      "priceKrw": 1000,
      "currency": "KRW",
      "provider": "TSIM",
      "networkType": "5G",
      "hotspot": true,
      "hasLocalNumber": false,
      "isLocalNetwork": true,
      "url": "https://www.esimoa.com/en/plans/jp/partner_9VKPYQ3JRYVK5797?ref=p_yourcode&utm_source=esimoa_partner"
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0,
  "sort": "price"
}

The Esim object#

Campo	Tipo	Descrizione
`id`	string	ID prodotto — da usare con l’endpoint di dettaglio
`title`	string	Nome visualizzato (in lang)
`countryCode / countryName`	string \| null	Paese principale (null per i piani multipaese)
`coverageCountries`	string[]	Codici dei paesi in cui funziona l’eSIM
`isMultiCountry`	boolean	Piano multi-paese
`dataAmount / dataAmountGB`	string / number	Dati inclusi (etichetta / numero in GB)
`isUnlimited`	boolean	Piano illimitato
`dataType`	'total' \| 'daily' \| null	Quantità totale o giornaliera
`validityDays`	integer	Validità in giorni
`priceKrw / currency`	integer / 'KRW'	Prezzo in KRW
`provider / networkType`	string	Fornitore / rete (es. 5G)
`hotspot / hasLocalNumber / isLocalNetwork`	boolean	Tethering / numero locale / rete locale
`url`	string	Link di acquisto con il tuo codice partner (?ref=). Mostralo così com’è.

Nota

I campi vengono solo aggiunti: nomi e significati non cambiano mai. Analizza le risposte in modo da ignorare i campi sconosciuti.