Tổng Kho eSIM · Open-API-Dokumentation

Integration

Kein offizielles Paket nötig. Nutzen Sie Signatur, ausführbare Beispiele und Testsammlungen, um Antworten vor der Implementierung kennenzulernen.

OpenAPI für Mitglieder

Integrieren Sie direkt mit einem Mitgliedskonto, ohne eine Organisation oder ein vietnamesisches Unternehmensprofil anzulegen.

Ein Administrator schaltet OpenAPI pro Mitglied frei. API-Schlüssel in der Hauptseitenleiste öffnen, Live oder Test wählen und einen Schlüssel erstellen; das Secret erscheint einmal. Beide Modi teilen sich das Schlüssellimit. Eine Sperre blockiert beide Modi, Widerrufen bleibt möglich.

Live nutzt das echte VND-Guthaben des Mitglieds ohne Kredit. Test verwendet ein separates virtuelles Wallet und simulierte eSIMs. Dort lassen sich Testguthaben und Beispieldaten erstellen oder zurücksetzen. Testbestellungen erscheinen nicht im echten Kaufverlauf.

Ein privater Paketpreis des Mitglieds ist endgültig, ohne zusätzlichen Rangrabatt. Ohne privaten Paketpreis gelten der aktuelle Listenpreis und Rangrabatt. Der Server legt den Preis bei der Bestellung fest.

Rechnungen folgen dem Mitgliederablauf: standardmäßig ein Verkauf an Verbraucher. Bei der Bestellung können Sie invoice_buyer mit gültigen persönlichen Daten gemäß den aktuellen Prüfregeln angeben. Ein vietnamesisches Unternehmensprofil ist für OpenAPI nicht erforderlich.

Authentifizierung und Vermeidung von Duplikaten

Live: https://api.tongkhoesim.com mit tke_member_live_. Test: https://api-testing.tongkhoesim.com mit tke_member_test_. Beide nutzen HMAC-SHA256 und X-TKE-Key, X-TKE-Timestamp, X-TKE-Nonce, X-TKE-Signature. Methode, Pfad/Query und Hash des unveränderten Bodys exakt signieren; keine Secrets im Browsercode.

POST-Anfragen für Bestellungen, Tarifwechsel, Stornierung oder Erstattungsanträge benötigen Idempotency-Key. Behalten Sie bei Wiederholung derselben Absicht Schlüssel und Body bei; die Duplikaterkennung gilt pro API-Schlüssel. Wechseln Sie daher nicht den API-Schlüssel, um eine ausstehende Transaktion zu wiederholen. Beispieldaten und Reset für Mitglieder benötigen ebenfalls Idempotency-Key; Reset muss einen {reason}-Body enthalten.

Geben Sie lpa in include an, um Installationscodes zu erhalten; das normale Stornierungsfenster schließt, wenn tatsächlich Codes zurückgegeben werden. qr ergänzt nur zusammen mit lpa ein QR-Bild und wird bei Listen-Endpunkten ignoriert. Fordern Sie Codes erst zur Auslieferung an; lassen Sie include sonst weg. Erstattungsanträge unterliegen weiterhin den Geschäftsregeln und sind nach der Codefreigabe keine freie Stornierungsmöglichkeit.

API-Endpunkte für Mitglieder

API-Pfad: GET /v1/catalog/packages: Erforderliche Berechtigung: catalog:read
API-Pfad: GET /v1/catalog/packages/{code}: Erforderliche Berechtigung: catalog:read
API-Pfad: GET /v1/orders: Erforderliche Berechtigung: orders:read
API-Pfad: POST /v1/orders: Erforderliche Berechtigung: orders:write
API-Pfad: GET /v1/orders/{id}: Erforderliche Berechtigung: orders:read
API-Pfad: POST /v1/orders/{id}/resend: Erforderliche Berechtigung: orders:write
API-Pfad: GET /v1/esims: Erforderliche Berechtigung: esims:read
API-Pfad: GET /v1/esims/{id}: Erforderliche Berechtigung: esims:read
API-Pfad: GET /v1/esims/{id}/usage: Erforderliche Berechtigung: esims:read
API-Pfad: GET /v1/esims/{id}/plan-options: Erforderliche Berechtigung: esims:read
API-Pfad: POST /v1/esims/{id}/change-plan: Erforderliche Berechtigung: esims:write
API-Pfad: POST /v1/esims/{id}/cancel: Erforderliche Berechtigung: esims:write
API-Pfad: GET /v1/esims/{id}/refund-requests: Erforderliche Berechtigung: esims:read
API-Pfad: POST /v1/esims/{id}/refund-requests: Erforderliche Berechtigung: esims:write
API-Pfad: GET /v1/wallet/balance: Erforderliche Berechtigung: wallet:read

Testmodus

GET /v1/testmode/status: esims:read
POST /v1/testmode/seed: orders:write
POST /v1/testmode/reset: orders:write
POST /v1/testmode/esims/{id}/simulate: esims:write

Sammelbestellungen und Webhooks werden für Mitglieder in beiden Modi nicht unterstützt. Erstattungsanträge mit Prüfung sind nur live möglich; eine Test-eSIM stornieren, um eine virtuelle Erstattung zu testen. Test ruft keine echten Anbieter auf und erstellt keine echten MISA-Rechnungen. Nicht unterstützte Aktionen liefern capability.not_supported.

Die Konsole akzeptiert Partner-Testschlüssel tke_test_ und Mitglied-Testschlüssel tke_member_test_ nur auf api-testing. Alle Live-Schlüssel werden blockiert. Secrets bleiben im Seitenspeicher und werden nie dauerhaft oder in Logs gespeichert.

Anfragen signieren

Die HMAC-Seite enthält Formel, Beispiele für bash/Node/Python/PHP/Go und Backend-Testvektoren.

bash

#!/usr/bin/env bash
# Yeu cau: openssl. Ky POST /v1/orders.
KEY_ID="tke_test_ab12cd34..."
SECRET="tke_secret_test_0123456789abcdef"
METHOD="POST"
PATH_Q="/v1/orders"
BODY='{"items":[{"package_code":"THAY-BANG-MA-GOI-CUA-BAN","quantity":2}]}'
TS="$(date +%s000)"                 # epoch milliseconds
NONCE="$(uuidgen)"

BODY_HASH="$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | awk '{print $NF}')"
SIGNING="$METHOD"$'
'"$PATH_Q"$'
'"$TS"$'
'"$NONCE"$'
'"$BODY_HASH"
SIG="$(printf '%s' "$SIGNING" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $NF}')"

curl -sS "https://api.tongkhoesim.com$PATH_Q"   -H "X-TKE-Key: $KEY_ID"   -H "X-TKE-Timestamp: $TS"   -H "X-TKE-Nonce: $NONCE"   -H "X-TKE-Signature: $SIG"   -H "Idempotency-Key: $(uuidgen)"   -H "Content-Type: application/json"   --data-raw "$BODY"

HMAC-Signatur ansehen

Ausführbare Beispieldateien

examples/sign.mjs und examples/sign.py laufen mit der Standardlaufzeit ohne Pakete. Sie lesen /hmac-test-vectors.json, berechnen Signaturen und zeigen PASS/FAIL.

bash

node examples/sign.mjs      # plain Node (node:crypto), nothing to install
python examples/sign.py     # plain Python (hmac/hashlib), nothing to install

Zum Testen nur tke_test_ verwenden. Niemals Live-Schlüssel in diese Dateien einfügen.

Sofort nutzbare Sammlungen

Postman und .http werden bei jedem Build aus openapi.json generiert. Jeder Endpunkt hat eine Anfrage mit 4 Signatur-Headern. Schlüssel ergänzen und Signatur berechnen.

Postman-Sammlung herunterladen tongkhoesim.http herunterladen

Die .http-Sammlung verwenden

tongkhoesim.http in VS Code mit REST Client oder JetBrains HTTP Client öffnen.
@key_id und @secret mit tke_test_ ausfüllen. @base_url zeigt auf api-testing.tongkhoesim.com.
timestamp/nonce/signature mit den HMAC-Beispielen oder examples/sign.* berechnen und in die Variablen einfügen.
Anfragen direkt im Editor senden, ohne Postman oder zusätzlichen Code.

Sie möchten ein SDK?

Client mit openapi-generator aus openapi.json generieren, um der Spezifikation zu folgen.

bash

npx @openapitools/openapi-generator-cli generate \
  -i https://docs.tongkhoesim.com/openapi.json \
  -g typescript-fetch \
  -o ./tke-sdk