Intégration API

Démarrage rapide de l’API

Après approbation du compte, le service commercial attribue les tarifs et active l’accès API. Créez une clé dans le tableau de bord partenaire. Les clés en lecture seule ne permettent pas de commander. Les achats doivent aussi être activés sur votre compte.

Utilisez une clé bearer côté serveur à chaque requête. Ne placez pas la clé dans le code du navigateur ni dans une URL. Vous pouvez la révoquer dans le tableau de bord partenaire.

Créer une commande

Envoyez un UUID dans Idempotency-Key. Réutilisez le même UUID après un délai dépassé ou une erreur de connexion. Envoyez le prix confirmé par le client et confirmez que l’appareil destinataire prend en charge l’eSIM et est désimlocké. Les changements de tarif en temps réel renvoient 409 PRICE_CHANGED. Cette API est en production : les achats acceptés utilisent les fonds réels du portefeuille.

POST /api/partner/v1/orders
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: 83c77d9f-395f-4ff0-8ed6-c461bda46559

{"productId":"PRODUCT_ID_FROM_CATALOG","expectedPrice":"2.25","deviceConfirmed":true}

Une réponse 201 contient orderId et esim ; vérifiez esim.status et esim.failure. Consultez la commande toutes les 10 secondes. Les fonds sont d’abord réservés, puis débités après vérification de la livraison. Une répétition peut aussi renvoyer une commande échouée. Si le résultat du fournisseur est incertain, les fonds restent réservés pendant le rapprochement de la commande initiale. Les données d’installation sont privées et n’apparaissent qu’après confirmation de la livraison.

Les montants sont des chaînes décimales en USD. Les listes renvoient items et nextCursor ; poursuivez jusqu’à ce que nextCursor soit null. Limites : 120 requêtes par clé et par minute, et 10 tentatives d’achat par utilisateur et par minute. Respectez Retry-After en cas de 429. Erreurs courantes : 401 clé invalide, 403 accès refusé, 402 solde insuffisant, 404 commande inaccessible, 409 conflit de prix ou d’idempotence, 503 service indisponible. Consultez la commande initiale avant tout nouvel achat.