Tổng Kho eSIM
Environnement de test

Mode test

Utilisez les clés partenaire tke_test_ ou membre tke_member_test_ sur api-testing.tongkhoesim.com. Les fonds virtuels et eSIM simulées sont séparés de l’argent, du stock et des factures réels. Les opérations dépendent du propriétaire ; consultez les limites membre pour les commandes groupées, webhooks et demandes de remboursement.

Testez tout le flux avant le réel. Consultez Signature HMAC pour l’authentification et Console de test pour envoyer depuis le navigateur.

OpenAPI pour les membres

L’administrateur accorde OpenAPI par membre. Ouvrez Clés API dans la barre latérale, choisissez Réel ou Test, puis créez une clé ; le secret apparaît une seule fois. Les deux modes partagent la limite de clés. La désactivation bloque les deux modes mais permet la révocation.

Le mode réel utilise le portefeuille VND du membre, sans crédit. Le test utilise un portefeuille virtuel séparé et des eSIM simulées. Ajoutez des fonds, créez ou réinitialisez des exemples dans le mode test. Les commandes de test ne figurent pas dans l’historique réel.

Les commandes groupées et webhooks ne sont pas disponibles pour les membres. Les demandes de remboursement à examiner sont réservées au réel ; annulez une eSIM de test pour essayer un remboursement virtuel. Le test n’appelle aucun fournisseur réel et n’émet aucune facture MISA réelle. Les opérations non disponibles renvoient capability.not_supported.

Points d’accès API des membres

Deux hôtes selon la clé

Utilisez le bon hôte. Un hôte incorrect est refusé avant la logique métier.

HôteURL de baseClés acceptées
Réelhttps://api.tongkhoesim.com/v1tke_live_ / tke_member_live_
Mode testhttps://api-testing.tongkhoesim.com/v1tke_test_ / tke_member_test_

Créer une clé test

Dans Mode test du tableau de bord, créez tke_test_ et sauvegardez le secret affiché une seule fois. La première clé lance automatiquement POST /v1/testmode/seed.

7 différences entre réel et test

AspectRéel (api, tke_live_)Test (api-testing, tke_test_)
Hôteapi.tongkhoesim.comapi-testing.tongkhoesim.com — mauvais hôte : 403
PortefeuillePortefeuille réel de l’organisationPortefeuille virtuel, recharges illimitées par tableau de bord ou administrateur
StockVrais esim_profilesStock virtuel, génération illimitée d’eSIM simulées
AttributionOpérateurs réelsSimulation déterministe : même entrée, mêmes ICCID/LPA (LPA:1$testmode-smdp.tongkhoesim.com$…)
ConsommationMesurée chez l’opérateurAugmentation automatique, alertes à 75/90 %
WebhooksÉvénements réelsÉvénements test, déclenchement manuel et fail-next
Grand livreGrand livre financier réelGrand livre virtuel isolé, ajout seul, jamais supprimé ni mélangé au réel
POST

/v1/testmode/seed

POST /v1/testmode/seed crée un jeu prêt à tester. Idempotent par organisation : les appels suivants retournent already_seeded: true sans doublons.

  • Portefeuille test suffisamment crédité
  • 3 commandes d’une eSIM sur 3 forfaits au prix de votre organisation
  • 3 états : non installé · actif à 40 % · expiré
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
  }
}

Consommation automatique (drift)

Les eSIM test activées accumulent de la consommation (toutes les 5 min par défaut) jusqu’à épuisement ou expiration. esim.usage_threshold est émis à 75 % et 90 %. GET /v1/testmode/status expose l’état et l’intervalle.

Endpoints /v1/testmode/*

Uniquement api-testing.tongkhoesim.com avec tke_test_. Aucun alias d’ancien chemin.

MéthodeCheminUsage
GET/v1/testmode/statusÉtat, checklist, compteurs clés/commandes/eSIM, portefeuille, webhook et drift
POST/v1/testmode/seedCréer les exemples, idempotent par organisation
POST/v1/testmode/resetSuppression logique des commandes/eSIM test et remise à zéro par écriture compensatoire
POST/v1/testmode/esims/{order_item_id}/simulateSimuler consommation, état, expiration, bridage et prochain refus opérateur
POST/v1/testmode/webhooks/fireEnvoyer immédiatement un événement exemple ({event_type}) au webhook test
POST/v1/testmode/webhooks/fail-nextFaire échouer les N prochains envois avec 503 pour tester les tentatives
Sources d’audit des transitions (via)
viaDéclenchementContenu de ref_id
open_apiAppel /v1 avec clé test : commande, recharge, annulation ou simulationapi_keys.id de la clé appelante
simulateSimulation depuis le tableau de bord par un membre ou un administrateur déléguéID du membre ou administrateur
seedDonnées créées via /v1/testmode/seedVide
POST

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

test-mode-only

POST /v1/testmode/esims/{order_item_id}/simulate modifie consommation, état, expiration, débit ou force un refus unique de recharge/annulation.

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"
  }
}

Erreurs du mode test

Code d’erreurHTTPSignification et solution
testmode.live_key_forbidden403Clé réelle sur /v1/testmode/*. Utilisez une clé tke_test_ de la même organisation.
testmode.invalid_scenario422Corps vide, aucun champ, ou état hors released/installed/enabled/disabled.
testmode.not_test_item422order_item_id n’appartient pas à une commande test. Aucune simulation sur le réel.
testmode.no_sellable_package422Aucun forfait avec prix pour cette organisation. La clé est créée, seul le seed échoue.
partner.wrong_host403Mauvaise association clé/hôte. Utilisez l’hôte indiqué dans la réponse.

Catalogue complet sur la page des erreurs . Les contrôles /v1 d’authentification précèdent le mode test.

Webhooks test : fire et fail-next

POST /v1/testmode/webhooks/fire envoie un événement sans commande réelle. Corps : { "event_type": "order.completed", "data": {...} }. Sans data, un exemple est généré.

POST /v1/testmode/webhooks/fail-next { "count": 1 } force N échecs 503 puis se désactive, sans couper votre récepteur.