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.
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 membresDeux hôtes selon la clé
Utilisez le bon hôte. Un hôte incorrect est refusé avant la logique métier.
| Hôte | URL de base | Clés acceptées |
|---|---|---|
| Réel | https://api.tongkhoesim.com/v1 | tke_live_ / tke_member_live_ |
| Mode test | https://api-testing.tongkhoesim.com/v1 | tke_test_ / tke_member_test_ |
Une clé test sur hôte réel, ou l’inverse, retourne 403 partner.wrong_host avec le bon hôte. Aucun secret dans les journaux.
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
| Aspect | Réel (api, tke_live_) | Test (api-testing, tke_test_) |
|---|---|---|
| Hôte | api.tongkhoesim.com | api-testing.tongkhoesim.com — mauvais hôte : 403 |
| Portefeuille | Portefeuille réel de l’organisation | Portefeuille virtuel, recharges illimitées par tableau de bord ou administrateur |
| Stock | Vrais esim_profiles | Stock virtuel, génération illimitée d’eSIM simulées |
| Attribution | Opérateurs réels | Simulation déterministe : même entrée, mêmes ICCID/LPA (LPA:1$testmode-smdp.tongkhoesim.com$…) |
| Consommation | Mesurée chez l’opérateur | Augmentation automatique, alertes à 75/90 % |
| Webhooks | Événements réels | Événements test, déclenchement manuel et fail-next |
| Grand livre | Grand livre financier réel | Grand livre virtuel isolé, ajout seul, jamais supprimé ni mélangé au réel |
/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é
#!/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"{
"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éthode | Chemin | Usage |
|---|---|---|
| GET | /v1/testmode/status | État, checklist, compteurs clés/commandes/eSIM, portefeuille, webhook et drift |
| POST | /v1/testmode/seed | Créer les exemples, idempotent par organisation |
| POST | /v1/testmode/reset | Suppression logique des commandes/eSIM test et remise à zéro par écriture compensatoire |
| POST | /v1/testmode/esims/{order_item_id}/simulate | Simuler consommation, état, expiration, bridage et prochain refus opérateur |
| POST | /v1/testmode/webhooks/fire | Envoyer immédiatement un événement exemple ({event_type}) au webhook test |
| POST | /v1/testmode/webhooks/fail-next | Faire échouer les N prochains envois avec 503 pour tester les tentatives |
| via | Déclenchement | Contenu de ref_id |
|---|---|---|
open_api | Appel /v1 avec clé test : commande, recharge, annulation ou simulation | api_keys.id de la clé appelante |
simulate | Simulation depuis le tableau de bord par un membre ou un administrateur délégué | ID du membre ou administrateur |
seed | Données créées via /v1/testmode/seed | Vide |
/v1/testmode/esims/{id}/simulate
test-mode-onlyPOST /v1/testmode/esims/{order_item_id}/simulate modifie consommation, état, expiration, débit ou force un refus unique de recharge/annulation.
#!/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.{
"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’erreur | HTTP | Signification et solution |
|---|---|---|
testmode.live_key_forbidden | 403 | Clé réelle sur /v1/testmode/*. Utilisez une clé tke_test_ de la même organisation. |
testmode.invalid_scenario | 422 | Corps vide, aucun champ, ou état hors released/installed/enabled/disabled. |
testmode.not_test_item | 422 | order_item_id n’appartient pas à une commande test. Aucune simulation sur le réel. |
testmode.no_sellable_package | 422 | Aucun forfait avec prix pour cette organisation. La clé est créée, seul le seed échoue. |
partner.wrong_host | 403 | Mauvaise 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.