Tổng Kho eSIM — Open API đối tác · v2.4.0

Documentation Open API

Open API s’adresse aux partenaires et aux membres autorisés par un administrateur. Votre système appelle /v1 pour consulter le catalogue, créer et lire les commandes, récupérer les profils eSIM (ICCID + codes LPA), suivre la consommation et rapprocher les données par interrogation REST périodique. Les paiements sont débités du portefeuille du propriétaire de la clé : organisation ou membre. Les webhooks sont réservés aux organisations ; les prix et factures membres suivent le parcours membre présenté dans le guide d’intégration OpenAPI.

Voir tous les endpoints Guide d’intégration Tester dans le navigateur

L’API en un coup d’œil

30 opérations

6 groupes : Catalogue · Commandes · eSIM · Portefeuille · Webhooks · Mode test.

Authentification unifiée

HMAC-SHA256 avec 4 headers X-TKE-*, y compris pour GET. Aucun accès sans signature.

Enveloppe unique

{ ok, data } ou { ok, error }, avec un statut HTTP adapté. Jamais 200 pour une erreur.

91 codes d’erreur publiés

Chaque code indique le statut HTTP et si une nouvelle tentative est possible, depuis le registre backend.

8 événements webhook

Configuration via POST /v1/webhooks, secret dédié, livraison au moins une fois et journaux pour le renvoi.

Mode test sur hôte dédié

api-testing.tongkhoesim.com accepte tke_test_ : portefeuille et stock virtuels, attribution déterministe et consommation automatique. Passez ensuite au host réel avec tke_live_.

text

https://api.tongkhoesim.com/v1    # Réel
https://api-testing.tongkhoesim.com/v1    # Mode test

Réel : api.tongkhoesim.com / tke_live_ (partenaires) ou tke_member_live_ (membres autorisés). Test : api-testing.tongkhoesim.com / tke_test_ / tke_member_test_ (partenaires / membres).

Démarrage en 4 étapes

1. Créer une clé de test

Créez une clé tke_test_ dans Mode test. Sauvegardez le secret affiché une seule fois. La première clé génère 3 commandes de démonstration dans 3 états. Le portefeuille test est rechargeable sans limite.

2. Commander sur l’hôte test

Signez avec HMAC et appelez POST https://api-testing.tongkhoesim.com/v1/orders. Les eSIM simulées (ICCID 8999) sont immédiates, sans stock ni argent réels. Utilisez la console ou Postman.

3. Enregistrer et tester le webhook

Enregistrez votre URL via POST /v1/webhooks ; CHECK_HEALTH doit recevoir 2xx. Utilisez /v1/testmode/webhooks/fire pour envoyer un événement et /fail-next pour tester les nouvelles tentatives.

4. Passer à une clé réelle

Créez tke_live_, gardez le même code et remplacez l’hôte, key_id et secret. Enregistrez séparément les webhooks de la clé réelle : ils sont isolés par api_key_id.

3 pièges d’intégration essentiels

Ces trois pièges peuvent passer les tests et n’apparaître qu’en paiement réel ou au rapprochement.

Idempotency-Key est isolé par clé API

La déduplication est limitée à api_key_id. Le même Idempotency-Key avec deux clés crée deux commandes et deux débits, même dans une organisation. Gardez une clé stable par flux ou incluez key_id.

REST utilise id, les webhooks order_item_id

L’id d’eSIM dans REST correspond à order_item_id dans les webhooks ; order_id désigne la commande. Stockez cet UUID, jamais ICCID seul car il peut être réutilisé. GET /v1/esims?iccid=… retrouve l’id. Envoyez external_ref à la commande : REST et webhooks eSIM le renvoient avec order_id ; ?external_ref=… retrouve les eSIM associées.

Terminer correctement les boucles de curseur

GET /v1/orders et /v1/esims utilisent un curseur. Un curseur invalide repart au début sans erreur. Arrêtez si next_cursor est absent ou identique au curseur courant ; tester seulement !== null peut boucler sans fin.

Étapes suivantes

Intégration

Exemples exécutables, Postman, .http et génération d’un client depuis openapi.json.

Signature HMAC

Formule exacte et vecteurs de test pour vérifier votre signature.

Référence API

Paramètres, schémas, réponses et exemples exécutables de chaque endpoint.

Webhooks

Catalogue d’événements, signature, nouvelles tentatives et rapprochement REST.