Tổng Kho eSIM — Open API đối tác · v2.4.0

Open-API-Dokumentation

Open API steht Partnern und von einem Administrator freigeschalteten Mitgliedern zur Verfügung. Ihr System ruft /v1 auf, um Kataloge anzusehen, Bestellungen zu erstellen und zu lesen, eSIM-Profile (ICCID + LPA-Installationscodes) abzurufen, Verbrauch zu verfolgen und Daten durch regelmäßige REST-Abfragen abzugleichen. Zahlungen werden vom Wallet des Schlüsselinhabers abgebucht: Organisation oder Mitglied. Webhooks sind für Organisationen bestimmt; Mitgliederpreise und Rechnungen folgen dem im OpenAPI-Mitgliederleitfaden beschriebenen Ablauf.

Alle Endpunkte ansehen Integrationsanleitung Im Browser ausprobieren

API im Überblick

30 Operationen

6 Gruppen: Katalog · Bestellungen · eSIM · Wallet · Webhooks · Testmodus.

Einheitliche Authentifizierung

HMAC-SHA256 mit 4 X-TKE-*-Headern, auch für GET. Kein Zugriff ohne Signatur.

Einheitliches Antwortformat

{ ok, data } oder { ok, error } mit passendem HTTP-Status. Fehler liefern niemals 200.

91 veröffentlichte Fehlercodes

Jeder Code nennt HTTP-Status und Wiederholbarkeit aus dem Backend-Register.

8 Webhook-Ereignisse

Konfiguration über POST /v1/webhooks, eigener Signaturschlüssel, mindestens einmalige Zustellung und Zustellprotokolle.

Testmodus mit eigenem Host

api-testing.tongkhoesim.com akzeptiert tke_test_: virtuelles Wallet, virtueller Bestand, deterministische Bereitstellung und automatischer Verbrauch. Danach zu Live-Host und tke_live_ wechseln.

text

https://api.tongkhoesim.com/v1    # Live
https://api-testing.tongkhoesim.com/v1    # Testmodus

Produktiv: api.tongkhoesim.com / tke_live_ (Partner) oder tke_member_live_ (freigeschaltete Mitglieder). Test: api-testing.tongkhoesim.com / tke_test_ / tke_member_test_ (Partner / Mitglieder).

Einstieg in 4 Schritten

1. Testschlüssel erstellen

Erstellen Sie unter Testmodus einen tke_test_-Schlüssel. Sichern Sie das einmalig angezeigte Geheimnis. Der erste Schlüssel erzeugt 3 Beispielbestellungen mit 3 Zuständen. Testguthaben ist unbegrenzt aufladbar.

2. Auf dem Test-Host bestellen

Signieren Sie per HMAC und rufen Sie POST https://api-testing.tongkhoesim.com/v1/orders auf. Mock-eSIMs (ICCID 8999) werden sofort erstellt, ohne echte Bestände oder Gelder. Nutzen Sie Konsole oder Postman.

3. Webhook registrieren und testen

Registrieren Sie Ihre URL mit POST /v1/webhooks; CHECK_HEALTH muss 2xx erhalten. Nutzen Sie /v1/testmode/webhooks/fire für Ereignisse und /fail-next für Wiederholungen.

4. Zu einem Live-Schlüssel wechseln

Erstellen Sie tke_live_ und ändern Sie Host, key_id und secret bei gleichem Code. Registrieren Sie Live-Webhooks separat; sie sind pro api_key_id isoliert.

3 kritische Integrationsfallen

Diese drei Fallen können Tests bestehen und erst bei echten Zahlungen oder beim Abgleich auffallen.

Idempotency-Key gilt pro API-Schlüssel

Deduplizierung gilt nur pro api_key_id. Derselbe Idempotency-Key mit zwei Schlüsseln erzeugt zwei Bestellungen und Abbuchungen, auch in derselben Organisation. Nutzen Sie einen stabilen Schlüssel je Ablauf oder integrieren Sie key_id.

REST nutzt id, Webhooks order_item_id

Die eSIM-id in REST entspricht order_item_id in Webhooks; order_id verweist auf die Bestellung. Speichern Sie diese UUID, nie nur die wiederverwendbare ICCID. GET /v1/esims?iccid=… liefert die id. Senden Sie external_ref beim Bestellen: REST und eSIM-Webhooks geben sie samt order_id zurück; ?external_ref=… findet alle zugehörigen eSIMs.

Cursorschleifen korrekt beenden

GET /v1/orders und /v1/esims nutzen Cursor. Ungültige Cursor beginnen ohne Fehler von vorn. Stoppen Sie bei fehlendem oder unverändertem next_cursor; nur !== null zu prüfen kann Endlosschleifen erzeugen.

Nächste Schritte

Integration

Ausführbare Beispiele, Postman, .http und Client-Generierung aus openapi.json.

HMAC-Signatur

Exakte Signaturformel und Testvektoren zur Prüfung Ihrer Implementierung.

API-Referenz

Parameter, Schemas, Antwortzweige und ausführbare Beispiele je Endpunkt.

Webhooks

Ereigniskatalog, Signaturprüfung, Wiederholungen und REST-Abgleich.