Tổng Kho eSIM
Testumgebung

Testmodus

Partner nutzen tke_test_, Mitglieder tke_member_test_ auf api-testing.tongkhoesim.com. Virtuelles Guthaben und simulierte eSIMs sind von echtem Geld, Bestand und Rechnungen getrennt. Der Funktionsumfang hängt vom Schlüsselinhaber ab; Mitglieder beachten die Grenzen für Sammelbestellungen, Webhooks und Erstattungsanträge.

Vor echten Zahlungen den gesamten Ablauf testen. Siehe HMAC-Signatur für Authentifizierung und Testkonsole zum direkten Senden im Browser.

OpenAPI für Mitglieder

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.

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.

API-Endpunkte für Mitglieder

Zwei Hosts je nach Schlüssel

Richtigen Host nutzen. Ein falscher Host wird vor der Geschäftslogik abgewiesen.

HostBasis-URLAkzeptierte Schlüssel
Livehttps://api.tongkhoesim.com/v1tke_live_ / tke_member_live_
Testmodushttps://api-testing.tongkhoesim.com/v1tke_test_ / tke_member_test_

Testschlüssel erstellen

Im Dashboard unter Testmodus tke_test_ erstellen und das einmalig angezeigte Geheimnis sichern. Der erste Schlüssel führt automatisch POST /v1/testmode/seed aus.

7 Unterschiede zwischen Live und Test

AspektLive (api, tke_live_)Test (api-testing, tke_test_)
Hostapi.tongkhoesim.comapi-testing.tongkhoesim.com — falscher Host: 403
WalletEchtes Organisations-WalletVirtuelles Wallet, unbegrenzt über Dashboard oder Admin aufladbar
BestandEchte esim_profilesVirtueller Bestand, unbegrenzt simulierte eSIMs
BereitstellungEchte MobilfunkanbieterDeterministischer Mock: gleiche Eingaben, gleiche ICCID/LPA (LPA:1$testmode-smdp.tongkhoesim.com$…)
VerbrauchEcht beim Anbieter gemessenAutomatischer Anstieg, Warnungen bei 75/90 %
WebhooksEchte Live-EreignisseTestereignisse, manuelles Auslösen und fail-next
HauptbuchEchtes FinanzhauptbuchIsoliertes virtuelles Hauptbuch, nur ergänzbar, nie gelöscht oder mit Live vermischt
POST

/v1/testmode/seed

POST /v1/testmode/seed erzeugt sofort nutzbare Beispieldaten. Pro Organisation idempotent: weitere Aufrufe liefern already_seeded: true ohne Duplikate.

  • Test-Wallet mit ausreichend Guthaben
  • 3 Bestellungen mit je 1 eSIM aus 3 Tarifen zum Organisationspreis
  • 3 Zustände: nicht installiert · 40 % verbraucht · abgelaufen
bash
#!/usr/bin/env bash
# Requires: bash + openssl + uuidgen.

KEY_ID="tke_test_REPLACE_WITH_YOUR_KEY_ID"
SECRET="REPLACE_WITH_YOUR_SECRET"

METHOD="POST"
REQ_PATH="/v1/testmode/seed"
BODY='{}'

TS="$(date +%s000)"                 # epoch milliseconds
NONCE="$(uuidgen)"
BODY_HASH="$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | awk '{print $NF}')"
SIGNING="$METHOD"$'\n'"$REQ_PATH"$'\n'"$TS"$'\n'"$NONCE"$'\n'"$BODY_HASH"
SIG="$(printf '%s' "$SIGNING" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $NF}')"

curl -sS -X "$METHOD" "https://api-testing.tongkhoesim.com$REQ_PATH" \
  -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"
json
{
  "ok": true,
  "data": {
    "seeded": true,
    "already_seeded": false,
    "orders_created": 3,
    "esims_created": 3
  }
}

Automatischer Verbrauch (Drift)

Aktivierte Test-eSIMs sammeln automatisch Verbrauch (Standard 5 Min.) bis Ende oder Ablauf. Bei 75 % und 90 % folgt esim.usage_threshold. GET /v1/testmode/status zeigt Status und Intervall.

/v1/testmode/*-Endpunkte

Nur api-testing.tongkhoesim.com mit tke_test_. Keine alten Pfad-Aliasse.

MethodePfadZweck
GET/v1/testmode/statusStatus, Checkliste, Schlüssel-/Bestell-/eSIM-Zahlen, Wallet, Webhook und Drift
POST/v1/testmode/seedBeispieldaten pro Organisation idempotent erstellen
POST/v1/testmode/resetTestbestellungen/eSIMs weich löschen, Wallet per Gegenbuchung auf null setzen
POST/v1/testmode/esims/{order_item_id}/simulateVerbrauch, Zustand, Ablauf, Drosselung und nächste Anbieterablehnung simulieren
POST/v1/testmode/webhooks/fireBeispielereignis ({event_type}) sofort an den Test-Webhook senden
POST/v1/testmode/webhooks/fail-nextDie nächsten N Zustellungen mit 503 fehlschlagen lassen, um Wiederholungen zu testen
Quellen der Zustandsänderungen (via)
viaAuslöserBedeutung von ref_id
open_api/v1-Aufruf mit Testschlüssel: Bestellung, Aufladung, Storno oder Simulationapi_keys.id des aufrufenden Schlüssels
simulateDashboard-Simulation durch Mitglied oder vertretenden AdminBenutzer-ID des Mitglieds oder Admins
seedDaten durch /v1/testmode/seed erstelltLeer
POST

/v1/testmode/esims/{id}/simulate

test-mode-only

POST /v1/testmode/esims/{order_item_id}/simulate ändert Verbrauch, Zustand, Ablauf oder Bandbreite und erzwingt einmalige Ablehnung von Aufladung/Storno.

bash
#!/usr/bin/env bash
KEY_ID="tke_test_REPLACE_WITH_YOUR_KEY_ID"
SECRET="REPLACE_WITH_YOUR_SECRET"
ORDER_ITEM_ID="REPLACE_WITH_ORDER_ITEM_ID"

METHOD="POST"
REQ_PATH="/v1/testmode/esims/$ORDER_ITEM_ID/simulate"
BODY='{"data_used_mb":4096,"status":"enabled"}'

TS="$(date +%s000)"
NONCE="$(uuidgen)"
BODY_HASH="$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | awk '{print $NF}')"
SIGNING="$METHOD"$'\n'"$REQ_PATH"$'\n'"$TS"$'\n'"$NONCE"$'\n'"$BODY_HASH"
SIG="$(printf '%s' "$SIGNING" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $NF}')"

curl -sS -X "$METHOD" "https://api-testing.tongkhoesim.com$REQ_PATH" \
  -H "X-TKE-Key: $KEY_ID" \
  -H "X-TKE-Timestamp: $TS" \
  -H "X-TKE-Nonce: $NONCE" \
  -H "X-TKE-Signature: $SIG" \
  -H "Content-Type: application/json" \
  --data-raw "$BODY"
# No Idempotency-Key required: state mutation is intrinsically idempotent.
json
{
  "ok": true,
  "data": {
    "order_item_id": "018f2b00-0000-7000-8000-000000000001",
    "esim_state": "enabled",
    "running_package_code": "TKE-VN-30D-X3K9F",
    "running_started_at": "2026-07-11T07:00:00Z",
    "running_expires_at": "2026-08-10T07:00:00Z",
    "data_bytes": 5368709120,
    "used_bytes": 4294967296,
    "remaining_bytes": 1073741824,
    "throttled": false,
    "via": "simulate",
    "last_via": "simulate",
    "mode": "test",
    "updated_at": "2026-07-11T09:15:00Z"
  }
}

Fehlercodes im Testmodus

FehlercodeHTTPBedeutung und Lösung
testmode.live_key_forbidden403Live-Schlüssel auf /v1/testmode/*. tke_test_ derselben Organisation verwenden.
testmode.invalid_scenario422Body leer, keine Felder oder Zustand außerhalb released/installed/enabled/disabled.
testmode.not_test_item422order_item_id gehört nicht zu einer Testbestellung. Keine Simulation auf Live-Daten.
testmode.no_sellable_package422Kein bepreister Tarif für diese Organisation. Schlüssel erstellt, nur Seed fehlgeschlagen.
partner.wrong_host403Falsche Schlüssel-/Host-Kombination. Den in der Antwort genannten Host nutzen.

Vollständiger Katalog auf der Fehlercodeseite . Die üblichen /v1 Authentifizierungsprüfungen laufen vor der Testlogik.

Test-Webhooks: fire und fail-next

POST /v1/testmode/webhooks/fire sendet ein Ereignis ohne echte Bestellung. Body: { "event_type": "order.completed", "data": {...} }. Ohne data wird ein Beispiel erzeugt.

POST /v1/testmode/webhooks/fail-next { "count": 1 } erzwingt N Fehler mit 503 und deaktiviert sich danach, ohne den Empfänger abzuschalten.