API publique (/v1)

Lister les 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
Réponse
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#

Tous les paramètres sont facultatifs.

Paramètre	Type	Description
`country`	string	Code pays (ISO 3166-1 alpha-2, ex. JP)
`days`	integer	Validité exacte en jours
`minDays`	integer	Validité minimale (jours)
`maxDays`	integer	Validité maximale (jours)
`dataGb`	number	Données minimales (GB)
`unlimited`	boolean	true = forfaits illimités uniquement
`countries`	string	Voyage multi-pays — 2 à 8 codes pays séparés par des virgules (par ex. FR,IT,ES). Uniquement les forfaits qui fonctionnent dans tous
`maxDataGb`	number	Données maximales (GB)
`minPriceKrw / maxPriceKrw`	integer	Fourchette de prix (KRW)
`dataType`	string	daily (le forfait se renouvelle chaque jour) \| total (une seule enveloppe pour toute la période)
`localNumber`	boolean	true = uniquement les forfaits avec un numéro de téléphone local (appels/SMS)
`network`	string	local (réseau d’un opérateur local) \| roaming (réseau en itinérance)
`multiCountry`	boolean	true = forfaits multi-pays uniquement, false = forfaits d’un seul pays uniquement
`provider`	string	Code de l’opérateur — tel que renvoyé dans provider
`hotspot / fiveG`	boolean	Partage de connexion / réseau 5G (approximatif — voir les règles ci-dessous)
`sort`	string	recommended (par défaut) \| price (le moins cher d’abord) \| data (le plus de données d’abord) \| price_per_gb (le moins cher par Go d’abord) \| validity (le plus long d’abord)
`limit`	integer	1–50, 10 par défaut
`offset`	integer	Éléments à ignorer — arrondi à l’inférieur au multiple de limit
`lang`	string	Langue de la réponse : ko \| en \| ja \| zh-CN \| zh-TW (en par défaut)

Filter rules#

days remplace minDays et maxDays.
unlimited=true ignore dataGb.
countries remplace country.
hotspot · fiveG sont vérifiés parmi les 50 premiers forfaits correspondant aux autres filtres. offset est ignoré et la réponse inclut totalIsApproximate: true.
Les valeurs booléennes n’acceptent que true, false, 1 ou 0 ; toute autre valeur renvoie 400.
Les résultats n’incluent que les produits vendus directement par esimoa ; les produits retirés de la vente sont exclus.

Réponse#

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#

Champ	Type	Description
`id`	string	ID du produit — à utiliser avec l’endpoint de détail
`title`	string	Nom affiché (en lang)
`countryCode / countryName`	string \| null	Pays principal (null pour les forfaits multi-pays)
`coverageCountries`	string[]	Codes des pays où l’eSIM fonctionne
`isMultiCountry`	boolean	Forfait multi-pays
`dataAmount / dataAmountGB`	string / number	Volume de données (libellé / nombre en GB)
`isUnlimited`	boolean	Forfait illimité
`dataType`	'total' \| 'daily' \| null	Volume total ou volume quotidien
`validityDays`	integer	Validité en jours
`priceKrw / currency`	integer / 'KRW'	Prix en KRW
`provider / networkType`	string	Fournisseur / réseau (ex. : 5G)
`hotspot / hasLocalNumber / isLocalNetwork`	boolean	Partage de connexion / numéro local / réseau local
`url`	string	Lien d’achat contenant votre code partenaire (?ref=). Affichez-le tel quel.

Remarque

Les champs sont uniquement ajoutés : leurs noms et leur signification ne changent jamais. Analysez les réponses de façon à ignorer les champs inconnus.