Entwickler
Vier Endpunkte, zwei Webhooks, keine Überraschungen.
Alles, was der Shop kann, kann auch dein Produkt. Die gesamte Oberfläche passt auf eine Seite.
Warum es diese API gibt
Konnektivität sollte in dem Moment bereitgestellt werden, in dem der Reisende bucht, und zwar in deinem eigenen Produkt. Sie sollte nichts sein, das er erst am Flughafen entdeckt.
Eine Buchungsplattform kann Daten an eine Reise hängen. Ein Gerätehersteller kann einen Tarif schon bei der Einrichtung aktivieren. Ein Team-Tool kann einer neuen Kollegin ihr Datenvolumen zusammen mit dem Laptop übergeben.
Alle drei Fälle sind vier Aufrufe und ein Webhook. Es gibt kein Partnerportal zum Einloggen und keine CSV zum Hochladen.
Authentifizierung
Schick deinen Schlüssel bei jeder Anfrage als Bearer-Token mit. Schlüssel tragen das Präfix sk_test für die Sandbox und sk_live für die Produktion.
Ein Schlüssel, der in der falschen Umgebung landet, scheitert mit einem 401, statt still Geld auszugeben. Schlüssel haben einen Geltungsbereich, also kann ein reiner Leseschlüssel keine Bestellung auslösen, und ein Schlüssel für ein Teamkonto sieht kein anderes.
Rotiere jederzeit über die Konsole. Der alte Schlüssel funktioniert noch 24 Stunden weiter, du wirst also nie zu einer Umstellung an einem Stichtag gezwungen.
curl https://api.orbislo.com/v1/catalog?country=jp \
-H "Authorization: Bearer sk_live_9f2c..." \
-H "Orbislo-Version: 2026-08-01"Zum Version-Header
Der Version-Header ist optional und friert die Antwortstruktur auf ein datiertes Release ein. Ohne ihn bekommst du die Version, gegen die dein Schlüssel angelegt wurde, und die ändert sich nie unter dir weg.
Wir ergänzen Felder ohne Vorwarnung. Wir entfernen nie ein Feld und ändern nie seinen Typ innerhalb einer Version.
4
Endpunkte in der ganzen API, dazu 2 Webhook-Ereignisse
90 s
mittlere Zeit von einer erfolgreichen Bestellung bis zum aktivierten Profil
24 h
Fenster, in dem ein wiederholter Idempotenzschlüssel die ursprüngliche Antwort liefert
Die Endpunkte
| Methode | Pfad | Was er tut | Ratenlimit |
|---|---|---|---|
| GET | /v1/catalog | Jeder Tarif, den wir verkaufen, mit Preis, Volumen, Gültigkeit und abgedeckten Ländern. | 600 pro Minute |
| POST | /v1/orders | Kauft einen Tarif und liefert eine Bestellung mit angehängtem Provisionierungsjob. | 60 pro Minute |
| GET | /v1/provisioning/:id | Der Zustand eines Provisionierungsjobs, von queued bis activated oder failed. | 600 pro Minute |
| GET | /v1/usage/:esim_id | Verbrauchte Bytes, verbleibende Bytes und der Netzbetreiber, an dem eine eSIM hängt. | 300 pro Minute |
Limits gelten pro Schlüssel in einem gleitenden Fenster. Jede Antwort führt den Restwert und die Rücksetzzeit mit, und ein 429 führt eine Wartezeit in Sekunden mit. Wenn dein Anwendungsfall wirklich einen größeren Eimer braucht, frag danach, denn ihn zu vergrößern ist eine Konfigurationsänderung und keine Verhandlung.
Katalog
Der Katalog ist die verbindliche Quelle dafür, was es gibt und was es kostet. Er deckt die 145 heute aktiven Reiseziele ab.
Filtere nach Land, nach Region oder nach Tariffamilie. Preise kommen in kleinsten Einheiten zurück, damit Gleitkomma nie in deinen Abrechnungscode gelangt.
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
}Zwei Felder, die zweimal Lesen verdienen
Das Feld expires ist bei jedem volumenbasierten Tarif false, den wir verkaufen, denn unser Datenvolumen verfällt nicht. Wenn du einen Preisvergleich baust, verändert dieses Feld die Rechnung stärker als der Preis.
Das Feld throttle_mbps ist bei volumenbasierten Tarifen null und bei unbegrenzten Tagespässen 1, wo volle Geschwindigkeit bis 2 GB am Tag reicht und danach auf 1 Mbps fällt.
Wir schreiben die Drosselzahl aus demselben Grund in die API, aus dem wir sie auf den Kaufknopf drucken. Eine Zahl, die ein Reisender erst später erfährt, ist ein Supportticket.
Bestellungen
Ein einziges POST kauft einen Tarif und startet die Provisionierung. Der Header Idempotency-Key ist Pflicht und keine Empfehlung.
Das schlimmste Ergebnis in dieser API ist ein Timeout, nach dem du nicht weißt, ob dem Reisenden Geld abgebucht wurde. Ein Pflichtschlüssel beseitigt diesen Zustand vollständig.
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"
}
}Geräteprüfung und verzögerte Aktivierung
Das Feld imei ist optional, aber dringend empfohlen. Schick es mit, und wir prüfen eSIM-Fähigkeit und SIM-Lock, bevor Geld fließt.
Ein Telefon, das kein Profil halten kann, bekommt ein 422 mit device_not_eligible statt eines verkauften Tarifs und eines wütenden Reisenden.
Wenn du activate auf on_first_use setzt, startet jedes Gültigkeitsfenster bei der Landung des Reisenden und nicht, als dein Server uns aufgerufen hat.
Provisionierungsstatus
Die Provisionierung läuft asynchron, weil am anderen Ende eine Netzbetreiberplattform hängt. Frag diesen Endpunkt ab, oder nimm den Webhook und spar dir das Abfragen.
Die mittlere Zeit von queued bis activated liegt unter 90 Sekunden. Alles, was nach 10 Minuten noch in queued steht, ist ein Fehlschlag, und er erstattet sich selbst.
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
Zwei Ereignisse, und beide ändern, was einem Reisenden gesagt werden sollte. Richte sie auf einen beliebigen HTTPS-Endpunkt, getrennt je Umgebung eingestellt.
Webhook-Ereignisse
| Ereignis | Wird ausgelöst, wenn | Was du damit tust |
|---|---|---|
| esim.activated | Das Profil bucht sich zum ersten Mal in ein Netz ein. | Sag dem Reisenden, dass er online ist. In diesem Moment wird der Kauf für ihn real. |
| esim.depleted | Der Tarif überschreitet eine Verbrauchsschwelle, bei 80 Prozent und noch einmal bei 100 Prozent. | Biete ein Aufladen an, bevor er strandet, und nicht danach. |
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"
}
}Eine Zustellung prüfen
Berechne HMAC SHA-256 über den Zeitstempel, einen Punkt und den rohen Anfragekörper, mit dem Secret deines Endpunkts. Vergleiche in konstanter Zeit.
Weise alles mit einem Zeitstempel zurück, der älter als 5 Minuten ist, das stoppt einen Replay. Zustellungen erfolgen mindestens einmal und werden 8 Mal über 24 Stunden wiederholt, also schlüssele deinen Handler auf die Event-ID.
Fehlercodes
| HTTP | Code | Was er bedeutet | Was zu tun ist |
|---|---|---|---|
| 400 | invalid_request | Ein Feld fehlt oder hat den falschen Typ. Der Körper nennt das Feld. | Korrigiere die Anfrage. Ein erneuter Versuch hilft nicht. |
| 401 | invalid_token | Das Bearer-Token ist falsch, widerrufen oder aus der anderen Umgebung. | Prüfe, ob du einen Sandbox-Schlüssel an den Produktivhost schickst. |
| 402 | insufficient_balance | Dein Kontoguthaben deckt die Bestellung nicht. | Lade auf und versuche es mit demselben Idempotenzschlüssel erneut. |
| 404 | not_found | In dieser Umgebung gibt es kein Objekt mit dieser ID. | Sandbox-IDs und Produktiv-IDs sind nicht austauschbar. |
| 409 | idempotency_conflict | Derselbe Idempotenzschlüssel wurde mit einem anderen Körper wiederverwendet. | Nimm einen neuen Schlüssel, oder schicke den ursprünglichen Körper Byte für Byte erneut. |
| 422 | device_not_eligible | Das Gerät kann keine eSIM, oder es ist netzgesperrt. | Führe die Geräteprüfung durch, bevor du Geld nimmst. |
| 429 | rate_limited | Du bist über den Eimer für diesen Endpunkt hinaus. | Warte mit der Wartezeit aus dem Header ab. Dreh keine Schleife. |
| 500 | internal_error | Unserer. Er liegt schon in unserem Alarm. | Versuche es nach 2 Sekunden mit demselben Idempotenzschlüssel erneut. |
| 503 | provider_unavailable | Eine vorgelagerte Netzbetreiberplattform ist ausgefallen. | Versuche es bis zu 10 Minuten lang. Wo ein zweiter Netzbetreiber existiert, schalten wir automatisch um. |
Jeder Fehlerkörper führt einen Code, eine für Menschen lesbare Meldung und eine Request-ID mit. Nenne dem Support die Request-ID, und du überspringst die ersten vier Fragen.
Sandbox gegen Produktion
Gleicher Host, gleiche Pfade, gleiche Antwortformen. Ein Schlüssel mit Präfix sk_test fasst nie Geld an und legt nie ein Netzbetreiberprofil an.
Provisionierungsjobs durchlaufen die ganze Zustandsmaschine in rund 4 Sekunden, deine Tests schlafen also nicht jeweils 90 Sekunden.
Bestelle die Tarif-ID plan_test_fail für einen fehlgeschlagenen Job samt Grund. Bestelle plan_test_slow für einen, der 11 Minuten in provisioning hängt, damit du deinen Timeout-Pfad durchspielen kannst.
Webhook-Zustellungen laufen auch in der Sandbox, gegen eine URL, die du je Umgebung setzt.
Falls du lieber gar nichts bauen willst
Das Partnerprogramm zahlt auf vermittelte Bestellungen ganz ohne Integration, und das ist für die meisten Content-Seiten die richtige Antwort.
Der MCP-Endpunkt gibt unseren Abdeckungsdatensatz und den Preisindex mit einer Zeile Konfiguration und ohne Code an einen KI-Assistenten weiter.
Die Tarife, die du verkaufen würdest, die gemessenen Geschwindigkeitsdaten hinter dem Katalog und die vollständige Länderliste sind alle offen auf dieser Seite veröffentlicht.
Fragen, die Entwickler stellen
Bekomme ich heute einen API-Schlüssel?
Wie lange dauert die Freigabe?
Was ist der Unterschied zwischen Sandbox und Produktion?
Brauche ich Idempotenzschlüssel?
Wie hoch sind die Ratenlimits?
Wie zuverlässig sind Webhooks?
Gibt es ein SDK?
Was passiert, wenn die Provisionierung scheitert?
Fang mit der Sandbox an, oder lass den Code ganz weg
Sandbox-Zugangsdaten kommen am selben Werktag. Wenn du lieber keine Integration schreibst, brauchen weder das Partnerprogramm noch der MCP-Endpunkt irgendetwas Gebautes.