Tổng Kho eSIM · Documentation Open API

Intégration

Aucun package officiel à installer. Commencez avec la signature, les exemples exécutables et les collections de test pour découvrir les réponses avant de coder.

OpenAPI pour les membres

Intégrez directement avec un compte membre, sans créer d’organisation ni de profil de personne morale vietnamienne.

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.

Le prix privé d’un forfait membre est définitif, sans remise de niveau supplémentaire. Sans prix privé, le prix catalogue et la remise de niveau actuels s’appliquent. Le serveur fixe le prix lors de la commande.

Les factures suivent le parcours membre : vente au consommateur par défaut. À la création d’une commande, invoice_buyer peut contenir des coordonnées individuelles valides selon les règles actuelles. Aucun profil de personne morale vietnamienne n’est requis pour accéder à OpenAPI.

Authentification et prévention des doublons

Réel : https://api.tongkhoesim.com avec tke_member_live_. Test : https://api-testing.tongkhoesim.com avec tke_member_test_. Les deux utilisent HMAC-SHA256 et X-TKE-Key, X-TKE-Timestamp, X-TKE-Nonce, X-TKE-Signature. Signez exactement méthode, chemin/requête et hash du corps brut ; aucun secret dans le code navigateur.

Les POST de création de commande, changement de forfait, annulation ou demande de remboursement exigent Idempotency-Key. Conservez la même clé et le même corps pour réessayer une intention ; la déduplication est limitée à la clé API, donc ne changez pas de clé API pour réessayer une transaction en attente. La création et la réinitialisation des exemples membre exigent aussi Idempotency-Key ; reset doit inclure un corps {reason}.

Ajoutez lpa dans include pour recevoir les codes d’installation ; la fenêtre d’annulation normale se ferme lorsque les codes sont effectivement renvoyés. qr ajoute uniquement une image QR avec lpa et est ignoré sur les endpoints de liste. Demandez les codes uniquement quand la livraison est prête ; omettez include sinon. Les demandes de remboursement restent soumises aux règles métier et ne constituent pas une annulation libre après divulgation.

Points d’accès API des membres

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

Mode test

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

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.

La console accepte les clés de test partenaire tke_test_ et membre tke_member_test_ uniquement sur api-testing. Toutes les clés réelles sont bloquées. Les secrets restent en mémoire de la page, jamais dans le stockage ni les journaux.

Signer les requêtes

La page HMAC contient la formule, les exemples bash/Node/Python/PHP/Go et les vecteurs générés par le backend.

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"

Voir la signature HMAC

Exemples exécutables

examples/sign.mjs et examples/sign.py fonctionnent avec le runtime standard, sans package. Ils lisent /hmac-test-vectors.json, calculent chaque signature et affichent 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

Utilisez seulement tke_test_ pour tester l’API. Ne collez jamais de clé réelle dans ces fichiers.

Collections prêtes à exécuter

Postman et .http sont générés directement depuis openapi.json à chaque build. Chaque endpoint possède une requête avec les 4 headers de signature : ajoutez votre clé et calculez la signature.

Télécharger Postman Télécharger tongkhoesim.http

Utiliser la collection .http

Ouvrez tongkhoesim.http dans VS Code avec REST Client ou JetBrains HTTP Client.
Renseignez @key_id et @secret avec tke_test_. @base_url pointe déjà vers api-testing.tongkhoesim.com.
Calculez timestamp/nonce/signature avec les exemples HMAC ou examples/sign.*, puis copiez-les dans les variables.
Envoyez les requêtes depuis l’éditeur, sans Postman ni code supplémentaire.

Vous souhaitez un SDK ?

Générez votre client depuis openapi.json avec openapi-generator pour suivre la spécification.

bash

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