Ratgeber

Die Atli-eSIM-API in deine Website oder App integrieren

Kein API-Key: Jeder deiner Nutzer bekommt ein Atli-Gastkonto. So ordnest du es deinem Partnercode zu, erstellst Angebote, kassierst und lieferst die eSIM.

Ein curl-Aufruf an den Kauf-Endpunkt der Atli-API neben einem Handy mit der Zahlungsseite von Atli, dazu das geflügelte blaue Atli-Maskottchen mit einem Handy neben einem Koffer

Partner können dieselbe Atli-eSIM-API nutzen, auf der heyatli.com und das Atli-Widget laufen. Für eine Website, eine App oder einen Bot kannst du eigene Oberflächen für Reiseziellisten, Tarifauswahl, Checkout und Installation bauen. Atli liefert den Tarifkatalog, wickelt Zahlungen über sein Stripe-Konto ab und stellt die eSIMs aus.

Die API verwendet keine API-Keys auf Anwendungsebene. Die Authentifizierung läuft über Tokens der einzelnen Nutzer. Dein Server meldet jeden Nutzer mit einer eindeutigen Geräte-ID oder über OAuth an und stellt die API-Anfragen dann in seinem Namen. Jedes Gastkonto braucht eine eigene Geräte-ID, die deine Anwendung sicher speichern muss.

Sandbox, Produktion und die OpenAPI-Datei

SandboxProduktion
APIhttps://api-staging.heyatli.comhttps://api.heyatli.com
OpenAPI-Dateihttps://api-staging.heyatli.com/openapi.yamlhttps://api.heyatli.com/openapi.yaml
Zahlungsseitehttps://staging.heyatli.com/payhttps://heyatli.com/pay

Die Sandbox arbeitet mit eigenen Konten und Testzahlungen, deshalb wird keine echte Karte belastet. Ihre eSIMs stammen von einem Testnetzbetreiber, lassen sich also nicht auf einem Handy installieren, und für Verkäufe in der Sandbox gibt es nie Provision. Alle Beispiele in diesem Ratgeber, die Konten oder Bestellungen anlegen, nutzen Sandbox-Endpunkte. Für die Produktion stellst du die Basis-URL der API auf https://api.heyatli.com um. Die Referenz unter partners.heyatli.com/de/dev/api schaltet zwischen beiden um.

Die Karte der wichtigsten Abläufe der Atli-API: Nutzer anlegen, Angebot holen, kaufen und bezahlen, eSIM erhalten, installieren und Verbrauch verfolgen, dazu optionale Zweige für ein echtes Konto, gespeicherte Karten und Gruppenkarten, Aufladungen, Rabatte und Teilen

Die API gibt Fehler immer im selben Format zurück: mit einem code, einer englischen message und einer trace_id für die Fehlersuche mit dem Support von Atli. Entscheide anhand von code, wie deine Anwendung den Fehler behandelt und welche Meldung sie anzeigt. Das Feld message kannst du in deinen Logs aufbewahren.

Anmeldung, Angebote, Gutscheineinlösung und eSIM-Sync unterliegen einem Rate-Limit, und eine abgewiesene Anfrage antwortet mit 429 und Retry-After in Sekunden.

Statt einzelne HTTP-Requests selbst zu schreiben, kannst du aus der OpenAPI-Spezifikation einen typisierten API-Client generieren:

Bash
docker run --rm -v "$PWD:/out" \
  openapitools/openapi-generator-cli generate \
  -i https://api.heyatli.com/openapi.yaml \
  -g typescript-fetch -o /out/atli-sdk

Tausch typescript-fetch gegen python, java, csharp, php oder swift6 aus. Für Go brauchst du go --additional-properties=enumClassPrefix=true.

Schritt 1: Nutzer anlegen

Du kannst für jeden Nutzer ein Atli-Gastkonto anlegen, ohne dass er sich registrieren muss. Erzeuge pro Nutzer eine eindeutige UUID, zum Beispiel mit crypto.randomUUID(), und speichere sie sicher in seinem Nutzerdatensatz.

Behandle die Geräte-ID wie vertrauliche Zugangsdaten, denn wer Zugriff darauf hat, kann sich als dieser Nutzer anmelden.

Mit dieser ID meldet dein Server den Nutzer an. Eine ID, die Atli noch nicht kennt, legt ein Gastkonto an, eine bekannte meldet den Gast wieder an:

Bash
curl https://api-staging.heyatli.com/login \
  -H 'Content-Type: application/json' \
  -d '{ "device_id": "YOUR_DEVICE_ID" }'
JSON
{
  "token": "eyJhbGci…",
  "refresh_token": "…",
  "expires_in": 900,
  "session_id": "…",
  "user": { "id": "…", "email": null }
}

Schick token bei jedem Aufruf, der einen Nutzer braucht, als Authorization: Bearer YOUR_TOKEN mit. Das Token gilt 15 Minuten. Erneuere es kurz vor Ablauf mit POST /refresh und dem refresh_token. Die Antwort auf den Refresh nennt das neue Token access_token, nicht token. Achte darauf, dass deine Integration das richtige Feld liest, damit die Authentifizierung nicht fehlschlägt, sobald das erste Token abläuft. Speichere jedes Mal das Refresh-Token, denn jeder Refresh liefert ein neues und macht das alte ungültig. Verlierst du beide, melde dich erneut mit der Geräte-ID an.

Ein Gast kann eSIMs kaufen und nutzen. Manche geteilten eSIMs und Gutscheine brauchen ein echtes Konto, und die API verweigert sie einem Gast mit einem Code wie gift_sign_in_required. Um dem Gast eine E-Mail-Adresse zu geben, schick sein Token und seine device_id an POST /auth/email/otp und bestätige dann mit POST /auth/email/verify. Eine Anmeldung über WhatsApp oder Telegram kann aus einem Gast genauso ein echtes Konto machen. In beiden Fällen bleiben die vorhandenen eSIMs und Kontodaten des Gasts erhalten. Fehlt die device_id oder gehört die E-Mail-Adresse schon zu einem Atli-Konto, landet die Person in einem anderen Konto.

Schritt 2: Nutzer deinem Partnercode zuordnen

Ordne jeden neuen Nutzer vor seinem ersten Angebot deinem Code zu:

Bash
curl https://api-staging.heyatli.com/user/referral/redeem \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "code": "YOUR_PARTNER_CODE" }'

Das Feld result gibt das Ergebnis an: ok bedeutet, dass der Nutzer erfolgreich zugeordnet wurde, already, dass er bereits jemandem zugeordnet ist, notnew, dass er schon einmal gekauft hat, own, dass es sich um deinen eigenen Empfehlungscode handelt, und notfound, dass der Code nicht gefunden wurde. Zuordnen lässt sich nur, wer noch niemandem zugeordnet ist und noch nie gekauft hat, und das nur einmal. Mach diesen Aufruf direkt nach dem Anlegen des Nutzers.

Die Zuordnung ist dauerhaft. Hat dein Code einen Rabatt, gilt er für die erste eSIM des Nutzers, ohne dass du den Code erneut schicken musst. Was die Zuordnung dir einbringt, steht im Ratgeber zum Partnerprogramm.

Schritt 3: Tarife zeigen und ein Angebot holen

GET /explore/plans liefert den vollständigen Katalog mit allen verfügbaren Reisezielen, Paketen, Preisen und Datenvolumen. Ein Token braucht es nicht, also kann dein Server Tarife auflisten, bevor jemand ein Konto hat. Ruf den Endpunkt von deinem Server aus auf, denn die API lehnt Browser-Anfragen von anderen Websites mit 403 ab. Übergib currency und filtere mit destination (JP, europe) oder category (local, regional, global):

Bash
curl 'https://api-staging.heyatli.com/explore/plans?currency=EUR&destination=JP'

Die id eines Pakets ist die product_id, die du kaufst. Hol mit store: true ein Angebot dafür ein, dann bekommst du eine quote_id:

Bash
curl https://api-staging.heyatli.com/plan/quote \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "product_id": "THE_PACKAGE_ID",
        "currency": "EUR",
        "store": true }'
JSON
{
  "subtotal_cents": 1500,
  "total_discount_cents": 150,
  "net_total_cents": 1350,
  "currency": "EUR",
  "quote_id": "…",
  "expires_at": "…"
}

Zeig net_total_cents als Endpreis an. Gespeicherte Angebote laufen nach 30 Minuten ab, also erstelle das Angebot, wenn der Nutzer zum Checkout geht. Jeder Nutzer hat immer nur ein gespeichertes Angebot, und ein neues ersetzt das vorherige.

target_esim_id lädt eine eSIM auf, die der Nutzer schon hat. Ohne diesen Parameter kommt der Tarif auf die Standard-eSIM des Nutzers. Hat er noch keine eSIM oder verkauft das Netz der Standard-eSIM diesen Tarif nicht, kommt der Tarif auf eine neue eSIM. Ist jemand mit dem eigenen Atli-Konto angemeldet, sagt new_esim im Angebot, welcher Fall eintritt. Bei Gästen fehlt das Feld. Vergleiche bei einem Gast die eSIM der abgeschlossenen Bestellung mit denen, die GET /esims auflistet, bevor du Installationsschritte zeigst.

auto_apply_best_voucher wendet den wertvollsten einlösbaren Gutschein des Nutzers an, und mit points_to_redeem lösen Nutzer ihre Punkte ein, die in Atlis Apps als Atli-Credits erscheinen. Eine Bestellung nimmt nur eine Art von Rabatt. Der Empfehlungsrabatt aus deinem Link hat Vorrang und schlägt jeden Gutschein, den das Angebot von sich aus wählen würde. Ein mit voucher_code angegebener Gutschein ersetzt ihn, und wer sowohl einen Gutschein als auch einen referral_code angibt, bekommt den Fehler cannot_combine_voucher_and_referral. Punkte zählen nur, wenn keiner von beiden greift.

Schritt 4: Bestellung anlegen und kassieren

Kauf das gespeicherte Angebot über seine quote_id. Die Bestellung übernimmt Tarif, Rabatte und Preis aus dem Angebot. Hat sich der Gesamtbetrag seitdem um mehr als 1 % verändert, schlägt der Kauf mit price_changed fehl, und du holst ein neues Angebot ein.

Jedes Angebot lässt sich für genau eine Bestellung verwenden. Wird eine Kaufanfrage versehentlich oder nach einem Timeout erneut gesendet, gibt die API die bestehende Bestellung zurück, statt eine doppelte anzulegen. Die Anfrage muss außerdem einen idempotency_key enthalten. Er verhindert doppelte Bestellungen, wenn du direkt über eine product_id statt über ein gespeichertes Angebot kaufst.

Bash
curl https://api-staging.heyatli.com/plan/purchase \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "quote_id": "THE_QUOTE_ID",
        "idempotency_key": "A_NEW_UUID" }'
JSON
{
  "order_id": "…",
  "client_secret": "pi_…_secret_…",
  "sealed_secret": "eyJhbGciOiJFQ0RILUVTIi…",
  "key_id": "…",
  "seal_signature": "…",
  "options": "{\"message\":\"Plan for Japan\",\"lang\":\"en\"}",
  "options_signature": "…",
  "total_amount_cents": 1350,
  "status": "pending_payment"
}

Das client_secret gehört zu einem PaymentIntent auf dem Stripe-Konto von Atli. Mounte damit das Payment Element von Stripe. Dein Server liest den Publishable Key aus GET /stripe/config und gibt ihn zusammen mit dem client_secret an die Seite weiter. Schreib den Key nicht fest in den Code, denn er unterscheidet sich zwischen Sandbox und Produktion, und ruf ihn nicht von der Seite aus ab, denn die API lehnt Browser-Anfragen von anderen Websites ab:

JavaScript
const stripe = Stripe(publishable_key);

const elements = stripe.elements({ clientSecret: order.client_secret });
elements.create('payment').mount('#pay');

const { error } = await stripe.confirmPayment({
  elements,
  confirmParams: { return_url: window.location.href },
  redirect: 'if_required',
});

Gib das client_secret nur an die Sitzung des Nutzers weiter, der gerade bezahlt, und halte es aus deinen Logs heraus. Sobald Stripe die Zahlung bestätigt, sagst du Atli, dass es die eSIM ausstellen soll:

Bash
curl https://api-staging.heyatli.com/plan/fulfill-payment \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "order_id": "THE_ORDER_ID" }'

Schlägt dieser Aufruf fehl, belaste nicht noch einmal. Atli schließt eine bezahlte Bestellung von selbst ab.

Belastet wird über das Stripe-Konto von Atli. Auf der Kartenabrechnung deiner Kundschaft steht deshalb der Name Atli, und Erstattungen und Zahlungsanfechtungen gehen an Atli. Willst du Apple Pay und Google Pay in deinem eigenen Formular anbieten, schreib an [email protected], sobald deine Integration echte Verkäufe vorweisen kann. Gespeicherte Karten laufen über denselben Kauf: Ergänze payment_method_id, um eine davon zu belasten, oder save_card: true, um eine neue Karte fürs nächste Mal zu speichern.

Bezahlen auf der Zahlungsseite von Atli

Bots auf WhatsApp oder Telegram, Sprachanwendungen und KI-Assistenten können das Zahlungsformular von Stripe nicht anzeigen. Für solche Integrationen kannst du Nutzer auf die gehostete Zahlungsseite von Atli schicken. Bau den Link aus den drei versiegelten Werten, die der Kauf zurückgegeben hat. Gibt der Kauf außerdem options und options_signature zurück, reich beide weiter. Dann zeigt die Seite über dem Kartenformular eine Zeile wie „Plan for Japan“ in der Sprache, die deine Anfrage verlangt hat:

JavaScript
const link = new URL('https://staging.heyatli.com/pay');
link.search = new URLSearchParams({
  type: 'payment_intent',
  sealed_secret: order.sealed_secret,
  key_id: order.key_id,
  seal_signature: order.seal_signature,
  ...(order.options && {
    options: Buffer.from(order.options).toString('base64url'),
    options_signature: order.options_signature,
  }),
}).toString();

Die Zahlungsseite zeigt den Gesamtbetrag der Bestellung an und unterstützt Kartenzahlung, Apple Pay und Google Pay. Ruf danach POST /plan/fulfill-payment mit der order_id auf und wiederhole das, bis die Bestellung bezahlt ist. Nur dieser Aufruf bestätigt die Zahlung, denn die Seite zeigt eine Zahlung, die noch verarbeitet wird, bereits als erfolgreich an.

Beim Erstellen von Zahlungslinks gelten diese Anforderungen:

  • Übergib sealed_secret, key_id, seal_signature und options_signature genau so, wie die API sie zurückgegeben hat, und URLSearchParams kümmert sich um das Encoding. options ist die Ausnahme: Kodiere es als base64url, ohne vorher am JSON etwas zu ändern. Pack nie ein client_secret im Klartext in einen Link.
  • Sandbox-Werte öffnen sich nur auf staging.heyatli.com/pay und Produktionswerte nur auf heyatli.com/pay.
  • Mit dem Link wird die Bestellung einer Person bezahlt. Schick ihn nur an die Person, der das Konto gehört, und halte ihn aus Logs heraus.
  • Speichere Links nicht für später. Ein neuer Kauf storniert die vorherige offene Bestellung samt Link.
  • brand=none blendet das Atli-Logo aus. lang und theme legen Sprache und Aussehen der Seite fest. Die Redirect-Parameter akzeptieren nur https-Adressen auf heyatli.com oder einer Subdomain davon, also sag der Person, dass sie nach dem Bezahlen in deinen Chat zurückkommen soll.
  • Der Button zum Abbrechen auf der Seite lässt die Bestellung offen. Um sie zu stornieren, ruf POST /orders/{id}/cancel auf.

Dieselbe Seite speichert auch eine Karte ohne Zahlung: Leg das Setup mit POST /user/payment-methods/setup-intent an, bau den Link mit setup_intent als type und speichere die Karte dann mit POST /user/payment-methods/confirm. Unter partners.heyatli.com/de/dev/payment-widget kannst du eine Testzahlung mit einem frischen Sandbox-Gast öffnen.

Nach der Zahlung ist eine eSIM nicht immer sofort installierbar. Frag den Bestellstatus ab, bis das Objekt esim die Installationsdaten enthält. Solange die Bestellung verarbeitet wird, zeig eine passende Statusmeldung an:

Bash
curl 'https://api-staging.heyatli.com/fulfillment/status-updates?order_id=THE_ORDER_ID' \
  -H 'Authorization: Bearer YOUR_TOKEN'
JSON
{
  "order_id": "…",
  "status": "completed",
  "esim": {
    "id": "…",
    "iccid": "…",
    "lpa_address": "…",
    "activation_code": "…",
    "qr_string": "…"
  }
}

Der Status paid bestätigt die Zahlung, und completed zeigt an, dass eSIM und zugehöriger Tarif bereitgestellt sind. Stell qr_string als QR-Code für die Installation über ein zweites Gerät dar. Wer die eSIM direkt auf dem Handy installiert, bekommt von dir die Installationslinks für iPhone oder Android. Sie öffnen die eSIM-Einrichtung des Handys:

JavaScript
const lpa = `LPA:1$${esim.lpa_address}$${esim.activation_code}`;
const carddata = encodeURIComponent(lpa);

const iphone = `https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=${carddata}`;
const android = `https://esimsetup.android.com/esim_qrcode_provisioning?carddata=${carddata}`;

Oder gib deinem Nutzer einen einzigen Link, der all das erledigt: https://heyatli.com/my/esim, wobei lpa den qr_string in base64url enthält und iccid die ICCID der eSIM. Die Seite zeigt den QR-Code, beide Ein-Tipp-Links und die Daten für die manuelle Eingabe, und mit der ICCID zeigt sie auch die Tarife und das verbleibende Datenvolumen. Ein Atli-Konto braucht es dafür nicht. Eine Sprache setzt du in den Pfad wie bei /ja/my/esim, und für eine Sandbox-eSIM nimmst du staging.heyatli.com. Wer den Link hat, kann die eSIM installieren, also schick ihn nur an die Person, die sie nutzen wird.

Was der Nutzer danach sieht, erklären unsere Ratgeber für iPhone und Android.

GET /esims listet die eSIMs des Nutzers mit ihren Installationsdaten, ihren Tarifen und dem Verbrauch zum Stand des letzten Syncs auf. POST /esims/{id}/sync fragt beim Netz aktuelle Zahlen ab. Jede Sync-Anfrage geht an den Netzbetreiber und unterliegt einem Rate-Limit. Hol aktuelle Verbrauchsdaten bei Bedarf ab, statt sie automatisch in festen Abständen abzufragen.

Anmeldung mit dem eigenen Atli-Konto

Für eine App, in der Leute ihr eigenes Atli-Konto statt eines Gastkontos nutzen, bietet Atli OAuth 2.1: den Authorization Code Flow mit PKCE (S256), rotierende Refresh-Tokens und Widerruf. Nutzer melden sich auf heyatli.com an und autorisieren dort den Zugriff, deshalb verarbeitet deine Anwendung nie ihre Atli-Passwörter.

Registriere einen Client unter partners.heyatli.com/de/dev/oauth/clients. Ein Konto kann 10 Clients besitzen: public für Handy-Apps und confidential für einen Server, der ein Secret geheim halten kann. Eine Webseite kann den Token-Aufruf nicht selbst machen, denn die API lehnt Browser-Anfragen von anderen Websites ab, solange Atli den Client nicht als vertrauenswürdig markiert hat. Gib einer Web-App deshalb einen Server und einen vertraulichen Client. Nur ein Client, der dir gehört, bekommt Tokens für die API, und für einen eigenen Client braucht dein Konto eine E-Mail-Adresse.

Hol die OAuth-Endpunkte aus den Metadaten des Autorisierungsservers, statt sie fest in den Code zu schreiben:

Bash
curl https://api.heyatli.com/.well-known/oauth-authorization-server

Access-Tokens gelten 15 Minuten. Jeder Refresh gibt ein neues Refresh-Token zurück, das im sicheren Speicher deiner Anwendung das vorherige ersetzen muss. Wer sich über deinen Client anmeldet, kann dir automatisch zugeordnet werden, sobald Atli das für dein Konto einschaltet. Bis dahin ordnest du die Leute wie in Schritt 2 selbst zu: mit POST /user/referral/redeem und ihrem Access-Token.

Teilen, Gutscheine und Gruppen

Um eine eSIM zum Teilen zu kaufen, holst du ein Angebot mit is_gift: true ein und setzt max_claims auf einen Wert zwischen 1 und 20. Sobald die Bestellung abgeschlossen ist, rufst du die claim_url über GET /gifts/sent ab. POST /rewards/voucher/redeem fügt dem Konto des Nutzers einen Gutschein hinzu. Ein Mitglied einer Atli Group kann ein Angebot mit group_id einholen und mit der Karte der Gruppe kaufen. partners.heyatli.com/de/dev/api zeigt jeden dieser Abläufe Schritt für Schritt mit Code.

FAQ

Hat die Atli-API einen API-Key?
Nein. Tokens identifizieren eine Person, keine Anwendung. Dein Server meldet jeden Nutzer mit einer Geräte-ID oder über OAuth an und ruft die API dann als dieser Nutzer auf.
Brauche ich ein eigenes Stripe-Konto?
Nein. Bestellungen werden über das Stripe-Konto von Atli belastet. Dein Formular nutzt den Publishable Key von Atli aus GET /stripe/config, und Kartendaten gehen direkt an Stripe, nie an deine Server oder an die API.
Kann die Kundschaft mit Apple Pay oder Google Pay bezahlen?
Ja. Die Zahlungsseite von Atli bietet beides an. Für ein eigenes Stripe-Formular schreib an [email protected], sobald deine Integration echte Verkäufe hat.
Wie lade ich Daten auf eine eSIM, die ein Nutzer schon hat?
Hol ein Angebot für das neue Paket mit target_esim_id für diese eSIM ein und kauf es wie gewohnt. Der Tarif kommt auf die vorhandene eSIM, es gibt also nichts neu zu installieren. Verkauft das Netz dieser eSIM das Paket nicht, lehnt die API es mit incompatible_esim ab.
Was, wenn die Zahlung durchgeht, aber mein Fulfillment-Aufruf fehlschlägt?
Belaste nicht noch einmal. Atli schließt eine bezahlte Bestellung von selbst ab, also frag GET /fulfillment/status-updates weiter ab, bis die eSIM erscheint.
Wo teste ich ohne echtes Geld?
In der Sandbox unter api-staging.heyatli.com. Bezahl dort mit der Testkarte 4242 4242 4242 4242 von Stripe, einem beliebigen Datum in der Zukunft und einer beliebigen Prüfnummer. Die Sandbox hat eigene Konten.