Guide

Comment intégrer l'API eSIM Atli à votre site ou application

Pas de clé API : chaque utilisateur reçoit un compte invité Atli. Rattachement à votre code partenaire, devis, paiement et livraison de l'eSIM.

Une requête curl vers l'endpoint d'achat de l'API Atli à côté d'un téléphone qui affiche la page de paiement d'Atli, avec la mascotte bleue ailée d'Atli qui tient un téléphone près d'une valise

Les partenaires peuvent utiliser la même API eSIM Atli que celle sur laquelle reposent heyatli.com et le widget Atli. Vous pouvez créer vos propres interfaces pour la liste des destinations, le choix des forfaits, le tunnel de paiement et l’installation sur un site web, une application ou un bot. Atli fournit le catalogue de forfaits, traite les paiements via son compte Stripe et émet les eSIM.

L’API n’utilise pas de clés API au niveau de l’application. L’authentification repose sur des tokens propres à chaque utilisateur. Votre serveur connecte chaque utilisateur avec un identifiant d’appareil unique ou via OAuth, puis envoie les requêtes à l’API en son nom. Chaque compte invité nécessite son propre identifiant d’appareil, que votre application doit conserver de façon sécurisée.

Sandbox, production et fichier OpenAPI

SandboxProduction
APIhttps://api-staging.heyatli.comhttps://api.heyatli.com
Fichier OpenAPIhttps://api-staging.heyatli.com/openapi.yamlhttps://api.heyatli.com/openapi.yaml
Page de paiementhttps://staging.heyatli.com/payhttps://heyatli.com/pay

Sandbox utilise des comptes distincts et des paiements de test, si bien qu’aucun débit réel n’est effectué. Ses eSIM proviennent d’un opérateur de test : elles ne peuvent donc pas être installées sur un téléphone, et les ventes Sandbox ne rapportent jamais de commission. Tous les exemples de ce guide qui créent des comptes ou des commandes utilisent les endpoints Sandbox. En production, remplacez l’URL de base de l’API par https://api.heyatli.com. La référence sur partners.heyatli.com/fr/dev/api bascule entre les deux.

Le schéma des principaux parcours de l'API Atli : créer un utilisateur, obtenir un devis, acheter et payer, récupérer l'eSIM, l'installer et suivre la consommation, avec des branches facultatives pour un vrai compte, les cartes enregistrées et de groupe, les recharges, les réductions et le partage

Les erreurs de l’API suivent toujours le même format : un code, un message en anglais et un trace_id à fournir au support Atli pour le diagnostic. Utilisez code pour déterminer comment votre application traite l’erreur et quel message elle affiche. Le champ message peut être conservé dans vos logs.

La connexion, les devis, l’utilisation de bons et la synchronisation des eSIM sont soumis à une limite de débit, et une requête refusée répond 429 avec Retry-After en secondes.

Vous pouvez générer un client typé pour l’API à partir de la spécification OpenAPI au lieu d’écrire chaque requête HTTP :

Bash
docker run --rm -v "$PWD:/out" \
  openapitools/openapi-generator-cli generate \
  -i https://api.heyatli.com/openapi.yaml \
  -g typescript-fetch -o /out/atli-sdk

Remplacez typescript-fetch par python, java, csharp, php ou swift6. Pour Go, il faut go --additional-properties=enumClassPrefix=true.

Étape 1 : créer un utilisateur

Vous pouvez créer un compte invité Atli pour chaque utilisateur sans lui demander de s’inscrire. Générez un UUID unique pour chaque utilisateur (par exemple avec crypto.randomUUID()) et enregistrez-le de façon sécurisée dans la fiche de son compte.

Traitez l’identifiant d’appareil comme une donnée d’authentification sensible, car toute personne qui y a accès peut s’authentifier en tant que cet utilisateur.

Connectez-vous avec cet UUID depuis votre serveur. Un identifiant qu’Atli n’a jamais vu crée un compte invité, et un identifiant connu s’y reconnecte :

Bash
curl https://api-staging.heyatli.com/login \
  -H 'Content-Type: application/json' \
  -d '{ "device_id": "YOUR_DEVICE_ID" }'
JSON
{
  "token": "eyJhbGci…",
  "refresh_token": "…",
  "expires_in": 900,
  "session_id": "…",
  "user": { "id": "…", "email": null }
}

Envoyez token sous la forme Authorization: Bearer YOUR_TOKEN à chaque appel qui nécessite un utilisateur. Il dure 15 minutes. Renouvelez-le peu avant l’échéance avec POST /refresh et le refresh_token. Dans la réponse du renouvellement, le nouveau token ne s’appelle pas token mais access_token. Assurez-vous que votre intégration lit le bon champ pour éviter des échecs d’authentification à l’expiration du premier token. Enregistrez le refresh token à chaque fois, car chaque renouvellement en renvoie un nouveau et retire l’ancien. Si vous perdez les deux, reconnectez-vous avec l’identifiant d’appareil.

Un invité peut acheter et utiliser des eSIM. Certaines eSIM partagées et certains bons exigent un vrai compte, et l’API les refuse à un invité avec un code comme gift_sign_in_required. Pour donner une adresse e-mail à l’invité, envoyez son token et son device_id à POST /auth/email/otp, puis confirmez avec POST /auth/email/verify. La connexion par WhatsApp ou Telegram peut transformer un invité en vrai compte de la même façon. Dans les deux cas, l’invité conserve ses eSIM et les données de son compte. Si vous omettez le device_id ou utilisez une adresse e-mail qui a déjà un compte Atli, la personne se retrouve dans un autre compte.

Étape 2 : rattacher l’utilisateur à votre code partenaire

Rattachez chaque nouvel utilisateur à votre code avant son premier devis :

Bash
curl https://api-staging.heyatli.com/user/referral/redeem \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "code": "YOUR_PARTNER_CODE" }'

Le champ result indique le résultat : ok signifie que l’utilisateur a bien été rattaché, already qu’il a déjà un parrain, notnew qu’il a déjà effectué un achat, own qu’il s’agit de votre propre code et notfound que le code est introuvable. Une personne ne peut être rattachée qu’une fois, et seulement si elle n’a ni parrain ni achat antérieur. Faites cet appel juste après avoir créé l’utilisateur.

Le rattachement est définitif. Si votre code comporte une réduction, la première eSIM de l’utilisateur en bénéficie sans que vous ayez à renvoyer le code. Le guide du programme d’affiliation explique ce que ce rattachement vous rapporte.

Étape 3 : afficher les forfaits et obtenir un devis

GET /explore/plans renvoie le catalogue complet, qui comprend les destinations disponibles, les offres, les prix et les volumes de données. Cet appel ne demande aucun token, si bien que votre serveur peut lister les forfaits avant que quiconque ait un compte. Appelez-le depuis votre serveur, car l’API refuse avec 403 les requêtes de navigateur venant d’autres sites web. Passez currency, et filtrez avec destination (JP, europe) ou category (local, regional, global) :

Bash
curl 'https://api-staging.heyatli.com/explore/plans?currency=EUR&destination=JP'

L’id d’une offre est le product_id que vous achetez. Demandez un devis pour cette offre avec store: true afin d’obtenir un quote_id :

Bash
curl https://api-staging.heyatli.com/plan/quote \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "product_id": "THE_PACKAGE_ID",
        "currency": "EUR",
        "store": true }'
JSON
{
  "subtotal_cents": 1500,
  "total_discount_cents": 150,
  "net_total_cents": 1350,
  "currency": "EUR",
  "quote_id": "…",
  "expires_at": "…"
}

Affichez net_total_cents comme prix final. Les devis enregistrés expirent au bout de 30 minutes : générez donc le devis quand l’utilisateur passe au tunnel de paiement. Chaque utilisateur ne détient qu’un devis enregistré à la fois, et un nouveau devis remplace le précédent.

target_esim_id recharge une eSIM que l’utilisateur possède déjà. Sans ce champ, le forfait va sur l’eSIM par défaut de l’utilisateur. S’il n’a pas encore d’eSIM, ou si le réseau de l’eSIM par défaut ne vend pas ce forfait, le forfait va sur une nouvelle eSIM. Pour une personne connectée avec son propre compte Atli, le champ new_esim du devis indique lequel des deux cas s’applique. Les devis des invités ne le contiennent pas. Pour un invité, comparez l’eSIM de la commande terminée avec celles que liste GET /esims avant d’afficher les étapes d’installation.

auto_apply_best_voucher applique le bon éligible de plus grande valeur dont dispose l’utilisateur, et points_to_redeem lui permet d’utiliser ses points, que les applications Atli affichent comme crédits Atli. Une commande n’accepte qu’un seul type de réduction. La réduction de parrainage issue de votre lien passe en premier et l’emporte sur tout bon que le devis choisirait de lui-même. Un bon indiqué avec voucher_code la remplace, et indiquer à la fois un bon et un referral_code échoue avec cannot_combine_voucher_and_referral. Les points ne comptent que si aucune des deux réductions ne s’applique.

Étape 4 : créer la commande et encaisser le paiement

Achetez le devis enregistré par son quote_id. La commande reprend le forfait, les réductions et le prix du devis. Si le total a varié de plus de 1 % entre-temps, l’achat échoue avec price_changed et vous redemandez un devis.

Chaque devis ne peut servir qu’à une seule commande. Si une requête d’achat est soumise une seconde fois par erreur ou après un timeout, l’API renvoie la commande existante au lieu de créer un doublon. La requête doit aussi contenir une idempotency_key, qui empêche les commandes en double quand vous achetez directement avec un product_id au lieu d’un devis enregistré.

Bash
curl https://api-staging.heyatli.com/plan/purchase \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "quote_id": "THE_QUOTE_ID",
        "idempotency_key": "A_NEW_UUID" }'
JSON
{
  "order_id": "…",
  "client_secret": "pi_…_secret_…",
  "sealed_secret": "eyJhbGciOiJFQ0RILUVTIi…",
  "key_id": "…",
  "seal_signature": "…",
  "options": "{\"message\":\"Plan for Japan\",\"lang\":\"en\"}",
  "options_signature": "…",
  "total_amount_cents": 1350,
  "status": "pending_payment"
}

Le client_secret appartient à un PaymentIntent Stripe sur le compte d’Atli. Utilisez-le pour monter le Payment Element de Stripe. Votre serveur récupère la clé publiable avec GET /stripe/config et la transmet à la page avec le client_secret. Ne codez pas la clé en dur, car elle diffère entre Sandbox et production, et ne la récupérez pas depuis la page, car l’API refuse les requêtes de navigateur venant d’autres sites web :

JavaScript
const stripe = Stripe(publishable_key);

const elements = stripe.elements({ clientSecret: order.client_secret });
elements.create('payment').mount('#pay');

const { error } = await stripe.confirmPayment({
  elements,
  confirmParams: { return_url: window.location.href },
  redirect: 'if_required',
});

Ne transmettez le client_secret qu’à la session de l’utilisateur qui paie, et gardez-le hors de vos logs. Une fois le paiement confirmé par Stripe, demandez à Atli d’émettre l’eSIM :

Bash
curl https://api-staging.heyatli.com/plan/fulfill-payment \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "order_id": "THE_ORDER_ID" }'

Si cet appel échoue, ne débitez pas une seconde fois. Atli finalise de lui-même une commande payée.

Le paiement est débité sur le compte Stripe d’Atli : c’est donc le nom d’Atli qui figure sur le relevé de carte de votre client, et les remboursements et litiges reviennent à Atli. Pour proposer Apple Pay et Google Pay dans votre propre formulaire, écrivez à [email protected] quand votre intégration aura de vraies ventes à son actif. Les cartes enregistrées passent par le même achat : ajoutez payment_method_id pour en débiter une, ou save_card: true pour garder une nouvelle carte pour la prochaine fois.

Payer sur la page de paiement d’Atli

Les bots WhatsApp et Telegram, les applications vocales et les assistants IA ne peuvent pas afficher le formulaire de paiement de Stripe. Pour ces intégrations, vous pouvez diriger les utilisateurs vers la page de paiement hébergée par Atli. Construisez le lien à partir des trois valeurs scellées renvoyées par l’achat. Si l’achat renvoie aussi options et options_signature, transmettez-les : la page affiche alors une ligne comme « Plan for Japan » au-dessus du formulaire de carte dans la langue demandée par votre requête :

JavaScript
const link = new URL('https://staging.heyatli.com/pay');
link.search = new URLSearchParams({
  type: 'payment_intent',
  sealed_secret: order.sealed_secret,
  key_id: order.key_id,
  seal_signature: order.seal_signature,
  ...(order.options && {
    options: Buffer.from(order.options).toString('base64url'),
    options_signature: order.options_signature,
  }),
}).toString();

La page de paiement affiche le total de la commande et accepte les paiements par carte, Apple Pay et Google Pay. Appelez ensuite POST /plan/fulfill-payment avec le order_id, et répétez l’appel jusqu’à ce que la commande soit payée. Seul cet appel confirme le paiement, car la page affiche comme réussi un paiement encore en cours de traitement.

Respectez ces exigences lorsque vous générez des liens de paiement :

  • Transmettez sealed_secret, key_id, seal_signature et options_signature exactement tels que l’API les a renvoyés, et URLSearchParams se charge de l’encodage. options fait exception : encodez-le en base64url sans rien changer au JSON auparavant. Ne mettez jamais un client_secret en clair dans un lien.
  • Les valeurs Sandbox s’ouvrent uniquement sur staging.heyatli.com/pay, et les valeurs de production uniquement sur heyatli.com/pay.
  • Le lien paie la commande de quelqu’un. Envoyez-le uniquement au titulaire du compte et gardez-le hors des logs.
  • Ne stockez pas les liens pour plus tard. Un nouvel achat annule la commande en attente précédente et son lien.
  • brand=none masque le logo Atli. lang et theme règlent la langue et l’apparence de la page. Les paramètres de redirection n’acceptent que des adresses https sur heyatli.com ou ses sous-domaines : dites donc à la personne de revenir dans votre conversation une fois le paiement effectué.
  • Le bouton Annuler de la page laisse la commande ouverte. Pour l’annuler, appelez POST /orders/{id}/cancel.

La même page enregistre une carte sans paiement : créez la configuration avec POST /user/payment-methods/setup-intent, construisez le lien avec type réglé sur setup_intent, puis enregistrez la carte avec POST /user/payment-methods/confirm. La page partners.heyatli.com/fr/dev/payment-widget peut ouvrir un paiement de test sur un nouvel invité Sandbox.

Étape 5 : afficher l’eSIM et ses liens d’installation

Une eSIM peut ne pas être disponible pour l’installation immédiatement après le paiement. Interrogez le statut de la commande jusqu’à ce que l’objet esim contienne les informations d’installation. Pendant le traitement de la commande, affichez un message d’état approprié :

Bash
curl 'https://api-staging.heyatli.com/fulfillment/status-updates?order_id=THE_ORDER_ID' \
  -H 'Authorization: Bearer YOUR_TOKEN'
JSON
{
  "order_id": "…",
  "status": "completed",
  "esim": {
    "id": "…",
    "iccid": "…",
    "lpa_address": "…",
    "activation_code": "…",
    "qr_string": "…"
  }
}

Le statut paid confirme le paiement, et completed indique que l’eSIM et son forfait ont été provisionnés. Affichez qr_string sous forme de QR code pour une installation depuis un second appareil. Pour les utilisateurs qui installent l’eSIM directement sur leur téléphone, fournissez les liens d’installation pour iPhone ou Android, qui ouvrent la configuration eSIM du téléphone :

JavaScript
const lpa = `LPA:1$${esim.lpa_address}$${esim.activation_code}`;
const carddata = encodeURIComponent(lpa);

const iphone = `https://esimsetup.apple.com/esim_qrcode_provisioning?carddata=${carddata}`;
const android = `https://esimsetup.android.com/esim_qrcode_provisioning?carddata=${carddata}`;

Vous pouvez aussi donner à l’utilisateur un seul lien qui fait tout cela : https://heyatli.com/my/esim avec lpa réglé sur le qr_string en base64url et iccid réglé sur l’ICCID de l’eSIM. La page affiche le QR code, les deux liens d’installation en un geste et les informations pour une saisie manuelle, et avec l’ICCID elle affiche aussi les forfaits et les données restantes. Elle ne demande aucun compte Atli. Ajoutez une langue au chemin comme dans /ja/my/esim, et utilisez staging.heyatli.com pour une eSIM Sandbox. Toute personne qui a le lien peut installer l’eSIM : envoyez-le donc uniquement à la personne qui l’utilisera.

Nos guides pour iPhone et Android montrent ce que l’utilisateur voit ensuite.

GET /esims liste les eSIM de l’utilisateur avec leurs informations d’installation, leurs forfaits et les données consommées à la dernière synchronisation. POST /esims/{id}/sync demande au réseau les chiffres actuels. Chaque requête de synchronisation interroge l’opérateur du réseau et est soumise à une limite de débit. Demandez des données de consommation à jour quand c’est nécessaire, plutôt que d’interroger l’API automatiquement à intervalles fixes.

Laisser les gens se connecter avec leur compte Atli

Pour une application où les gens utilisent leur propre compte Atli plutôt qu’un invité, Atli propose OAuth 2.1 : le flux par code d’autorisation avec PKCE (S256), la rotation des refresh tokens et la révocation. Les utilisateurs s’authentifient et autorisent l’accès sur heyatli.com : votre application ne manipule donc jamais leurs mots de passe Atli.

Enregistrez un client sur partners.heyatli.com/fr/dev/oauth/clients. Un compte peut posséder 10 clients : des clients public pour les applications mobiles et des clients confidential pour un serveur capable de garder un secret. Une page web ne peut pas faire elle-même l’appel qui obtient les tokens, car l’API refuse les requêtes de navigateur venant d’autres sites web sauf si Atli a marqué le client comme fiable : donnez donc à une application web un serveur et un client confidentiel. Seul un client dont vous êtes propriétaire peut obtenir des tokens pour l’API, et votre compte doit avoir une adresse e-mail pour en posséder un.

Récupérez les endpoints OAuth dans les métadonnées du serveur d’autorisation au lieu de les coder en dur :

Bash
curl https://api.heyatli.com/.well-known/oauth-authorization-server

Les access tokens durent 15 minutes. Chaque renouvellement renvoie un nouveau refresh token, qui doit remplacer le précédent dans le stockage sécurisé de votre application. Les personnes qui se connectent via votre client peuvent vous être rattachées automatiquement une fois qu’Atli a activé cette option sur votre compte. D’ici là, rattachez-les vous-même avec POST /user/referral/redeem et leur access token, comme à l’étape 2.

Partage, bons et groupes

Pour acheter une eSIM partageable, demandez un devis avec is_gift: true et réglez max_claims sur une valeur comprise entre 1 et 20. Une fois la commande exécutée, récupérez le claim_url dans GET /gifts/sent. POST /rewards/voucher/redeem ajoute un bon au compte de l’utilisateur. Un membre d’un Atli Group peut demander un devis avec group_id et acheter avec la carte du groupe. La page partners.heyatli.com/fr/dev/api détaille chacun de ces parcours étape par étape avec le code correspondant.

FAQ

L'API Atli a-t-elle une clé API ?
Non. Les tokens identifient une personne et non une application. Votre serveur connecte chaque utilisateur avec un identifiant d’appareil ou via OAuth, puis appelle l’API en tant que cet utilisateur.
Ai-je besoin de mon propre compte Stripe ?
Non. Les commandes sont débitées sur le compte Stripe d’Atli. Votre formulaire utilise la clé publiable d’Atli fournie par GET /stripe/config, et les données de carte partent directement chez Stripe : elles ne passent jamais par vos serveurs ni par l’API.
Les clients peuvent-ils payer avec Apple Pay ou Google Pay ?
Oui. La page de paiement d’Atli propose les deux. Pour votre propre formulaire Stripe, écrivez à [email protected] quand votre intégration aura de vraies ventes.
Comment ajouter des données à une eSIM qu'un utilisateur possède déjà ?
Demandez un devis pour la nouvelle offre avec target_esim_id pointant vers cette eSIM, puis achetez-la comme d’habitude. Le forfait va sur l’eSIM que l’utilisateur possède déjà : il n’y a donc rien de nouveau à installer. Si le réseau de cette eSIM ne vend pas l’offre, l’API la refuse avec incompatible_esim.
Et si le paiement passe mais que mon appel de finalisation échoue ?
Ne débitez pas une seconde fois. Atli finalise de lui-même une commande payée : continuez donc à interroger GET /fulfillment/status-updates jusqu’à ce que l’eSIM apparaisse.
Où tester sans argent réel ?
Testez sur Sandbox : son adresse est api-staging.heyatli.com. Payez avec la carte de test de Stripe 4242 4242 4242 4242, n’importe quelle date future et n’importe quel code de sécurité. Sandbox a ses propres comptes.