Intégration API eSIM : architecture, workflows, webhooks et sécurité

Une API eSIM permet à une entreprise de vendre et de gérer la connectivité au sein de son propre site web, de son application mobile, de son parcours de réservation, de son portail client ou de son système d’entreprise.

Le client peut ne jamais voir le fournisseur de connectivité en amont. Il choisit un forfait, paie la marque qu’il connaît, reçoit les informations d’installation et gère son service dans une expérience cohérente.

L’intégration technique qui sous-tend ce parcours est plus complexe que l’envoi d’une requête suivie de la réception d’un code QR. Les commandes peuvent aboutir de manière asynchrone. Les profils ont leur propre cycle de vie. La validité du forfait peut commencer à l’achat, à l’installation ou à la première utilisation du réseau. Les relevés de consommation peuvent arriver plus tard. Les webhooks peuvent être retardés, dupliqués ou livrés dans le désordre. Une expiration de délai ne prouve pas l’échec d’une commande.

Une intégration fiable doit donc répondre à quatre questions :

1. Quel système fait autorité pour chaque donnée ?
2. Quelles opérations sont synchrones et lesquelles sont asynchrones ?
3. Comment l’intégration se rétablit-elle après une incertitude ou un échec ?
4. Comment les opérations sensibles sont-elles authentifiées, autorisées, surveillées et rapprochées ?

Ce guide présente une architecture pratique pour les entreprises qui intègrent un service SIM et eSIM en marque blanche. Les exemples sont indépendants des fournisseurs et donnés à titre illustratif. Ils ne constituent pas une spécification de l’API actuelle de SIM24.biz.

Points essentiels

• Une API commerciale eSIM relie normalement les systèmes de l’entreprise à une plateforme fournisseur. Elle ne donne pas à une boutique ordinaire un accès direct à l’eUICC ou au SM-DP+.
• Définissez les systèmes de référence avant de développer. La plateforme commerciale, le fournisseur, le prestataire de paiement et le CRM ne doivent pas tous prétendre faire autorité sur le même état.
• Traitez l’exécution des commandes et de nombreuses opérations de cycle de vie comme asynchrones, même lorsqu’elles se terminent généralement rapidement.
• Utilisez une référence stable générée par le client API et une stratégie d’idempotence afin qu’une nouvelle tentative ne crée pas une seconde commande involontaire.
• Une requête dont le délai expire a un résultat inconnu jusqu’à ce que le client récupère la ressource ou reçoive un événement vérifié.
• Les consommateurs de webhooks doivent vérifier l’authenticité, rejeter les messages périmés ou invalides, stocker les identifiants d’événement et traiter les doublons sans risque.
• Un code HTTP de succès confirme qu’une requête a été acceptée ou a reçu une réponse avec succès. Il ne prouve pas nécessairement qu’un profil a été installé ou que les données mobiles fonctionnent.
• Séparez les états de commande, profil, forfait, réseau et paiement. Les regrouper dans un seul indicateur « actif » rend l’assistance et le rapprochement peu fiables.
• Utilisez des identifiants à privilèges minimaux, un stockage sécurisé des secrets, une rotation contrôlée, une isolation forte entre partenaires et des journaux d’audit détaillés.
• Un bac à sable réaliste, les tests d’échec et le rapprochement financier sont des conditions de mise en production, pas des améliorations facultatives.

Que fait réellement une API eSIM ?

L’expression « API eSIM » désigne plusieurs interfaces différentes.

API commerciale et produit

Cette interface expose les produits, prix, destinations, volumes, validités et règles commerciales. Un partenaire l’utilise pour constituer un catalogue ou sélectionner un produit pour une commande.

API de commande et de livraison

Elle crée une commande, réserve ou attribue un profil et renvoie les informations de livraison lorsqu’elles sont disponibles.

API de cycle de vie des profils

Selon le service et l’architecture de provisioning, elle peut exposer l’attribution du profil, l’état de téléchargement, les informations d’activation sur l’appareil, le remplacement ou d’autres actions de cycle de vie autorisées.

API de gestion de la connectivité

Elle peut exposer l’état de la SIM, du forfait, la consommation, le solde, les recharges, la suspension, la réactivation, les informations réseau et les alertes.

API d’administration des partenaires

Une plateforme destinée aux revendeurs ou aux entreprises peut fournir une hiérarchie de comptes, des autorisations, des listes de prix, des limites et des rapports.

Interfaces de provisioning SIM à distance

Les spécifications GSMA définissent les interfaces et procédures de sécurité utilisées par des composants tels que le SM-DP+, le Local Profile Assistant, l’eUICC, l’IoT Profile Assistant et l’eSIM IoT Remote Manager.

Ce ne sont pas les mêmes interfaces qu’une API commerciale publique. Une application de voyage appelle généralement l’API métier de son fournisseur. La plateforme fournisseur interagit ensuite avec le stock de profils et l’infrastructure de provisioning concernés par l’intermédiaire de systèmes contrôlés.

Cette distinction compte. Une réponse positive de l’API de commande peut signifier qu’un profil a été attribué et que les informations d’activation sont disponibles. Elle ne prouve pas que l’appareil du client a téléchargé le profil, l’a activé, s’est enregistré sur un réseau ou a consommé des données.

Une architecture de référence pratique

Un service typique en marque blanche fondé sur des API comporte les couches suivantes.

Pourquoi un service d’intégration est utile

Une boutique peut appeler directement un fournisseur, mais un backend dédié ou une couche d’intégration crée généralement une séparation plus sûre.

Il peut :

• garder les identifiants fournisseur hors des navigateurs et applications mobiles ;
• convertir le modèle de données du fournisseur en modèle interne de la marque ;
• appliquer les règles et limites métier ;
• joindre les références d’idempotence ;
• stocker les identifiants de requête et de réponse ;
• recevoir et vérifier les webhooks ;
• mettre le travail en file et réessayer sans risque ;
• protéger l’expérience client contre les changements en amont ;
• permettre l’utilisation ultérieure de plusieurs fournisseurs ;
• produire une piste d’audit pour l’assistance et la finance.

Le service d’intégration n’a pas besoin d’être une grande plateforme indépendante. Il peut être un module clairement séparé dans un backend existant. L’essentiel est que la logique propre au fournisseur ne se propage pas dans tous les composants destinés aux clients.

Définissez le système de référence pour chaque entité

Les systèmes distribués deviennent peu fiables lorsque la responsabilité des données est ambiguë.

Pour chaque entité importante, définissez le système faisant autorité et les systèmes conservant des copies synchronisées.

N’écrasez pas l’historique avec le dernier état

Stockez à la fois :

• l’état courant matérialisé utilisé par l’application ;
• un historique en ajout seul des requêtes, réponses, événements et actions manuelles importants.

Si une commande passe de pending à fulfilled, son enregistrement courant doit afficher fulfilled. L’historique d’audit doit toujours montrer quand elle a été créée, quelle requête API l’a initiée, quand le fournisseur l’a acceptée et quel événement a confirmé sa livraison.

Cette distinction est essentielle pour examiner les doubles débits, les livraisons retardées ou une action d’assistance contestée.

Utilisez un modèle métier clair

Une intégration eSIM ne doit pas traiter « une eSIM » comme une seule ligne de base de données contenant tous les états.

Les entités utiles comprennent généralement :

Produit

L’offre commerciale disponible à la vente, par exemple un forfait régional de 10 Go valable 30 jours. Elle peut comprendre la couverture par destination, le volume, les règles de validité, les services pris en charge et le prix de gros.

Commande

La demande commerciale d’acquisition d’un produit. Une commande possède son propre état, sa référence client, son prix et sa relation au paiement.

Profil

L’abonnement mobile téléchargeable associé aux identifiants de provisioning et à un état de cycle de vie. Un profil peut être lié à une commande, sans être la commande elle-même.

Relation SIM ou eUICC

Pour les SIM physiques ou l’IoT géré, le service peut modéliser séparément la carte, l’eUICC, l’EID, l’ICCID, l’appareil et l’équipement auquel ils sont affectés.

Forfait ou droit de consommation

Le volume et la validité que le client peut consommer. Une recharge peut créer un nouveau droit sans créer un nouveau profil.

Consommation

Les relevés de consommation ou soldes agrégés transmis par le fournisseur. La consommation doit inclure une heure d’observation ou de tarification, une unité et une source.

Opération de cycle de vie

Une action demandée, comme suspendre, réactiver, recharger, remplacer ou annuler. La demande peut être en attente avant de réussir ou d’échouer.

Événement

Une notification immuable indiquant qu’un fait s’est produit, identifiée indépendamment de la ressource concernée.

Séparer ces concepts évite des contradictions telles que « l’eSIM a été remboursée mais reste active ». Le remboursement concerne un paiement ou une commande, tandis que le profil et le forfait nécessitent leurs propres actions et états résultants.

Le workflow du catalogue

La première décision d’intégration concerne la manière dont les produits entrent dans la boutique.

Récupération du catalogue en direct

Le canal client ou le backend demande les produits au fournisseur au moment où il en a besoin.

Avantages :

• données fournisseur à jour ;
• moins de tâches de synchronisation ;
• accès rapide aux nouveaux produits.

Risques :

• achat dépendant de la disponibilité et de la latence du fournisseur ;
• propagation possible des détails de gros dans la logique destinée au client ;
• effet immédiat des changements de produit sur la boutique en ligne ;
• consommation des quotas API par les appels répétés.

Catalogue local synchronisé

La marque importe périodiquement les produits du fournisseur et publie les versions de détail approuvées depuis sa propre base.

Avantages :

• boutique plus rapide et mieux contrôlée ;
• titres, traductions, tarification et présentation commerciale locaux ;
• approbation explicite des changements fournisseur ;
• résilience en cas d’indisponibilité temporaire du catalogue fournisseur.

Risques :

• produits et prix pouvant devenir obsolètes ;
• nécessité de synchroniser et d’examiner les changements ;
• stock indisponible pouvant rester affiché.

Schéma de contrôle recommandé

Utilisez un catalogue synchronisé pour la présentation, mais validez les disponibilités critiques et les conditions commerciales actuelles avant de créer la commande fournisseur.

Stockez :

• l’identifiant produit fournisseur immuable ;
• la version fournisseur et locale, ou l’horodatage de dernière mise à jour ;
• la devise et le coût de gros ;
• l’identifiant du produit de détail ;
• les destinations et réseaux lorsqu’ils sont fournis ;
• le volume, la validité et la règle d’activation ;
• les restrictions de service ;
• l’état de commercialisation et le motif du retrait.

N’utilisez jamais un nom de produit traduit comme identifiant API.

Le workflow complet d’achat et de livraison

Un parcours client robuste peut être conçu comme une séquence de transitions d’état.

Étape 1 : valider le produit

Confirmez que le produit sélectionné est toujours commercialisable, que la destination et les règles de service correspondent à la commande et que le coût courant ne dépasse pas une limite commerciale définie.

Étape 2 : créer une commande locale

Générez votre propre identifiant de commande avant d’appeler des systèmes externes. Stockez le client, le produit, le prix de détail annoncé, la devise, le traitement fiscal et un instantané des conditions produit importantes.

Le produit peut changer ensuite. La commande historique doit toujours montrer ce que le client a acheté.

Étape 3 : autoriser ou encaisser le paiement

La séquence appropriée dépend du moyen de paiement et des règles du fournisseur.

Les schémas courants comprennent :

• autoriser le paiement, créer la commande fournisseur, puis capturer le paiement ;
• encaisser le paiement, créer la commande fournisseur, puis rembourser automatiquement si la livraison échoue ;
• réserver le stock fournisseur, encaisser le paiement, puis confirmer la livraison.

Chaque schéma crée un cas d’échec différent. Documentez ce qui se passe si le paiement réussit mais que la requête fournisseur expire, ou si le fournisseur livre une commande après un échec de capture du paiement.

Étape 4 : soumettre la commande fournisseur

Envoyez une référence partenaire stable et une valeur d’idempotence lorsque cela est pris en charge.

Une requête illustrative pourrait être :

POST /v1/orders HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json
Idempotency-Key: 7f5089ca-68d4-4e0e-91c3-f44d74c21c6a

{
  "partner_order_reference": "WEB-20260914-18427",
  "product_id": "regional-eu-10gb-30d",
  "quantity": 1
}

Une réponse d’acceptation illustrative pourrait être :

{
  "order_id": "ord_82h41",
  "partner_order_reference": "WEB-20260914-18427",
  "status": "processing",
  "created_at": "2026-09-14T13:05:28Z"
}

La requête et les noms de champs ci-dessus sont uniquement des exemples. Les intégrations réelles doivent suivre la documentation du fournisseur retenu.

Étape 5 : déterminer le résultat asynchrone

Le fournisseur peut renvoyer immédiatement les données de livraison ou poursuivre le traitement.

Votre intégration doit pouvoir obtenir le résultat par :

• un webhook ;
• la récupération de la ressource commande ;
• un point de terminaison d’état ;
• une tâche contrôlée de rapprochement.

Ne laissez pas une requête du navigateur client ouverte indéfiniment pendant que plusieurs systèmes externes terminent leur travail.

Étape 6 : stocker les données de livraison de manière sécurisée

Stockez l’identifiant de commande fournisseur, la référence de profil, les données d’activation autorisées et l’état commercial pertinent. Limitez l’accès aux informations d’activation, car une divulgation incontrôlée peut permettre à une autre personne d’installer le profil.

Étape 7 : fournir le parcours d’installation

Le client peut recevoir :

• un code QR ;
• une adresse SM-DP+ et un code d’activation ;
• un lien d’activation pris en charge par le système d’exploitation ;
• des instructions dans une application mobile ;
• une autre méthode d’activation prise en charge par le fournisseur.

Le code QR n’est pas le profil eSIM. Il représente normalement les informations utilisées par l’appareil pour lancer un processus sécurisé de provisioning.

Étape 8 : observer les événements ultérieurs du cycle de vie

Lorsque le fournisseur et la chaîne de provisioning les exposent, les états ultérieurs peuvent comprendre le téléchargement, l’installation, l’activation sur l’appareil, le premier enregistrement réseau, l’activation du forfait, la consommation et l’expiration.

Ne prétendez pas disposer d’une visibilité que les systèmes en amont ne fournissent pas. Certaines plateformes savent que les informations d’activation ont été émises, sans recevoir immédiatement un état d’installation sur l’appareil faisant autorité.

Concevez des machines à états explicites

Un seul champ d’état nommé active est trop vague pour une intégration en production.

Exemples d’états de commande

• created
• payment_pending
• payment_authorised
• submitted
• processing
• fulfilled
• failed
• cancelled
• refunded
• manual_review

Exemples d’états de profil

• unassigned
• allocated
• activation_data_issued
• downloaded
• enabled
• disabled
• deleted
• expired
• unknown

Exemples d’états de forfait

• pending
• available
• active
• depleted
• expired
• cancelled

Ce sont des états internes illustratifs. Le fournisseur peut employer d’autres termes et ne pas exposer toutes les transitions.

Conservez « inconnu » comme un véritable état

Les systèmes distribués créent de l’incertitude. Si une requête expire après soumission, l’état correct n’est pas automatiquement failed. Le fournisseur peut l’avoir reçue et exécutée.

Marquez le résultat comme inconnu ou en attente de rapprochement. Récupérez la ressource à l’aide de la référence partenaire stable ou de la clé d’idempotence avant de tenter une commande de remplacement.

Idempotence : éviter les commandes en double involontaires

Une opération est idempotente lorsque répéter la même requête voulue ne crée pas d’effet métier supplémentaire.

HTTP définit des méthodes telles que GET, PUT et DELETE comme idempotentes dans leur sémantique prévue. POST n’est pas idempotente par défaut, mais la création de commande utilise souvent POST. Un mécanisme d’idempotence au niveau métier est donc important.

Un schéma de commande sûr

1. Générer une clé d’idempotence unique pour l’achat voulu.
2. La conserver durablement avant d’envoyer la requête fournisseur.
3. Envoyer la même clé lors d’une nouvelle tentative de cette même opération.
4. Ne jamais la réutiliser pour un autre produit, client ou volume.
5. Stocker la réponse fournisseur associée à la clé.
6. Interroger la commande par référence partenaire après une réponse incertaine.

Le fournisseur doit définir :

• les points de terminaison prenant en charge l’idempotence ;
• la durée de conservation des clés ;
• la comparaison éventuelle des contenus de requête ;
• la réponse renvoyée pour une clé répétée ;
• le comportement lorsque la première requête est encore en traitement ;
• le traitement du conflit lorsque la même clé est réutilisée avec des données différentes.

L’idempotence ne remplace pas le rapprochement

Un défaut du client API ou du fournisseur peut encore créer des enregistrements incohérents. La finance et l’exploitation doivent comparer régulièrement les commandes locales, commandes fournisseur, profils attribués, paiements et factures.

Expirations de délai et stratégie de nouvelle tentative

Les nouvelles tentatives doivent dépendre de l’opération et du type d’échec.

Conditions permettant généralement une nouvelle tentative

• panne réseau temporaire ;
• connexion réinitialisée ;
• service fournisseur indisponible ;
• limite de débit explicite avec une indication exploitable de nouvelle tentative ;
• erreur serveur documentée comme transitoire.

Conditions nécessitant normalement correction ou examen

• identifiant produit invalide ;
• échec d’authentification ;
• autorisation insuffisante ;
• requête mal formée ;
• solde du compte ou limite de crédit insuffisants ;
• état de ressource incompatible ;
• rejet par une règle métier.

Utilisez un délai exponentiel borné avec variation aléatoire

Augmenter le délai entre les tentatives réduit le risque que de nombreux clients submergent simultanément un service en cours de rétablissement. Ajoutez une variation aléatoire, ou jitter, pour éviter que tous les processus réessaient au même instant.

Définissez :

• un nombre maximum de tentatives ;
• une durée totale maximale ;
• une file d’échec définitif ou une procédure d’examen manuel ;
• des alertes en cas d’échec prolongé ;
• des politiques distinctes pour les lectures et les opérations modifiant l’état.

Ne relancez jamais une création de commande au résultat incertain avec une nouvelle référence simplement parce que la première réponse HTTP n’a pas été reçue.

Webhooks : événements envoyés par le fournisseur

Les webhooks permettent au fournisseur de notifier le partenaire lorsqu’un événement asynchrone se produit.

Les événements possibles comprennent :

• commande livrée ou échouée ;
• profil attribué ;
• informations d’activation disponibles ;
• état du profil modifié ;
• forfait activé, épuisé ou expiré ;
• seuil de consommation atteint ;
• SIM suspendue ou réactivée ;
• recharge terminée ;
• produit ou prix modifié ;
• état d’incident ou de maintenance modifié.

Une enveloppe d’événement représentative

{
  "event_id": "evt_01J7S6A8QK",
  "event_type": "order.fulfilled",
  "occurred_at": "2026-09-14T13:05:31Z",
  "resource": {
    "type": "order",
    "id": "ord_82h41"
  },
  "data": {
    "partner_order_reference": "WEB-20260914-18427",
    "status": "fulfilled"
  }
}

Cet exemple n’est pas un schéma SIM24.biz.

Authentifiez l’expéditeur

Un point de terminaison webhook exposé à Internet ne doit pas faire confiance à une requête simplement parce qu’elle contient un identifiant de commande plausible.

Les contrôles courants comprennent :

• une signature calculée sur le corps exact de la requête ;
• un horodatage inclus dans les données signées ;
• une fenêtre d’acceptation étroite pour réduire le risque de rejeu ;
• une comparaison des signatures en temps constant ;
• la rotation du secret avec une période de chevauchement contrôlée ;
• le TLS mutuel pour les cas exigeant une assurance renforcée, lorsqu’il est pris en charge ;
• des contrôles réseau comme couche supplémentaire, et non comme seule méthode d’authentification.

La documentation du fournisseur doit définir l’algorithme de signature de référence et l’encodage. Analyser puis sérialiser le JSON avant vérification peut modifier les octets et faire échouer des signatures valides ou permettre des comparaisons non sécurisées au résultat inattendu. Vérifiez le corps brut reçu selon le schéma documenté.

Traitez les webhooks de manière asynchrone

Un consommateur fiable :

1. reçoit la requête ;
2. vérifie la taille et les exigences de transport de base ;
3. vérifie la signature et l’horodatage ;
4. stocke durablement l’événement et son identifiant ;
5. renvoie rapidement la réponse de succès documentée ;
6. traite l’effet métier via une file interne ou un processus de traitement ;
7. consigne le succès, la nouvelle tentative ou l’intervention manuelle.

N’effectuez pas de travail lent de livraison, d’e-mail ou de CRM avant d’accuser réception du webhook. Une réponse lente peut inciter le fournisseur à réessayer et multiplier les doublons.

Prévoyez les livraisons en double

La livraison au moins une fois est courante dans les systèmes événementiels. Un fournisseur réessaie parce qu’il ne peut pas savoir si le consommateur a stocké l’événement avant une coupure de connexion.

Stockez event_id avec une contrainte d’unicité. Retraiter le même événement ne doit pas provoquer un second remboursement, plusieurs e-mails de livraison ou une double application de recharge.

Prévoyez l’arrivée des événements dans le désordre

Un événement order.processing retardé peut arriver après order.fulfilled.

Utilisez :

• les numéros de version de ressource lorsqu’ils sont fournis ;
• les numéros de séquence du fournisseur ;
• l’heure de survenue de l’événement, avec prudence ;
• les règles de transition d’état autorisées ;
• la récupération de la ressource courante lorsqu’un événement contredit l’état local.

Ne remplacez pas aveuglément l’état courant par le dernier webhook reçu.

Traitez un webhook comme une notification, pas toujours comme la vérité complète

Pour les actions sensibles, utilisez l’événement pour déclencher la récupération de la ressource fournisseur courante. Cela réduit les données transportées par les événements et permet de confirmer l’état actuel via un appel API authentifié.

L’interrogation périodique et le rapprochement restent nécessaires

Les webhooks améliorent la réactivité mais ne doivent pas être l’unique mécanisme de synchronisation.

Des événements peuvent être manqués à cause :

• d’erreurs de configuration ;
• de secrets ou certificats expirés ;
• d’interruptions temporaires du récepteur ;
• de défauts de livraison du fournisseur ;
• de limites de conservation des événements ;
• d’un déploiement qui rejette des contenus valides.

Un processus de rapprochement peut comparer périodiquement :

• les commandes locales en attente avec l’état des commandes fournisseur ;
• les références de profil locales avec le stock attribué ;
• les demandes de recharge avec les droits de consommation créés ;
• les soldes des forfaits avec les relevés de consommation ;
• les remboursements avec les annulations fournisseur ;
• les totaux internes mensuels avec la facture fournisseur.

La fréquence du rapprochement doit refléter le risque métier. Une commande payée non livrée peut nécessiter une intervention en quelques minutes, tandis que le rapprochement de consommation au niveau facture peut être quotidien ou mensuel.

Authentification et autorisation

La sécurité API commence par identifier l’application ou le service appelant et limiter ce qu’il peut faire.

Gardez les identifiants sur des serveurs de confiance

N’intégrez jamais un secret fournisseur dans :

• du JavaScript de navigateur ;
• une application mobile publique ;
• un fichier de configuration téléchargeable ;
• du code source enregistré dans un dépôt ;
• des captures d’écran ou journaux d’assistance.

Les canaux client doivent appeler le backend de la marque, qui appelle ensuite le fournisseur avec des identifiants côté serveur.

Privilégiez les identifiants à durée de vie courte lorsqu’ils sont disponibles

Le flux client credentials d’OAuth 2.0 ou un autre mécanisme approprié d’identité de service peut émettre des jetons d’accès à durée limitée. La RFC 9700 fournit les bonnes pratiques de sécurité OAuth 2.0 et déconseille des schémas historiques non sécurisés.

Si le fournisseur utilise des clés API statiques, compensez avec :

• un stockage dans un gestionnaire de secrets ;
• une séparation stricte des environnements ;
• des autorisations à privilèges minimaux ;
• une rotation régulière ;
• une surveillance des usages inhabituels ;
• des procédures de révocation immédiate ;
• l’interdiction de partager une même clé entre applications ou partenaires sans lien.

L’authentification n’est pas l’autorisation

Un identifiant valide ne doit pas automatiquement donner accès à tous les partenaires, profils ou opérations.

Les contrôles doivent faire respecter :

• les frontières entre partenaires et espaces clients ;
• la propriété des ressources ;
• le catalogue produit autorisé ;
• les actions de cycle de vie autorisées ;
• les limites de dépense ou de volume ;
• le rôle d’administrateur ;
• la séparation des accès production et bac à sable.

L’OWASP API Security Top 10 2023 cite notamment les défaillances d’autorisation au niveau des objets, d’authentification, d’autorisation au niveau des fonctions et l’accès sans restriction aux flux métier sensibles parmi les principaux risques API.

Protégez plus fortement les opérations administratives

La création d’identifiants, la suspension en masse, les changements de prix, l’approbation de remboursements et l’exportation des données peuvent nécessiter :

• une authentification multifacteur ;
• l’approbation d’une seconde personne ;
• une authentification renforcée au moment de l’action ;
• des restrictions sur les réseaux d’origine ;
• des journaux d’audit détaillés ;
• une notification aux équipes de sécurité ou de finance.

Sécurité des requêtes, réponses et données

Sécurité du transport

Utilisez des configurations TLS actuelles et validez correctement les certificats. Ne désactivez pas leur vérification pour résoudre un problème d’environnement de test.

Validation des entrées

Validez le type, la longueur, le format, les valeurs autorisées et le sens métier. Un document JSON valide peut tout de même demander une quantité impossible, un produit non autorisé ou un périmètre d’export dangereux.

Minimisation des sorties

Ne renvoyez que les champs nécessaires à l’appelant. Évitez d’exposer les secrets en amont, identifiants réseau internes, informations personnelles ou données d’activation complètes à des rôles non autorisés.

Journaliser sans divulguer

Les journaux doivent fournir assez d’informations pour le diagnostic, notamment :

• l’identifiant de corrélation ;
• la référence de commande partenaire ;
• l’identifiant de requête fournisseur ;
• le point de terminaison et la catégorie de résultat ;
• les durées et le nombre de tentatives ;
• les identifiants de ressource pertinents ;
• l’identité de l’acteur ou du service.

Masquez ou excluez :

• les jetons d’accès et clés API ;
• les secrets et signatures de webhooks ;
• les données de carte de paiement ;
• les données d’authentification ;
• les données personnelles inutiles ;
• les codes d’activation complets lorsqu’ils ne sont pas nécessaires à l’assistance.

Protection des données

Déterminez les données personnelles nécessaires au fournisseur et leur finalité. Pour les services soumis au RGPD, définissez les rôles de responsable et de sous-traitant par activité, concluez les clauses de traitement requises, listez les sous-traitants ultérieurs, contrôlez les transferts internationaux et établissez des procédures de conservation et de suppression.

Une intégration API doit permettre la minimisation des données. Si le fournisseur peut livrer une commande eSIM avec une référence de commande partenaire, il n’a peut-être pas besoin du profil marketing complet du client ni de détails de réservation sans rapport.

Protégez les workflows métier sensibles

De nombreuses attaques API n’exploitent pas un paquet mal formé. Elles automatisent une fonction valide à une échelle abusive.

Exemples :

• créer de nombreux profils avec des moyens de paiement volés ;
• demander de manière répétée des informations d’activation de remplacement ;
• énumérer les identifiants de commande ou de profil ;
• abuser des produits promotionnels ;
• déclencher des recharges coûteuses ;
• exporter un volume excessif de données client ;
• épuiser le stock fournisseur ou les quotas API.

Les contrôles peuvent comprendre :

• des limites de débit par partenaire et par opération ;
• des seuils de dépense et de volume ;
• des contrôles de risque sur le paiement et le compte ;
• la validation des états attendus ;
• l’approbation des opérations groupées à haut risque ;
• la détection des anomalies ;
• des coupe-circuits ;
• des protections du stock ;
• un examen manuel des comportements exceptionnels.

Une limite technique de débit ne constitue pas, à elle seule, une stratégie antifraude. Dix requêtes autorisées peuvent être nuisibles si chacune achète un produit coûteux.

Gestion des versions API et des changements

Les services de connectivité évoluent. Les produits, réseaux, relations fournisseur et interfaces logicielles changent.

Le fournisseur doit documenter :

• l’approche de gestion des versions ;
• la politique de rétrocompatibilité ;
• le délai de dépréciation ;
• les notes de version ;
• la définition d’un changement incompatible ;
• la disponibilité en bac à sable avant changement en production ;
• la méthode d’annonce des changements urgents ;
• la prise en charge de versions coexistantes ;
• le traitement des ajouts de valeurs d’énumération et de nouveaux champs facultatifs.

Construisez des lecteurs tolérants, pas négligents

Un consommateur doit normalement tolérer un nouveau champ facultatif. Il ne doit pas accepter silencieusement une valeur inconnue qui modifie le sens financier ou le cycle de vie.

Par exemple, un nouvel état de commande doit placer l’enregistrement dans un état explicite inconnu ou à examiner, au lieu d’être interprété comme une commande livrée.

Utilisez une documentation lisible par machine

La spécification OpenAPI fournit un format standard de description des API HTTP. Une spécification maintenue peut servir à générer des clients, valider les données, alimenter les outils de test et produire la documentation.

Une documentation lisible par machine n’est pas automatiquement correcte. Comparez-la au comportement réel du bac à sable et aux notes de version.

Observabilité et surveillance opérationnelle

Une intégration n’est pas terminée tant que les opérateurs ne peuvent pas voir si elle fonctionne.

Indicateurs techniques

• nombre de requêtes par point de terminaison et résultat ;
• percentiles de latence ;
• taux d’expiration de délai et d’erreur de connexion ;
• échecs d’authentification ;
• réponses de limitation de débit ;
• volume de nouvelles tentatives ;
• échecs de signature de webhook ;
• délai de traitement des webhooks ;
• longueur de file et ancienneté du plus vieux message ;
• nombre de messages en échec définitif.

Indicateurs métier

• commandes payées en attente de livraison ;
• taux de réussite et délai de livraison ;
• profils attribués mais non délivrés ;
• état d’installation ou d’activation lorsqu’il est disponible ;
• délai d’exécution des recharges ;
• taux de remboursement et de remplacement ;
• écarts de rapprochement entre commandes locales et fournisseur ;
• écarts de consommation et de facturation ;
• marge par produit ;
• contacts d’assistance par commande.

Identifiants de corrélation

Reliez les enregistrements client, paiement, commande locale, commande fournisseur, profil et événement par des identifiants stables. Propagez un identifiant de corrélation dans les services internes et conservez l’identifiant de requête ou de trace du fournisseur lorsqu’il est fourni.

Un agent d’assistance doit pouvoir partir du numéro de commande client et accéder aux preuves techniques pertinentes sans chercher manuellement dans plusieurs systèmes sans lien.

Les alertes doivent indiquer une action

« Les erreurs API ont augmenté » est moins utile que :

« La création des commandes fournisseur dépasse le seuil d’échec convenu depuis dix minutes ; 28 commandes payées restent en attente ; les nouvelles tentatives automatiques sont suspendues ; le responsable de l’incident est l’équipe d’exploitation des intégrations. »

Chaque alerte doit préciser la gravité, le workflow touché, l’impact client, l’équipe responsable et l’action immédiate.

Gérer les pannes du fournisseur

L’expérience client doit se dégrader de manière sûre lorsque le service en amont est indisponible.

Les contrôles possibles comprennent :

• un coupe-circuit après des échecs répétés ;
• une mise en file des livraisons avec un message client clair ;
• le retrait temporaire des produits touchés ;
• le blocage de nouvelles captures de paiement lorsque la livraison ne peut pas être achevée sans risque ;
• une page d’état et une notification à l’assistance ;
• un rapprochement au retour du service ;
• une livraison manuelle contrôlée pour les cas approuvés ;
• un basculement vers un autre fournisseur uniquement lorsque les produits et les règles commerciales sont réellement compatibles.

Ne basculez pas automatiquement vers un produit alternatif dont la couverture, les règles d’activation ou les restrictions diffèrent sans contrôles commerciaux et vis-à-vis du client.

Décidez à l’avance du traitement du paiement

Pour chaque point de défaillance, précisez si le système doit :

• conserver l’autorisation ouverte ;
• capturer le paiement plus tard ;
• annuler l’autorisation ;
• émettre un remboursement automatique ;
• mettre la commande en attente d’examen manuel ;
• proposer un choix au client.

Cette décision relève du produit, de la finance et des opérations client, pas seulement du développeur API.

Exigences du bac à sable et de l’environnement de test

Un bac à sable utile doit prendre en charge davantage qu’une réponse réussie.

Demandez s’il peut simuler :

• le traitement et une livraison retardée ;
• un échec permanent ;
• une erreur serveur transitoire ;
• une expiration de délai de requête ;
• une limitation de débit ;
• une clé d’idempotence dupliquée ;
• un webhook dupliqué ;
• un webhook reçu dans le désordre ;
• une signature de webhook invalide ;
• un profil indisponible ;
• l’activation et l’expiration du forfait ;
• les seuils de consommation ;
• la réussite et l’échec d’une recharge ;
• la suspension et la réactivation ;
• un export de facturation ou de consommation.

Le fournisseur doit expliquer les différences entre bac à sable et production, notamment le catalogue produit, l’authentification, les limites de débit, la conservation des données et la livraison des webhooks.

Stratégie de test

Tests de contrat d’interface

Vérifiez que les requêtes et réponses correspondent au schéma convenu, aux champs requis, aux types et aux valeurs autorisées.

Tests des transitions d’état

Testez les transitions autorisées et rejetées. Une commande annulée ne doit pas revenir en traitement sans parcours de récupération défini.

Tests d’idempotence

Répétez la même requête de commande avant et après son achèvement. Vérifiez qu’un seul effet métier se produit.

Tests par injection de défaillances

Provoquez des expirations de délai, événements retardés, dépendances indisponibles et échecs internes partiels. Confirmez que le système atteint un état récupérable.

Tests de sécurité

Testez l’isolation des partenaires, l’autorisation au niveau des objets, la révocation des identifiants, les signatures de webhook, le traitement du rejeu, les limites d’entrée et l’exposition de données sensibles.

Tests de charge et de pics

Utilisez des volumes convenus avec le fournisseur. Testez le débit habituel et les pics causés par des campagnes, des perturbations de voyage ou des opérations IoT groupées.

Tests de bout en bout sur appareils

Pour des produits et appareils représentatifs, testez le parcours complet :

1. récupérer le produit ;
2. créer et payer la commande ;
3. recevoir les informations du profil ;
4. télécharger et installer l’eSIM ;
5. l’activer sur l’appareil ;
6. s’enregistrer sur un réseau autorisé ;
7. utiliser le service prévu ;
8. observer la consommation ou le solde ;
9. appliquer une recharge ou une opération de cycle de vie autorisée ;
10. rapprocher la transaction.

Un test API qui s’arrête à une réponse 200 OK n’a pas testé la connectivité mobile.

Rapprochement financier

La réussite technique et l’exactitude commerciale sont différentes.

Créez des contrôles quotidiens ou périodiques comparant :

• les paiements capturés ;
• les commandes locales ;
• les commandes fournisseur ;
• les profils ou SIM attribués ;
• les forfaits délivrés ;
• les annulations et remboursements ;
• les frais de consommation ;
• les factures de gros ;
• les commissions revendeur ;
• les taxes et devises.

Exemples d’anomalies

• paiement capturé, aucune commande fournisseur ;
• commande fournisseur livrée, paiement échoué ;
• deux commandes fournisseur liées à une commande locale ;
• remboursement émis, forfait actif conservé de manière inattendue ;
• recharge facturée deux fois ;
• consommation dépassant la règle commerciale attendue ;
• prix de gros différent de l’instantané de catalogue importé ;
• facture contenant un profil ou une référence partenaire inconnus.

Chaque anomalie doit entrer dans une file contrôlée avec un responsable, une valeur financière et un historique de résolution.

La documentation nécessaire à votre équipe

Une intégration en production exige davantage que des pages de référence des points de terminaison.

Demandez et maintenez :

• un guide d’authentification ;
• le processus d’environnements et d’identifiants ;
• une définition d’interface OpenAPI ou équivalente ;
• le modèle de données et les descriptions d’état ;
• un catalogue des erreurs ;
• les règles d’idempotence ;
• les limites de débit ;
• la sécurité des webhooks et la politique de nouvelle tentative ;
• le processus de changement des produits et prix ;
• la politique de publication et de dépréciation ;
• les contacts d’assistance et d’escalade ;
• le processus d’incident et de maintenance ;
• le guide de rapprochement et de facturation ;
• les informations de protection et de conservation des données ;
• les informations de continuité d’activité.

La documentation interne doit ajouter :

• un registre des décisions d’architecture ;
• une matrice des systèmes de référence ;
• des diagrammes de séquence et d’état ;
• la procédure de rotation des secrets ;
• les tableaux de bord et alertes opérationnels ;
• les procédures de gestion d’incident ;
• les contrôles de livraison et de remboursement manuels ;
• le processus de mise en production et de retour arrière.

Liste de contrôle pratique avant mise en production

Architecture et données

• □Chaque entité principale possède un système de référence défini.
• □Les identifiants fournisseur sont stockés séparément des identifiants locaux.
• □Les transitions d’état et résultats inconnus sont modélisés explicitement.
• □Les champs sensibles et règles de conservation sont documentés.

Commandes et paiements

• □La création de commande possède une stratégie d’idempotence.
• □Les scénarios d’expiration de délai et de doublon ont été testés.
• □Le comportement de capture, d’annulation d’autorisation et de remboursement est défini pour chaque point d’échec.
• □Le rapprochement détecte les écarts entre paiements et commandes fournisseur.

Webhooks et traitement asynchrone

• □Les signatures et horodatages sont correctement vérifiés.
• □Les événements dupliqués ou reçus dans le désordre sont traités sans risque.
• □Les événements sont stockés avant l’envoi de l’accusé de réception.
• □Les traitements échoués atteignent une file visible de nouvelle tentative ou d’examen manuel.
• □L’interrogation périodique ou le rapprochement couvre les événements manqués.

Sécurité

• □Aucun secret fournisseur n’existe dans un navigateur ou une application mobile.
• □Les identifiants de production et de bac à sable sont distincts.
• □Les identifiants ont des privilèges minimaux et une procédure de rotation testée.
• □L’autorisation par partenaire et au niveau des objets a été testée.
• □Les journaux excluent les secrets, données de paiement et informations personnelles inutiles.
• □Les actions administratives et groupées sont auditées.

Exploitation

• □Les tableaux de bord techniques et métier sont opérationnels.
• □Les alertes identifient un responsable et une action.
• □L’assistance peut relier une commande client aux références fournisseur et profil.
• □Les procédures d’escalade fournisseur et de panne ont été répétées.
• □Le retrait des produits peut être effectué rapidement.

Préparation commerciale

• □Les changements de prix du catalogue sont contrôlés.
• □La consommation et les factures peuvent être rapprochées.
• □Les conditions publiées correspondent aux comportements d’activation, validité, remboursement et remplacement.
• □Les tests représentatifs d’appareils et de réseaux ont réussi.
• □Un responsable de la décision de retour arrière ou de suspension du lancement est désigné.

Erreurs d’intégration courantes

Appeler le fournisseur directement depuis l’application mobile

Cela expose les identifiants ou impose des compromis d’authentification dangereux. Utilisez un backend contrôlé.

Considérer une expiration de délai comme une commande échouée

La commande peut être terminée. Récupérez-la ou rapprochez-la avant d’en créer une autre.

Utiliser les e-mails ou noms de produit comme identifiants

Les noms changent et les données client ne doivent pas devenir une clé technique. Utilisez des identifiants immuables.

Supposer que les webhooks arrivent une seule fois et dans l’ordre

Prévoyez les nouvelles tentatives, doublons, retards et réordonnancements.

Envoyer deux fois la livraison

Les événements en double ou nouvelles tentatives peuvent provoquer plusieurs e-mails et de la confusion. Rendez chaque effet secondaire idempotent.

Exposer trop largement le code QR

Les informations d’activation doivent être accessibles uniquement aux clients et rôles d’assistance autorisés.

Journaliser tous les contenus sans masquage

Cela peut copier des identifiants, données personnelles et informations d’activation dans plusieurs systèmes de journaux.

Mélanger les états de commande et de connectivité

Une commande livrée peut contenir un profil non installé. Un profil activé peut avoir un forfait expiré. Gardez les cycles de vie distincts.

Ignorer la finance jusqu’à la fin du mois

Les anomalies quotidiennes sont plus faciles à examiner que des milliers d’écarts inexpliqués sur une facture.

Construire uniquement le parcours réussi

L’essentiel de la complexité d’intégration réside dans les opérations incertaines, retardées et partiellement achevées.

La place de SIM24.biz dans un service fondé sur des API

SIM24.biz accompagne les entreprises qui construisent des offres de connectivité SIM, eSIM et IoT sous leur propre marque. Un modèle fondé sur des API peut permettre au partenaire de conserver son site web, son application, ses paiements, son CRM, ses outils d’analyse et sa relation client tout en intégrant les fonctions de connectivité nécessaires.

La frontière d’intégration appropriée dépend du projet. Un partenaire peut utiliser un parcours client complet en marque blanche. Un autre peut utiliser les API pour le catalogue, la livraison et les fonctions de cycle de vie tout en possédant toute l’interface utilisateur. Un troisième peut combiner les stocks de SIM physiques et d’eSIM avec des opérations d’entreprise ou IoT.

Les points de terminaison exacts, méthodes d’authentification, webhooks, états visibles du cycle de vie, limites, fonctions de bac à sable et niveaux de service disponibles auprès de SIM24.biz doivent être confirmés pour l’implémentation et la combinaison de fournisseurs retenues. Les schémas et noms de points de terminaison de cet article sont illustratifs et ne doivent pas être présentés comme la documentation API actuelle de SIM24.biz.

Un cadrage technique rigoureux doit définir :

• le parcours client cible ;
• les systèmes de référence ;
• les produits et marchés requis ;
• les flux d’intégration et d’événements ;
• le modèle de paiement et de rapprochement ;
• les responsabilités de sécurité et de données ;
• les scénarios du pilote ;
• les responsabilités opérationnelles après lancement.

Conclusion

Une intégration API eSIM réussit lorsque les clients reçoivent une connectivité fiable et que l’entreprise peut expliquer chaque commande, profil, paiement et anomalie.

L’appel API n’est qu’une partie de ce résultat. La conception complète doit gérer la livraison asynchrone, les états de cycle de vie indépendants, les opérations idempotentes, les webhooks vérifiés, les réponses incertaines, les identifiants sécurisés, la surveillance opérationnelle et le rapprochement financier.

La meilleure architecture crée des frontières claires. La marque maîtrise son client et sa logique commerciale. La couche d’intégration contrôle les dépendances externes. Le fournisseur fournit des capacités définies de plateforme, provisioning et connectivité. Chaque partie peut identifier l’état qu’elle connaît et l’action dont elle est responsable.

Construisez les parcours d’échec avant le lancement, pas lorsque le premier client ayant payé attend déjà son profil.

Questions fréquentes

Qu’est-ce qu’une API eSIM ?

Une API eSIM est une interface métier par laquelle un partenaire autorisé accède à des fonctions telles que la récupération des produits, les commandes, la livraison des profils, les états, la consommation, les recharges ou la gestion du cycle de vie. Son périmètre exact dépend du fournisseur.

Une API eSIM se connecte-t-elle directement à l’eUICC ?

Normalement, une API métier de détail ou en marque blanche se connecte à la plateforme fournisseur. La livraison sécurisée du profil à l’eUICC utilise l’architecture et les composants de provisioning pertinents, tels que le SM-DP+ et le Local Profile Assistant dans le modèle grand public.

Pourquoi les commandes eSIM sont-elles asynchrones ?

Le fournisseur peut devoir attribuer du stock, effectuer du provisioning ou coordonner d’autres systèmes. Renvoyer une ressource en attente permet à la requête client de se terminer sans attendre indéfiniment.

Qu’est-ce qu’une clé d’idempotence ?

C’est une valeur unique représentant une opération voulue de modification d’état. Lorsque la même requête doit être relancée, réutiliser la clé aide à éviter un effet métier en double involontaire si le fournisseur prend en charge ce comportement.

Dois-je relancer une commande eSIM après expiration du délai ?

Traitez d’abord le résultat comme inconnu. Récupérez la commande avec la référence partenaire ou le mécanisme d’idempotence du fournisseur. Réessayez uniquement selon les règles documentées et utilisez le même identifiant pour la même opération voulue.

Comment sécuriser un webhook eSIM ?

Vérifiez la signature du fournisseur sur la requête brute selon le schéma documenté, contrôlez un horodatage signé ou un mécanisme anti-rejeu, limitez la taille du contenu, stockez l’identifiant d’événement et traitez l’événement de manière idempotente. Le TLS mutuel peut convenir à certaines intégrations exigeant une assurance renforcée.

Les webhooks sont-ils garantis comme arrivant une seule fois ?

Ne concevez pas le système sur cette hypothèse. Les consommateurs doivent tolérer les événements dupliqués, retardés et reçus dans le désordre, et utiliser le rapprochement pour détecter les changements manqués.

Faut-il stocker le code QR ?

Stockez uniquement ce qui est nécessaire au parcours client et de récupération pris en charge, protégez-le comme une information sensible de livraison et limitez l’accès. Confirmez les règles de conservation et de réaffichage avec le fournisseur.

Que doit inclure un bac à sable API eSIM ?

Il doit prendre en charge des scénarios représentatifs de réussite et d’échec, notamment l’achèvement asynchrone, les requêtes en double, les nouvelles tentatives de webhook, les signatures invalides, les limites de débit, les changements de cycle de vie et les données de rapprochement.

Comment stocker les identifiants API ?

Conservez-les dans un système de gestion des secrets côté serveur, séparez les environnements et privilèges, appliquez une rotation selon une procédure testée et ne les placez jamais dans le code du navigateur ou d’une application mobile.

Comment changer de fournisseur eSIM ultérieurement ?

Gardez la logique propre au fournisseur derrière une couche d’intégration, utilisez des identifiants internes et des modèles métier, conservez des exports complets et négociez les droits de transition. Les profils actifs peuvent encore nécessiter une migration technique ou un remplacement plutôt qu’un simple changement de base de données.

Une intégration API est-elle meilleure qu’une plateforme complète en marque blanche ?

Elle offre plus de contrôle sur l’expérience client et les systèmes, mais nécessite du développement et une responsabilité opérationnelle permanente. Une plateforme complète en marque blanche peut permettre un lancement plus rapide. Le bon modèle dépend de la différenciation, des ressources et de l’échelle.

Connectez les services eSIM et SIM aux systèmes que vous possédez déjà

SIM24.biz aide les partenaires à définir des parcours de connectivité sous leur marque, les frontières d’intégration et les exigences du pilote autour de leurs plateformes commerciales et client existantes.

Échangez avec SIM24.biz sur le modèle API ou en marque blanche adapté à votre service.

Sources

1. GSMA, « SGP.22 v2.7, eSIM Consumer Technical Specification » : https://www.gsma.com/solutions-and-impact/technologies/esim/gsma_resources/sgp-22-v2-7/
2. GSMA, « SGP.31 v1.3, eSIM IoT Architecture and Requirements » : https://www.gsma.com/solutions-and-impact/technologies/esim/gsma_resources/sgp-31-v1-3/
3. GSMA, « SGP.32 v1.3, eSIM IoT Technical Specification » : https://www.gsma.com/solutions-and-impact/technologies/esim/gsma_resources/sgp-32-v1-3/
4. IETF, « RFC 9110, HTTP Semantics » : https://www.rfc-editor.org/rfc/rfc9110.html
5. IETF, « RFC 9700, Best Current Practice for OAuth 2.0 Security » : https://www.rfc-editor.org/rfc/rfc9700.html
6. IETF, « RFC 8725, JSON Web Token Best Current Practices » : https://www.rfc-editor.org/rfc/rfc8725.html
7. OpenAPI Initiative, « OpenAPI Specification v3.1.1 » : https://spec.openapis.org/oas/v3.1.1.html
8. Cloud Native Computing Foundation, « CloudEvents Specification » : https://github.com/cloudevents/spec/blob/main/cloudevents/spec.md
9. OWASP Foundation, « OWASP API Security Top 10, 2023 » : https://owasp.org/API-Security/editions/2023/en/0x11-t10/
10. Union européenne, « Règlement (UE) 2016/679, règlement général sur la protection des données » : https://eur-lex.europa.eu/eli/reg/2016/679/oj/eng
11. Comité européen de la protection des données, « Guidelines 07/2020 on the concepts of controller and processor in the GDPR » : https://www.edpb.europa.eu/our-work-tools/our-documents/guidelines/guidelines-072020-concepts-controller-and-processor-gdpr_en