Développeurs
Quatre endpoints, deux webhooks, aucune surprise.
Tout ce que fait la boutique, votre produit peut le faire. La surface entière tient sur une page.
Pourquoi cette API existe
La connectivité devrait être provisionnée au moment où le voyageur réserve, dans votre propre produit. Ce ne devrait pas être une découverte faite à l'aéroport.
Une plateforme de réservation peut rattacher des données à un itinéraire. Un fabricant d'appareils peut activer un forfait pendant la configuration initiale. Un outil d'équipe peut remettre ses données à une nouvelle recrue en même temps que son ordinateur portable.
Ces trois cas, ce sont quatre appels et un webhook. Il n'y a aucun portail partenaire où se connecter et aucun CSV à téléverser.
Authentification
Envoyez votre clé en tant que jeton bearer sur chaque requête. Les clés portent le préfixe sk_test pour le bac à sable et sk_live pour la production.
Une clé collée dans le mauvais environnement échoue avec un 401 au lieu de dépenser de l'argent en silence. Les clés sont limitées en portée, donc une clé en lecture seule ne peut pas passer commande et une clé émise pour un compte d'équipe ne voit pas les autres.
Faites tourner vos clés depuis la console quand vous voulez. L'ancienne continue de fonctionner 24 heures, donc vous n'êtes jamais forcé à une bascule en une seule fois.
curl https://api.orbislo.com/v1/catalog?country=jp \
-H "Authorization: Bearer sk_live_9f2c..." \
-H "Orbislo-Version: 2026-08-01"À propos de l'en-tête de version
L'en-tête de version est facultatif et fige la forme de la réponse sur une publication datée. Sans lui, vous obtenez la version en vigueur à la création de votre clé, qui ne change jamais dans votre dos.
Nous ajoutons des champs sans prévenir. Nous ne retirons jamais un champ et ne changeons jamais son type à l'intérieur d'une version.
4
endpoints dans toute l'API, plus 2 événements webhook
90 s
délai médian entre une commande acceptée et un profil activé
24 h
fenêtre pendant laquelle une clé d'idempotence répétée renvoie la réponse d'origine
Les endpoints
| Méthode | Chemin | Ce qu'il fait | Limite de débit |
|---|---|---|---|
| GET | /v1/catalog | Tous les forfaits que nous vendons, avec prix, volume, validité et pays couverts. | 600 par minute |
| POST | /v1/orders | Achète un forfait et renvoie une commande avec un job de provisionnement rattaché. | 60 par minute |
| GET | /v1/provisioning/:id | L'état d'un job de provisionnement, de queued jusqu'à activated ou failed. | 600 par minute |
| GET | /v1/usage/:esim_id | Octets consommés, octets restants et opérateur auquel une eSIM est rattachée. | 300 par minute |
Les limites s'appliquent par clé dans une fenêtre glissante. Chaque réponse porte le solde restant et l'heure de remise à zéro, et un 429 porte un délai de réessai en secondes. Si votre cas d'usage a vraiment besoin d'un seau plus grand, demandez, parce que l'agrandir est un changement de configuration et pas une négociation.
Catalogue
Le catalogue fait foi sur ce qui existe et sur ce que cela coûte. Il couvre les 145 destinations actives aujourd'hui.
Filtrez par pays, par région ou par famille de forfaits. Les prix sont renvoyés en unités mineures, donc la virgule flottante n'atteint jamais votre code de facturation.
GET /v1/catalog?country=jp
{
"object": "list",
"data": [
{
"id": "plan_jp_5gb",
"name": "Japan 5 GB",
"countries": ["jp"],
"data_mb": 5120,
"price": { "amount": 1150, "currency": "usd" },
"expires": false,
"throttle_mbps": null,
"tethering": true,
"carriers": ["NTT Docomo", "KDDI", "SoftBank"]
}
],
"has_more": false
}Deux champs à lire deux fois
Le champ expires vaut false sur tous les forfaits au volume que nous vendons, parce que nos données n'expirent pas. Si vous construisez un comparateur de prix, ce champ change le calcul plus que le prix lui-même.
Le champ throttle_mbps vaut null sur les forfaits au volume et 1 sur les pass journaliers illimités, où la pleine vitesse va jusqu'à 2 GB par jour puis retombe à 1 Mbps.
Nous mettons ce chiffre de bridage dans l'API pour la même raison que nous l'imprimons sur le bouton d'achat. Un chiffre qu'un voyageur découvre après coup, c'est un ticket de support.
Commandes
Un seul POST achète un forfait et lance le provisionnement. L'en-tête Idempotency-Key est obligatoire et non conseillé.
Le pire résultat possible dans cette API, c'est un timeout qui vous laisse dans le doute sur le fait qu'un voyageur ait été débité. Une clé obligatoire supprime complètement cet état.
POST /v1/orders
Idempotency-Key: 4f1d0f6e-1c3a-4a2b-9d77-1b6a0e7c9f21
Content-Type: application/json
{
"plan_id": "plan_jp_5gb",
"traveller_ref": "user_88213",
"imei": "356938035643809",
"activate": "on_first_use"
}
201 Created
{
"id": "ord_7Kd2mQ",
"status": "provisioning",
"esim_id": "esim_2xB9Ln",
"provisioning_id": "prv_5Ttq81",
"amount": { "amount": 1150, "currency": "usd" },
"activation": {
"type": "universal_link",
"url": "https://orbislo.com/i/2xB9Ln",
"lpa": "LPA:1$rsp.orbislo.com$K4-9TT-2XB9LN"
}
}Vérification de l'appareil et activation différée
Le champ imei est facultatif mais fortement recommandé. Envoyez-le et nous vérifions la compatibilité eSIM et le verrouillage opérateur avant d'encaisser.
Un téléphone incapable d'héberger un profil reçoit un 422 avec device_not_eligible, au lieu d'un forfait vendu et d'un voyageur en colère.
Mettre activate sur on_first_use fait démarrer toute fenêtre de validité à l'atterrissage du voyageur, et non au moment où votre serveur nous a appelés.
État du provisionnement
Le provisionnement est asynchrone, parce qu'il y a une plateforme opérateur à l'autre bout. Interrogez cet endpoint, ou prenez le webhook et laissez tomber l'interrogation régulière.
Le temps médian entre queued et activated est inférieur à 90 secondes. Tout ce qui reste en queued après 10 minutes est un échec, et se rembourse tout seul.
GET /v1/provisioning/prv_5Ttq81
{
"id": "prv_5Ttq81",
"status": "activated",
"states": [
{ "state": "queued", "at": "2026-08-24T09:14:02Z" },
{ "state": "provisioning", "at": "2026-08-24T09:14:04Z" },
{ "state": "installed", "at": "2026-08-24T09:14:41Z" },
{ "state": "activated", "at": "2026-08-24T09:15:07Z" }
],
"carrier": "KDDI",
"failure_reason": null
}Webhooks
Deux événements, et tous les deux changent ce qu'il faut dire au voyageur. Pointez-les vers n'importe quel endpoint HTTPS, réglé séparément par environnement.
Événements webhook
| Événement | Se déclenche quand | Quoi en faire |
|---|---|---|
| esim.activated | Le profil s'accroche à un réseau pour la première fois. | Dites au voyageur qu'il est en ligne. C'est le moment où l'achat devient réel pour lui. |
| esim.depleted | Le forfait franchit un seuil de consommation, à 80 pour cent puis à 100 pour cent. | Proposez une recharge avant qu'il soit coincé, pas après. |
POST https://your-app.example/hooks/orbislo
Orbislo-Signature: t=1756032907,v1=6c1b...
Content-Type: application/json
{
"id": "evt_9pQ4rz",
"type": "esim.depleted",
"created": "2026-08-24T11:41:33Z",
"data": {
"esim_id": "esim_2xB9Ln",
"threshold": 80,
"used_mb": 4096,
"remaining_mb": 1024,
"country": "jp"
}
}Vérifier une livraison
Calculez un HMAC SHA-256 sur l'horodatage, un point, puis le corps brut de la requête, avec le secret de votre endpoint. Comparez en temps constant.
Rejetez tout horodatage de plus de 5 minutes, ce qui bloque un rejeu. Les livraisons sont au moins une fois et réessayées 8 fois sur 24 heures, donc indexez votre gestionnaire sur l'identifiant de l'événement.
Codes d'erreur
| HTTP | Code | Ce que cela veut dire | Quoi faire |
|---|---|---|---|
| 400 | invalid_request | Un champ manque ou n'a pas le bon type. Le corps nomme le champ. | Corrigez la requête. Réessayer ne servira à rien. |
| 401 | invalid_token | Le jeton bearer est faux, révoqué, ou vient de l'autre environnement. | Vérifiez que vous n'envoyez pas une clé de bac à sable vers l'hôte de production. |
| 402 | insufficient_balance | Le solde de votre compte ne couvre pas la commande. | Rechargez, puis réessayez avec la même clé d'idempotence. |
| 404 | not_found | Aucun objet ne porte cet identifiant dans cet environnement. | Les identifiants du bac à sable et ceux de la production ne sont pas interchangeables. |
| 409 | idempotency_conflict | La même clé d'idempotence a été réutilisée avec un corps différent. | Prenez une nouvelle clé, ou renvoyez le corps d'origine octet pour octet. |
| 422 | device_not_eligible | L'appareil ne gère pas l'eSIM, ou il est verrouillé par un opérateur. | Lancez la vérification de l'appareil avant d'encaisser. |
| 429 | rate_limited | Vous avez dépassé le seau de cet endpoint. | Levez le pied avec le délai de réessai de l'en-tête. Ne bouclez pas. |
| 500 | internal_error | C'est nous. C'est déjà dans nos alertes. | Réessayez avec la même clé d'idempotence après 2 secondes. |
| 503 | provider_unavailable | Une plateforme opérateur en amont est hors service. | Réessayez pendant 10 minutes au plus. Nous basculons automatiquement là où un second opérateur existe. |
Chaque corps d'erreur porte un code, un message lisible par un humain et un identifiant de requête. Citez cet identifiant au support et vous sautez les quatre premières questions.
Bac à sable contre production
Même hôte, mêmes chemins, mêmes formes de réponse. Une clé préfixée sk_test ne touche jamais à l'argent et ne crée jamais de profil opérateur.
Les jobs de provisionnement parcourent toute la machine à états en 4 secondes environ, donc vos tests ne dorment pas 90 secondes chacun.
Commandez le forfait d'identifiant plan_test_fail pour obtenir un job en échec avec son motif. Commandez plan_test_slow pour en obtenir un qui reste en provisioning pendant 11 minutes, de quoi éprouver votre chemin de timeout.
Les livraisons de webhooks partent aussi dans le bac à sable, vers une URL que vous réglez par environnement.
Si vous préférez ne rien construire
Le programme d'affiliation rémunère les commandes apportées sans la moindre intégration, ce qui est la bonne réponse pour la plupart des sites de contenu.
L'endpoint MCP expose notre jeu de données de couverture et notre indice de prix à un assistant IA avec une ligne de configuration et zéro code.
Les forfaits que vous vendriez, les mesures de débit derrière le catalogue et la liste complète des pays sont publiés ouvertement sur ce site.
Les questions que posent les développeurs
Puis-je obtenir une clé d'API aujourd'hui ?
Combien de temps prend la validation ?
Quelle est la différence entre le bac à sable et la production ?
Ai-je besoin de clés d'idempotence ?
Quelles sont les limites de débit ?
Les webhooks sont-ils fiables ?
Existe-t-il un SDK ?
Que se passe-t-il si le provisionnement échoue ?
Commencez par le bac à sable, ou sautez le code entièrement
Les identifiants du bac à sable arrivent le jour ouvré même. Si vous préférez ne pas écrire d'intégration, le programme d'affiliation et l'endpoint MCP ne demandent rien à construire.