Intégrer l'eSIM API

Utilisez l'eSIM API pour acheter des forfaits data et transmettre les détails d'installation depuis votre application. Vous avez besoin d'un espace de travail, d'une clé API et de fonds dans le portefeuille de l'organisation pour les achats en production. Suivez la procédure d'authentification et utilisez la région API correspondant à votre clé.

Donnez à la clé esim:read pour inspecter les offres et les ressources, et esim:write pour acheter ou gérer le service. Les identifiants d'installation ont des permissions distinctes : esim_credentials:read pour les récupérer et esim_credentials:write pour créer ou envoyer des liens d'installation. Conservez la clé API dans votre application serveur.

1. Choisir une offre

Listez les offres pour la destination, puis récupérez l'offre sélectionnée. Vérifiez zone.countries, le volume et la validité dans pricing, les conditions de débit, et tout service téléphonique inclus. Pour une eSIM existante, utilisez Lister les offres compatibles ; la disponibilité dans le catalogue général n'établit pas la compatibilité de recharge.

Récupérez les exigences d'identification de l'offre avant de collecter les informations de l'abonné. La réponse contient un schéma JSON pour chaque pays de couverture, exigeant le prénom, le nom et l'e-mail, plus d'éventuels champs supplémentaires. Activez la validation du format de l'e-mail et de la date. Vous collectez et validez ces informations ; l'eSIM API ne reçoit ni ne vérifie les réponses, et une validation réussie n'autorise pas un achat.

Pour une nouvelle eSIM, récupérez les options de paiement. Affichez le prix unique retourné ou le devis récurrent disponible avant d'accepter l'achat. Les prix de paiement sont hors taxes. Le renouvellement a son propre prix et sa propre cadence ; suivez forfaits récurrents si le client le choisit.

Pour l'exemple d'achat unique ci-dessous, installez curl et jq. Définissez BIRD_API_URL sur votre URL de base régionale, BIRD_API_KEY sur votre clé et ESIM_OFFER_ID sur l'ID de l'offre sélectionnée :

Exemple de code

curl --fail-with-body --silent --show-error \
  "$BIRD_API_URL/v1/esim/offers/$ESIM_OFFER_ID/checkout" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  > esim-checkout.json

jq '.one_time' esim-checkout.json

Vérifiez le prix et les conditions de l'offre avant de continuer. Le devis ne réserve pas la disponibilité.

2. Créer l'achat

Créez une commande avec offer_id. Omettez esim_id pour un nouveau profil ; incluez-le pour une recharge. Pour un achat unique, envoyez offer_revision et expected_price provenant du devis accepté. Ces champs rejettent les conditions modifiées avec 409 avant la facturation ; récupérez et vérifiez un nouveau devis avant d'accepter un prix modifié.

Définissez ESIM_ORDER_KEY sur une valeur unique pour cet achat et enregistrez-la avec la requête. Cet exemple achète une nouvelle eSIM non attribuée et copie le prix publié sans modifier son montant ni sa devise :

Exemple de code

jq '{offer_id, offer_revision: .one_time.offer_revision, expected_price: .one_time.price}' \
  esim-checkout.json > esim-order.json

curl --fail-with-body --silent --show-error \
  "$BIRD_API_URL/v1/esim/orders" \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $ESIM_ORDER_KEY" \
  --data-binary @esim-order.json

Pour attribuer un nouveau profil à la fin de la livraison, incluez un subscriber_id d'espace de travail ; suivez la configuration de l'abonné. Une recharge conserve l'attribution existante, omettez donc subscriber_id lors de l'envoi de esim_id. Envoyez les détails d'installation séparément après la livraison.

Enregistrez l'ID de commande retourné. Inspectez status même après HTTP 201, qui peut contenir une commande terminée ou échouée. HTTP 202 signifie que le traitement continue. Récupérez la commande jusqu'à ce qu'elle soit completed ou failed. Une commande terminée identifie esim_id et package_id ; l'installation sur l'appareil reste une étape distincte.

3. Fournir les détails d'installation

Après l'achat, lisez les identifiants d'installation, créez un lien d'installation hébergé, ou envoyez un lien par e-mail ou SMS. Ne laissez pas les détails d'activation et les liens d'installation apparaître dans les outils d'analyse ou les journaux publics.

Pour un lien envoyé, enregistrez l'identifiant de livraison et consultez l'historique de livraison. Une réponse 202 confirme l'acceptation pour l'envoi ; delivered confirme la livraison du message, et l'installation sur l'appareil nécessite sa propre vérification. Suivez le guide d'installation pour les méthodes prises en charge, l'expiration du lien et la récupération.

4. Récupérer un achat interrompu

Si la réponse de création a été perdue ou a renvoyé 503, répétez la requête enregistrée avec son Idempotency-Key d'origine ; voir requêtes idempotentes. Si vous disposez de l'identifiant de commande, lisez d'abord cette commande. Créer un autre achat alors que le résultat est incertain peut entraîner une facturation supplémentaire.

Pour une commande en charging, inspectez funding et le solde de votre portefeuille. funding.required_amount est le solde total nécessaire, taxes comprises ; comparez-le avec les fonds existants avant d'ajouter de l'argent. Les commandes ponctuelles relancent le financement automatiquement. Après le refus d'un premier achat récurrent pour fonds insuffisants, ajoutez des fonds et relancez explicitement la même requête de création avec sa clé d'origine.

Vérifiez le statut actuel de la commande même après funding.lapses_at : cet horodatage ne garantit pas l'annulation. Une commande peut encore aboutir si elle reçoit des fonds avant qu'une nouvelle tentative échoue pour fonds insuffisants.

Pour arrêter un achat non financé indésirable, annulez la commande. Une annulation non financée réussie renvoie status: failed et failure_code: canceled. Une commande ponctuelle financée renvoie 409 et se poursuit. Pour un premier achat récurrent, un paiement récupéré pendant l'annulation peut laisser l'achat payé se poursuivre tandis que le renouvellement futur s'arrête. Inspectez la commande et l'abonnement renvoyés avant de signaler une annulation ou un remboursement.

Pour un achat échoué, inspectez failure_code et failure_reason. Tout montant facturé est crédité automatiquement ; refund_transaction_id identifie un crédit émis. Conservez l'identifiant de commande pour le support si le paiement, la livraison ou le crédit reste non résolu.

5. Afficher les soldes et l'état du service

Obtenir l'eSIM pour le statut, l'état d'installation, les forfaits et available_actions. Affichez l'enveloppe, la consommation et la date et heure de mesure du forfait à l'aide du guide d'utilisation. Une consommation inconnue doit rester inconnue dans votre application.

Revérifiez la disponibilité des actions lorsque le client agit ; l'opération contrôle à nouveau les permissions et l'état. Utilisez le guide des opérations pour investiguer les achats incomplets, les problèmes d'installation ou les échecs de connectivité.

Étapes suivantes

Poursuivez avec la documentation, les guides et les exemples sur ce sujet.

Obtenir un guide d'implémentation