Allo

Commander une eSIM

Commande une eSIM pour l'un des numéros du compte et la débite sur votre crédit prépayé en priorité, puis sur votre carte enregistrée. La réponse renvoie…

POST/v2/api/partner/accounts/{account_id}/esims

Commande une eSIM pour l'un des numéros du compte et la débite sur votre crédit prépayé en priorité, puis sur votre carte enregistrée. La réponse renvoie l'eSIM avec le statut PROVISIONING. L'eSIM est en général prête 5 à 15 minutes plus tard, et Allo vous envoie alors le webhook partner.esim.ready.

Requête

  • phone_number est requis. Ce doit être l'un des numéros du compte ou de ses membres, créé avec number_preference.esim à true (voir Créer un compte, Ajouter un numéro et Ajouter un membre). Tout autre numéro échoue avec PARTNER_ESIM_NUMBER_NOT_FOUND ou ESIM_NOT_ELIGIBLE.
  • tier est requis : un code renvoyé par Obtenir l'offre eSIM, par exemple ESIM_20GB. Un code inconnu échoue avec INVALID_ESIM_TIER.
  • holder_id est optionnel : l'utilisateur Allo auquel l'eSIM est rattachée. Omettez-le pour que le compte lui-même en soit le titulaire. Pour le numéro d'un membre, envoyez l'id du membre renvoyé par Ajouter un membre ou Lister les membres. Cela vaut aussi pour un numéro que le membre a repris avec phone_number.
  • identity est requis : l'entreprise à laquelle la ligne est enregistrée. corporate_name, postal_address, postal_code (5 chiffres) et city sont requis. first_name, last_name, company_name, siret, naf et email sont optionnels. Un champ requis manquant échoue avec ESIM_IDENTITY_INCOMPLETE.

Facturation

  • Les frais de mise en service et la première période du palier sont facturés sur l'abonnement que vous payez pour le compte, avec votre remise partenaire appliquée. 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 commande et qu'aucune carte n'est enregistrée, la requête échoue avec 402 PARTNER_CREDIT_INSUFFICIENT. Rechargez votre crédit ou ajoutez une carte, puis réessayez avec une nouvelle Idempotency-Key.
  • Une carte qui exige 3D Secure est refusée avec 402 ESIM_PAYMENT_FAILED. Une carte refusée échoue de la même façon. Rien ne reste en attente : mettez à jour votre carte dans le portail partenaire, puis réessayez.
  • Un numéro dont l'eSIM a été révoquée peut recevoir une nouvelle eSIM. La nouvelle commande facture à nouveau les frais de mise en service. Si vous la passez juste après la révocation, elle reste PROVISIONING jusqu'à ce que le réseau mobile ait confirmé la révocation.
  • Si l'abonnement que vous payez pour le compte ne peut pas recevoir d'eSIM pour le moment, la requête échoue avec ESIM_SUBSCRIPTION_CONFLICT. Si l'erreur indique retryable: true, réessayez dans quelques minutes.

Nouvelles tentatives

Envoyez un en-tête Idempotency-Key (8 à 100 lettres, chiffres, - ou _, par exemple un UUID) et réutilisez-le pour réessayer la même commande. Une nouvelle tentative avec la même clé ne vous débite pas deux fois. Une clé dans un autre format échoue avec INVALID_IDEMPOTENCY_KEY.

Erreurs propres au numéro

CodeSignification
ESIM_ALREADY_EXISTSLe numéro a déjà une eSIM non révoquée. Consultez-la avec Obtenir une eSIM, ou révoquez-la pour en commander une nouvelle.
ESIM_ORDER_IN_PROGRESSUne commande pour ce numéro est encore en cours de provisionnement. Attendez partner.esim.ready ou partner.esim.failed.
ESIM_ORDER_NEEDS_SUPPORTUne précédente commande a été débitée sans aboutir, et le support Allo la traite. Écrivez à [email protected] avant de commander à nouveau.
PARTNER_ESIM_HOLDER_NOT_FOUNDholder_id ne peut pas détenir d'eSIM pour ce numéro. Omettez-le pour utiliser le compte.

Autorisation

Authorizationstring · headerrequis

Api-Key ak_live_…

Paramètres de chemin

account_idstringrequis

The account id returned by Create account (usr-*).

En-têtes

Idempotency-Keystring

Optional. 8 to 100 letters, digits, - or _, for example a UUID. Retrying with the same key does not charge you twice.

Corps

phone_numberstringrequis

One of the account's numbers that can carry an eSIM: created, added or given to a member with number_preference.esim set to true.

tierstringrequis

A tier code from Get eSIM offer.

holder_idstring | null

Optional. The Allo user the eSIM is registered to: the account itself by default, or the id of a member returned by Add member for the member's own number, including a number the member took over with phone_number.

identityobjectrequis

The business the line is registered to.

10 champs
corporate_namestringrequis
postal_addressstringrequis
postal_codestringrequis

5 digits.

citystringrequis
first_namestring | null
last_namestring | null
company_namestring | null
siretstring | null
nafstring | null
emailstring | null

Réponses

201eSIM ordered
dataobject
11 champs
idstring

The eSIM id (eso-*).

account_idstring

The account the eSIM was ordered for.

partner_client_refstring | null

Your own reference, set when the account was created.

phone_numberstring

The number the eSIM carries.

tierstring

The tier code that was ordered.

scheduled_tierstring | null

The tier a scheduled downgrade will switch the eSIM to. Always null on a new order.

scheduled_tier_atstring<date-time> | null

When the scheduled downgrade applies. Always null on a new order.

statusenum<string>

PROVISIONING: ordered, not ready yet. ACTIVE: ready, calls to the number ring the eSIM. FAILED: the order did not complete, see failure_code. REVOKED: the eSIM was revoked, or replaced by a later eSIM on the same number, and no longer works.

PROVISIONINGACTIVEFAILEDREVOKED

failure_codestring | null

Why the order failed. Set only when status is FAILED.

dataobject | null

Mobile data use this month. Always null here, since a new eSIM is not ACTIVE yet: read it with Get eSIM once the eSIM is ready.

created_atstring<date-time>

When the eSIM was ordered.

400Validation error: MISSING_FIELD, INVALID_ESIM_TIER, ESIM_IDENTITY_INCOMPLETE or INVALID_IDEMPOTENCY_KEY.
errorobject
401
402Billing error, nothing is left pending. PARTNER_CREDIT_INSUFFICIENT: your prepaid credit does not cover the order and your billing account has no card on file. ESIM_PAYMENT_FAILED: your card was declined or requires 3D Secure.
errorobject
403The API key lacks the PARTNER scope.
errorobject
404The account was not provisioned by your API key (PARTNER_ACCOUNT_NOT_FOUND), the number does not belong to the account (PARTNER_ESIM_NUMBER_NOT_FOUND), or holder_id cannot hold an eSIM for this number (PARTNER_ESIM_HOLDER_NOT_FOUND).
errorobject
409The number cannot carry an eSIM (ESIM_NOT_ELIGIBLE), already has an eSIM that is not revoked (ESIM_ALREADY_EXISTS), has an order in progress (ESIM_ORDER_IN_PROGRESS) or one handled by Allo support (ESIM_ORDER_NEEDS_SUPPORT), or the subscription you pay for the account cannot take an eSIM right now (ESIM_SUBSCRIPTION_CONFLICT).
errorobject
429
500eSIMs cannot be ordered for this account right now (ESIM_UNAVAILABLE).
errorobject