Passer au contenu principal
POST
Buy eSIM top-up
Scope requis : PARTNER
Achète des données mobiles en plus pour une eSIM, au-delà de son palier. Une recharge est débitée une seule fois. Ses données comptent pour le mois civil en cours uniquement (heure de Paris), et les données non utilisées sont perdues à la fin de ce mois. Quand une eSIM atteint son quota, les données mobiles s’arrêtent jusqu’au mois suivant ou jusqu’à l’achat d’une recharge. Les appels et les SMS continuent de fonctionner, et la ligne n’est jamais facturée pour des données au-delà du quota. Allo envoie partner.esim.data_low à 80 % du quota et partner.esim.data_exhausted à 100 %, pour que vous puissiez proposer une recharge à votre client à temps.

Requête

  • L’en-tête Idempotency-Key est obligatoire : voir Nouvelles tentatives.
  • code est requis : un top_ups[].code renvoyé par Obtenir l’offre eSIM.
  • L’eSIM doit être ACTIVE. Tant qu’elle est en cours de provisionnement, la requête échoue avec ESIM_NOT_READY.
Un code inconnu échoue avec INVALID_ESIM_TOPUP. Vous pouvez acheter plusieurs recharges pour la même eSIM dans le même mois : leurs données s’additionnent.

Réponse

Facturation

  • Le prix est celui que renvoie Obtenir l’offre eSIM pour le compte : hors taxes, dans la devise de l’abonnement que vous payez pour le compte.
  • Allo prélève d’abord votre crédit prépayé, puis débite le reste sur votre carte enregistrée. Allo ne facture jamais votre client.
  • Si votre crédit prépayé ne couvre pas la recharge et qu’aucune carte n’est enregistrée, la requête échoue avec 402 PARTNER_CREDIT_INSUFFICIENT.
  • Une carte refusée, ou une carte qui exige 3D Secure, échoue avec 402 ESIM_PAYMENT_FAILED. Une validation 3D Secure est impossible via l’API : Allo annule la tentative et rien ne reste en attente. Réessayez avec une autre carte, mise à jour dans le portail partenaire, ou après avoir rechargé votre crédit prépayé.

Nouvelles tentatives

L’en-tête Idempotency-Key est obligatoire sur cet endpoint, pour qu’une nouvelle tentative ne vous débite jamais deux fois. Envoyez un nouvel UUID pour chaque recharge, et le même quand vous réessayez cette recharge.
  • Sans l’en-tête, la requête échoue avec 400 IDEMPOTENCY_KEY_REQUIRED.
  • La clé compte 8 à 100 lettres, chiffres, - ou _. Une clé dans un autre format échoue avec 400 INVALID_IDEMPOTENCY_KEY.
  • Une clé déjà utilisée sur cette eSIM pour une recharge avec un autre code échoue avec 409 IDEMPOTENCY_KEY_ALREADY_USED. Envoyez une nouvelle clé pour une nouvelle recharge.

Erreurs propres à l’eSIM

Autorisations

Authorization
string
header
requis

En-têtes

Idempotency-Key
string
requis

Required. 8 to 100 letters, digits, - or _, for example a UUID. Send a new key for each top-up and the same key when you retry it: Allo does not charge you twice.

Pattern: ^[A-Za-z0-9_-]{8,100}$

Paramètres de chemin

id
string
requis

The eSIM id returned by Order eSIM (eso-*).

Corps

application/json
code
string
requis

A top-up code from Get eSIM offer.

Exemple:

"TOPUP_5GB"

Réponse

Top-up bought

data
object