Die eSIM-API integrieren

Verwenden Sie die eSIM-API, um Datenpakete zu kaufen und Installationsdetails aus Ihrer Anwendung bereitzustellen. Sie benötigen einen Workspace, einen API-Schlüssel und Guthaben in der Organisations-Wallet für Live-Käufe. Folgen Sie der Authentifizierung und verwenden Sie die API-Region, die zu Ihrem Schlüssel passt.

Geben Sie dem Schlüssel esim:read, um Angebote und Ressourcen einzusehen, und esim:write, um Dienste zu kaufen oder zu verwalten. Installationszugangsdaten haben eigene Berechtigungen: esim_credentials:read zum Abrufen und esim_credentials:write zum Erstellen oder Senden von Installationslinks. Bewahren Sie den API-Schlüssel in Ihrer Serveranwendung auf.

1. Angebot auswählen

Listen Sie Angebote auf für das Reiseziel und rufen Sie dann das gewählte Angebot ab. Prüfen Sie zone.countries, das Datenvolumen und die Gültigkeit in pricing, Geschwindigkeitsbedingungen und enthaltene Telefondienste. Verwenden Sie für eine vorhandene eSIM Kompatible Angebote auflisten; die allgemeine Katalogverfügbarkeit bestätigt keine Top-up-Kompatibilität.

Rufen Sie die Identifikationsanforderungen des Angebots ab, bevor Sie Teilnehmerinformationen erfassen. Die Antwort enthält ein JSON-Schema für jedes Abdeckungsland mit Pflichtfeldern für Vorname, Nachname und E-Mail sowie weiteren Feldern. Aktivieren Sie die Validierung von E-Mail- und Datumsformaten. Sie erfassen und validieren diese Informationen; die eSIM-API empfängt oder überprüft die Angaben nicht, und eine erfolgreiche Validierung autorisiert keinen Kauf.

Rufen Sie für eine neue eSIM die Checkout-Optionen ab. Zeigen Sie den zurückgegebenen Einmalpreis oder das verfügbare wiederkehrende Angebot an, bevor Sie den Kauf bestätigen. Checkout-Preise verstehen sich ohne Steuern. Verlängerungen haben eigene Preise und Intervalle; folgen Sie Wiederkehrende Pakete, wenn der Kunde sich dafür entscheidet.

Installieren Sie für das folgende Einmalbeispiel curl und jq. Setzen Sie BIRD_API_URL auf Ihre regionale Basis-URL, BIRD_API_KEY auf Ihren Schlüssel und ESIM_OFFER_ID auf die gewählte Angebots-ID:

Codebeispiel

curl --fail-with-body --silent --show-error \
  "$BIRD_API_URL/v1/esim/offers/$ESIM_OFFER_ID/checkout" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  > esim-checkout.json

jq '.one_time' esim-checkout.json

Prüfen Sie Preis und Angebotsbedingungen, bevor Sie fortfahren. Das Angebot reserviert keine Verfügbarkeit.

2. Kauf erstellen

Erstellen Sie eine Bestellung mit offer_id. Lassen Sie esim_id für ein neues Profil weg; geben Sie es für ein Top-up an. Senden Sie bei einem Einmalkauf offer_revision und expected_price aus dem akzeptierten Angebot. Diese Felder lehnen geänderte Bedingungen mit 409 ab, bevor eine Belastung erfolgt; rufen Sie ein neues Angebot ab und prüfen Sie es, bevor Sie einen geänderten Preis akzeptieren.

Setzen Sie ESIM_ORDER_KEY auf einen eindeutigen Wert für diesen Kauf und speichern Sie ihn zusammen mit der Anfrage. Dieses Beispiel kauft eine neue, nicht zugewiesene eSIM und übernimmt den veröffentlichten Preis ohne Änderung von Betrag oder Währung:

Codebeispiel

jq '{offer_id, offer_revision: .one_time.offer_revision, expected_price: .one_time.price}' \
  esim-checkout.json > esim-order.json

curl --fail-with-body --silent --show-error \
  "$BIRD_API_URL/v1/esim/orders" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $ESIM_ORDER_KEY" \
  --data-binary @esim-order.json

Um ein neues Profil nach Abschluss der Bereitstellung zuzuweisen, geben Sie einen Workspace-subscriber_id an; folgen Sie dem Teilnehmer-Setup. Ein Top-up behält die bestehende Zuweisung bei, lassen Sie daher subscriber_id beim Senden von esim_id weg. Senden Sie Installationsdetails separat nach der Bereitstellung.

Speichern Sie die zurückgegebene Bestell-ID. Prüfen Sie status auch nach HTTP 201, da die Antwort eine abgeschlossene oder fehlgeschlagene Bestellung enthalten kann. HTTP 202 bedeutet, dass die Verarbeitung fortgesetzt wird. Rufen Sie die Bestellung ab, bis sie completed oder failed ist. Eine abgeschlossene Bestellung identifiziert esim_id und package_id; die Geräteinstallation bleibt ein separater Schritt.

3. Installationsdetails bereitstellen

Lesen Sie nach dem Kauf die Installationszugangsdaten, erstellen Sie einen gehosteten Installationslink oder senden Sie einen Link per E-Mail oder SMS. Halten Sie Aktivierungsdetails und Installationslinks aus Analyse-Tools und öffentlichen Logs heraus.

Speichern Sie bei einem gesendeten Link die Zustellungs-ID und prüfen Sie den Zustellverlauf. Eine 202-Antwort bestätigt die Annahme zum Versand; delivered bestätigt die Nachrichtenzustellung, und die Geräteinstallation erfordert eine eigene Prüfung. Folgen Sie der Installationsanleitung für unterstützte Methoden, Link-Ablauf und Wiederherstellung.

4. Unterbrochenen Kauf wiederherstellen

Falls die Erstellungsantwort verloren ging oder 503 zurückgab, wiederholen Sie die gespeicherte Anfrage mit dem ursprünglichen Idempotency-Key; siehe Idempotente Anfragen. Falls Sie die Bestell-ID haben, lesen Sie zuerst diese Bestellung. Ein weiterer Kauf bei unbekanntem Ergebnis kann eine zusätzliche Belastung verursachen.

Prüfen Sie bei einer Bestellung in charging den Wert funding und Ihr Wallet-Guthaben. funding.required_amount ist der benötigte Gesamtbetrag inklusive Steuer; vergleichen Sie ihn mit dem vorhandenen Guthaben, bevor Sie Geld hinzufügen. Einmalkäufe wiederholen die Finanzierung automatisch. Wird ein erstmaliger wiederkehrender Kauf wegen unzureichendem Guthaben abgelehnt, laden Sie Guthaben auf und wiederholen Sie dieselbe Erstellungsanfrage explizit mit dem ursprünglichen Schlüssel.

Prüfen Sie den aktuellen Bestellstatus auch nach funding.lapses_at: Dieser Zeitstempel garantiert keine Stornierung. Eine Bestellung kann trotzdem abgeschlossen werden, wenn sie Guthaben erhält, bevor ein weiterer Versuch wegen unzureichender Mittel fehlschlägt.

Um einen unerwünschten, nicht finanzierten Kauf zu stoppen, stornieren Sie die Bestellung. Eine erfolgreiche nicht finanzierte Stornierung gibt status: failed und failure_code: canceled zurück. Eine finanzierte Einmalbestellung gibt 409 zurück und läuft weiter. Bei einem erstmaligen wiederkehrenden Kauf kann eine während der Stornierung eingegangene Zahlung dazu führen, dass der bezahlte Kauf fortgesetzt wird, während die zukünftige Verlängerung endet. Prüfen Sie die zurückgegebene Bestellung und das Abonnement, bevor Sie eine Stornierung oder Erstattung melden.

Prüfen Sie bei einem fehlgeschlagenen Kauf failure_code und failure_reason. Jede Belastung wird automatisch gutgeschrieben; refund_transaction_id identifiziert eine ausgestellte Gutschrift. Bewahren Sie die Bestell-ID für den Support auf, falls Zahlung, Zustellung oder Gutschrift ungeklärt bleiben.

5. Guthaben und Servicestatus anzeigen

eSIM abrufen für Status, Installationszustand, Pakete und available_actions. Zeigen Sie Kontingent, Verbrauch und Beobachtungszeitpunkt des Pakets mithilfe der Nutzungsanleitung an. Unbekannter Verbrauch muss in Ihrer Anwendung als unbekannt dargestellt werden.

Prüfen Sie die Aktionsverfügbarkeit erneut, wenn der Kunde handelt; die Operation prüft Berechtigungen und Zustand noch einmal. Verwenden Sie die Betriebsanleitung, um unvollständige Käufe, Installationsprobleme oder Verbindungsfehler zu untersuchen.

Nächste Schritte

Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema.

Implementierungs-Briefing erhalten