Comment les produits intègrent des API
Une intégration réelle, du début à la fin
Vous avez appris toutes les briques de base : JSON, requêtes, REST, authentification, documentation, webhooks. Maintenant, assemblons le tout.
Voici le scénario. Vous êtes PM dans une entreprise e-commerce. L'équipe veut envoyer un SMS de confirmation quand un client passe une commande. Votre application n'envoie pas de SMS, donc vous avez besoin d'un service externe. Ce service, c'est Twilio.
Voyons exactement comment cette intégration fonctionne, étape par étape.
Étape 1 : le besoin produit
Un client passe une commande sur votre site. Vous voulez qu'il reçoive immédiatement un SMS : "Votre commande #4821 a été confirmée. Livraison estimée : 8 mars."
Votre application gère la commande. Mais envoyer un SMS ? Ce n'est pas quelque chose que vous construisez de zéro. Vous utilisez un service spécialisé. Twilio a une API qui envoie des SMS. Votre serveur appelle l'API de Twilio, Twilio délivre le SMS sur le téléphone du client.
C'est le schéma derrière la plupart des intégrations. Votre produit se concentre sur ce qu'il fait le mieux (gérer les commandes), et une API externe s'occupe du reste (envoyer des SMS).
Étape 2 : trouver le bon endpoint
Votre développeur va sur la documentation de l'API Twilio et trouve le endpoint pour envoyer un message. Voici à quoi ressemble la requête :
Cela devrait vous sembler familier depuis le chapitre 2 :
- POST parce que vous créez quelque chose (un nouveau message)
- L'URL de base est le serveur API de Twilio
- Le path pointe vers la ressource Messages sous votre compte. Il a un format un peu inhabituel :
/2010-04-01/est une date de version (la façon dont Twilio versionne son API),{AccountSid}est l'identifiant unique de votre compte, et.jsonà la fin indique à Twilio que vous voulez la réponse en JSON. Toutes les API ne formatent pas leurs URL de cette façon, mais la logique est la même : version, compte, ressource.
Étape 3 : s'authentifier
Au chapitre 4, vous avez vu des clés API envoyées avec Authorization: Bearer your_api_key. Twilio utilise une méthode légèrement différente appelée Basic Authentication. Au lieu d'une seule clé API, vous avez deux valeurs : un Account SID (votre identifiant) et un Auth Token (votre mot de passe). Ils sont combinés en une seule chaîne séparée par deux-points, puis encodés dans un format appelé base64.
Voici ce que ça donne concrètement. Vos deux identifiants :
- Account SID :
AC1234567890abcdef - Auth Token :
e9f8a7b6c5d4e3f2
Sont combinés en AC1234567890abcdef:e9f8a7b6c5d4e3f2, puis encodés en base64 : QUMxMjM0NTY3ODkwYWJjZGVmOmU5ZjhhN2I2YzVkNGUzZjI=. Cette chaîne encodée est placée dans le header :
Ne vous inquiétez pas pour l'encodage en lui-même. Le code de votre équipe technique gère ça automatiquement. Ce qu'il faut retenir : Basic Auth est simplement une autre façon d'envoyer des identifiants dans le header Authorization. Certaines API utilisent Bearer + une seule clé, d'autres utilisent Basic + un combo identifiant:mot de passe encodé. La documentation vous indique toujours lequel utiliser.
Le body contient trois champs : le numéro de téléphone du destinataire, votre numéro Twilio, et le texte du message. C'est tout ce dont Twilio a besoin pour envoyer un SMS.
Étape 4 : recevoir la réponse
Twilio traite la requête et renvoie une réponse JSON confirmant que le message a été créé :
Le status: "queued" signifie que Twilio a accepté le message et va le délivrer sous peu. Le sid est l'identifiant unique de ce message (comme un numéro de commande, mais pour le SMS).
Étape 5 : le callback webhook
Mais comment savoir si le SMS a réellement été délivré ? Peut-être que le numéro est faux. Peut-être que l'opérateur l'a bloqué. C'est là qu'interviennent les webhooks (chapitre 6).
Quand vous avez configuré l'intégration, votre équipe a enregistré une URL de webhook chez Twilio. Maintenant, quand le statut du SMS change, Twilio envoie une requête POST à votre serveur :
Votre serveur reçoit cette requête, voit "MessageStatus": "delivered", et sait que le client a bien reçu le SMS. Si le statut avait été "failed", votre serveur pourrait le signaler et envoyer un email à la place.
Vue d'ensemble
Chaque étape de cette intégration correspond à un concept que vous connaissez déjà :
| Étape | Ce qui se passe | Concept (chapitre) |
|---|---|---|
| 1. Identifier le besoin | Nous devons envoyer des SMS, donc nous choisissons Twilio | API en tant que service (ch. 2) |
| 2. Trouver le endpoint | POST /Messages.json dans la doc de Twilio | REST + documentation API (ch. 3, 5) |
| 3. S'authentifier | Envoyer Account SID + Auth Token dans le header | Authentification (ch. 4) |
| 4. Envoyer la requête | POST avec le numéro de téléphone et le corps du message (JSON) | Requêtes + JSON (ch. 1, 2) |
| 5. Lire la réponse | Twilio renvoie un objet JSON avec status: queued | Réponses + JSON (ch. 1, 2) |
| 6. Recevoir le webhook | Twilio envoie un POST quand le SMS est délivré ou échoue | Webhooks (ch. 6) |
Voilà pour une intégration. Mais ce même schéma se répète partout : envoyer des emails (Postmark), traiter des paiements (Stripe), générer des PDF (DocSpring), traduire du texte (DeepL). Le service change, mais le flux est le même. Trouver le endpoint, s'authentifier, envoyer une requête, traiter la réponse, écouter les webhooks.
Points clés
- La plupart des fonctionnalités produit qui reposent sur des services externes suivent le même schéma d'intégration : trouver le endpoint, s'authentifier, envoyer une requête, traiter la réponse.
- Les webhooks bouclent la boucle en notifiant votre serveur quand quelque chose se passe de manière asynchrone (comme un SMS délivré ou échoué).
- Chaque étape correspond directement à un concept que vous avez déjà appris. Il n'y a rien de nouveau ici, juste toutes les pièces qui fonctionnent ensemble.