Consulter la consommation et ajouter une recharge
Utilisez ce guide pour ajouter des données à une eSIM existante. Vous devez avoir l'autorisation de lire l'eSIM et d'acheter un forfait, ainsi que des fonds suffisants dans le portefeuille. La disponibilité des recharges dépend du profil, des forfaits existants et de l'offre sélectionnée.
1. Consulter les forfaits actifs
Ouvrez le profil depuis eSIMs et examinez Data packages. Avec API, listez les forfaits de l'eSIM et vérifiez leur état, leur expiration et leur solde.
balance.total_bytes correspond à l'enveloppe achetée. Si used_bytes, remaining_bytes ou used_percent est null, aucune mesure n'est disponible. Conservez ces valeurs comme inconnues dans votre application.
Lisez le champ balance_reporting de l'eSIM pour décider quoi afficher. S'il vaut unavailable, affichez l'enveloppe achetée sans la présenter comme des données restantes mesurées. S'il vaut available, la consommation peut rester inconnue tant qu'un rapport n'est pas arrivé. L'historique de consommation quotidien est distinct et n'est pas disponible actuellement.
Utilisez balance.as_of pour connaître l'heure de la dernière mise à jour du solde ; avant qu'une consommation ne soit signalée, il peut s'agir de l'heure de livraison du forfait. balance.observed_at correspond à l'heure de mesure réseau lorsqu'elle est fournie. Affichez l'horodatage avec la consommation mesurée afin que le client puisse repérer un rapport différé.
2. Lister les offres compatibles
Sélectionnez Top up sur l'eSIM, ou appelez Lister les offres compatibles pour ce profil. Utilisez une offre renvoyée plutôt qu'une offre du catalogue général. Une couverture dans le même pays n'établit pas la compatibilité.
Si un rechargement n'est pas disponible, lisez available_actions sur l'eSIM pour en connaître la raison. Une commande non terminée ou la limite de forfaits peut empêcher un nouvel achat. Résolvez la commande existante avant de réessayer. Actualisez les offres compatibles avant de soumettre : une offre peut devenir indisponible entre la sélection et l'achat.
Une eSIM en expired est en veille et peut revenir à active après l'aboutissement d'un rechargement compatible. Vérifiez l'action disponible et les offres compatibles avant de décider que le profil installé doit être remplacé.
3. Vérifier les conditions effectives
Affichez l'enveloppe, la couverture, le prix publié et la devise, ainsi que la validité de l'offre sélectionnée. Comparez la validité du nouveau forfait avec la limite de service active_until de l'eSIM lorsqu'elle est présente. Si cette limite devait réduire la validité achetée, la commande renvoie 409 avec la validité effective. Affichez la période plus courte et obtenez l'acceptation avant de définir acknowledge_shortened_validity: true.
Une recharge crée un forfait supplémentaire. Elle ne modifie pas le solde d'un forfait existant et ne prolonge pas sa date d'expiration. Vérifiez l'activation et l'expiration du nouveau forfait après la livraison.
4. Approuver et suivre la commande
Confirmez l'achat dans le tableau de bord. Avec le API, créez une commande en utilisant le esim_id existant, le offer_id sélectionné, le revision de l'offre comme offer_revision, et son pricing.price comme expected_price. Omettez subscriber_id ; un rechargement conserve l'attribution existante. Enregistrez l'identifiant de commande et un Idempotency-Key pour les nouvelles tentatives.
Si le prix ou la révision acceptés ont changé, récupérez l'offre actuelle et confirmez les nouvelles conditions avant de soumettre un autre achat. Copiez le montant et la devise du prix renvoyé sans conversion ni arrondi.
Suivez la commande dans Orders, ou récupérez la commande via API. Inspectez status après les réponses 201 et 202. Si la réponse est perdue, renvoyez la même requête avec la même clé ; ne créez pas un nouvel achat tant que le résultat est incertain.
5. Vérifier le forfait résultant
Lorsque la commande est completed, utilisez son package_id pour obtenir le nouveau forfait. Vérifiez que l'eSIM cible, la couverture et l'enveloppe correspondent à l'achat. Le rechargement utilise le profil installé ; vous n'avez pas besoin d'installer une nouvelle eSIM. Un forfait en attente de première utilisation peut ne pas encore avoir d'horodatage d'activation ou d'expiration.
Dépannage
Si la commande est terminée mais qu'un solde reste inconnu, comparez l'état du forfait et les horodatages de rapport. Le rapport peut être en retard sur la consommation de l'appareil ; passer une nouvelle commande ne résout pas ce délai. Si un achat échoue, examinez les détails de l'échec et toute référence de crédit avant de réessayer.
Étapes suivantes
Ressources associées
Poursuivez avec la documentation, les guides et les exemples sur ce sujet.