Overview

API publique (/v1)

Shared rules of the /v1 API: base URL, response envelope, pagination and response language.

On this page

URL de base
Endpoints
Response envelope
Pagination
Response language
Prices & caching

URL de base#

Envoyez chaque requête en HTTPS à l’adresse ci-dessous. Une clé d’API publique est requise (Authentification), et toutes les réponses sont en JSON.

url

https://api.esimoa.com/v1

Endpoints#

Endpoint	Description
GET /v1/esims	Rechercher des eSIM
GET /v1/esims/:id	Obtenir une eSIM
GET /v1/countries	Lister les pays
GET /v1/openapi.json	Spécification OpenAPI 3.1 (sans clé)

Response envelope#

Les réponses réussies incluent toujours "success": true. Les listes sont renvoyées dans items et un résultat unique dans item.

json

// List endpoints
{ "success": true, "items": [ ... ], "total": 42, "limit": 10, "offset": 0, "sort": "price" }

// Detail endpoint
{ "success": true, "item": { ... } }

Pour les réponses d’erreur et les codes d’état, consultez Limites de requêtes et erreurs.

Pagination#

Les listes sont paginées avec limit (1–50, 10 par défaut) et offset. offset est toujours arrondi à l’inférieur au multiple de limit — par exemple, limit=10, offset=15 est traité comme offset=10. L’offset de la réponse est la valeur réellement utilisée, et total est le nombre total.

Pourboire

Demandez la page suivante avec offset + limit. Un offset qui n’est pas un multiple de limit pourrait répéter des éléments d’une page à l’autre ; il est donc arrondi à l’inférieur.

Response language#

Le paramètre lang (ko | en | ja | zh-CN | zh-TW, par défaut en) définit la langue des noms de pays, des titres d’articles et de la page d’achat vers laquelle pointe url. Faites-la correspondre à la langue de votre utilisateur.

Prices & caching#

Les prix (priceKrw) sont le prix de vente esimoa en KRW, sous forme d’entier. Les prix changent souvent — ne mettez les résultats de recherche en cache que quelques minutes au maximum ; le paiement esimoa fait toujours foi pour le montant débité.