Réponse en bref
Une API est un ensemble de règles qui permet à un logiciel de demander des données ou une action à un autre sans qu’une personne passe par les écrans. La requête part vers une adresse avec une clé, la réponse revient avec un code d’état. Le service propriétaire de l’API fixe les limites, le prix et les versions : une intégration demande donc un responsable des clés, un journal des erreurs et quelqu’un qui suit les changements.
Une API est un guichet pour les logiciels, pas pour les personnes
Le prestataire annonce que le site et le CRM seront reliés par l’API, et le dirigeant acquiesce sans image en tête. Alors, qu’est-ce qu’une API, dit sans jargon de développeur ? MDN Web Docs la définit comme un ensemble de fonctionnalités et de règles présentes dans un logiciel, qui permettent d’interagir avec lui par un autre logiciel plutôt que par une interface humaine. MDN ajoute qu’on peut y voir un simple contrat entre l’application et les logiciels qui s’en servent.
Wikipédia le dit depuis l’autre rive : une interface utilisateur relie un ordinateur à une personne, une API relie des logiciels entre eux. Prenez une banque : vous voyez des écrans et des boutons dans son application, votre logiciel de comptabilité voit un guichet avec une liste fixe de formulaires. Il remet un formulaire convenu, reçoit une réponse convenue et n’entre jamais dans les bureaux. Wikipédia y voit l’un des buts principaux d’une API : masquer les détails internes du fonctionnement d’un système.
De quoi sont faites une requête et une réponse, sans code
Les API que croise une petite entreprise sont presque toujours des API web. Telegram, par exemple, décrit sa Bot API comme une interface fondée sur HTTP. MDN présente HTTP comme un échange de messages : le client envoie des requêtes, le serveur renvoie des réponses. Une requête comporte une méthode, un verbe comme GET ou POST, le chemin de la ressource, des en-têtes facultatifs et parfois un corps. En langage de boutique, ce sont l’action, l’adresse du guichet, une mention de qui demande et le formulaire lui-même.
La réponse porte un code d’état qui, d’après MDN, indique si la requête a réussi et, sinon, pourquoi. MDN range ces codes en cinq classes : de 200 à 299 pour le succès, de 400 à 499 pour une erreur du client, de 500 à 599 pour une erreur du serveur. L’essentiel pour un dirigeant est que chaque échange laisse une trace. Un vague « l’intégration ne marche pas » devient alors une question précise : ce qui a été envoyé, et quel code est revenu.
Ce qu’une petite entreprise relie concrètement par des API
Les liaisons courantes sont peu nombreuses. Un formulaire du site transmet le nouveau contact au CRM, et personne ne le recopie depuis un e-mail. Le site demande à un service de paiement de créer un règlement, puis apprend qu’il a été payé. Une boutique interroge le transporteur sur le coût de livraison et le numéro de suivi. Les commandes arrivent dans le logiciel de comptabilité, et un bot de messagerie prévient le commercial dès qu’il en arrive une.
Tous les logiciels n’ont pas de guichet, et tous les guichets ne vous sont pas ouverts. Wikipédia distingue trois politiques de diffusion : une API privée est réservée à l’usage interne de l’entreprise, une API partenaire à des partenaires commerciaux précis, une API publique est accessible à tous. Vérifiez donc d’abord que le service déjà payé possède une API et que votre formule l’inclut. Une API n’offre en outre que ce que son propriétaire a choisi d’exposer : si une action manque dans la documentation, aucun prestataire ne pourra l’appeler.
Une clé d’API est un mot de passe, sa fuite une porte ouverte
Le guichet doit savoir qui demande : c’est le rôle de la clé. YooKassa, un service de paiement russe, prend l’identifiant de la boutique comme nom d’utilisateur et une clé secrète comme mot de passe. Le guide de Stripe sur les clés le dit sans détour : les clés secrètes sont des identifiants du compte, comme un nom d’utilisateur et un mot de passe. Qui en obtient une peut, selon ce guide, effectuer des débits non autorisés, lire les données des clients ou perturber l’intégration. Stripe ajoute que des acteurs malveillants fouillent sans cesse les dépôts de code publics en quête de clés, et demande de ne pas les partager par e-mail ni par messagerie.
L’API Security Top 10 d’OWASP place l’authentification défaillante au deuxième rang de sa liste 2023 et compte l’envoi de jetons et de mots de passe dans l’URL parmi les signes d’une API vulnérable. La réponse de Stripe est la clé restreinte, limitée aux permissions d’une tâche. Son exemple est un tiers qui surveille les litiges et reçoit un accès en lecture seule à ces données. Une clé exposée, dit le guide, doit être renouvelée immédiatement. Un dirigeant retiendra trois habitudes : les clés sont créées dans votre propre compte, chaque prestataire reçoit la plus étroite, et vous savez comment la révoquer.
Limites de requêtes, offres payantes et versions : l’autre partie décide
Une API est le matériel d’autrui, et son propriétaire le protège. Stripe dit limiter le rythme des requêtes pour maximiser la stabilité et prévenir les abus. Sa documentation donne aujourd’hui une limite globale de 100 requêtes par seconde en mode réel, et le logiciel qui la dépasse reçoit l’état 429 Too Many Requests. Les limites marquent aussi la frontière entre le gratuit et le payant. La FAQ de Telegram pour les bots plafonne aujourd’hui l’envoi de masse à environ 30 messages par seconde, et décrit des diffusions payantes qui portent ce plafond à 1000 contre un coût en Telegram Stars.
Les versions sont la troisième règle. Wikipédia rappelle que les modifications d’une API peuvent rompre la compatibilité avec les clients qui en dépendent, et qu’une API publique peut déclarer obsolètes certaines de ses parties. Stripe décrit son propre rythme : de nouvelles versions paraissent chaque mois sans changement incompatible et, deux fois par an, une version majeure en contient, si bien que la mise à niveau peut obliger à modifier une intégration existante. Quelqu’un doit donc lire les avis de changement du service, et la maintenance entre dans le plan dès le premier jour.
Webhooks : quand l’autre système appelle votre adresse en premier
Dans le schéma ordinaire, votre logiciel demande et le service répond. Mais certaines choses arrivent plus tard, sans vous : une banque confirme un paiement quelques minutes après le départ du client. Demander chaque minute si c’est payé gaspille des requêtes, et les services proposent donc le canal inverse, le webhook. Vous donnez une adresse au service, et il y envoie un message lorsqu’un événement se produit. Selon sa documentation, Stripe pousse des données en temps réel vers l’adresse enregistrée quand, par exemple, la banque d’un client confirme un paiement.
Le webhook a aussi ses règles. Stripe exige une adresse HTTPS accessible publiquement, et la livraison ne dure pas éternellement : Stripe réessaie jusqu’à trois jours en mode réel, YooKassa livre une notification pendant 24 heures après l’événement. Stripe avertit aussi que le même événement peut arriver plus d’une fois et que, sans vérification, un attaquant pourrait envoyer de faux événements pour déclencher, par exemple, l’expédition de commandes. Si un site reste en panne un long week-end, des commandes payées peuvent rester marquées impayées jusqu’à ce que quelqu’un fasse le rapprochement.
Les questions à poser à un prestataire avant de lancer l’intégration
Commencez par les clés. Demandez qui les crée et dans quel compte, car ce compte doit être le vôtre, pas celui du prestataire. Demandez où elles seront conservées : le guide de Stripe dit de ne jamais placer de clés secrètes dans le code source. Demandez ce que chaque clé autorise et comment elle sera remplacée en fin de mission. Demandez enfin un environnement de test : Stripe, par exemple, propose un bac à sable avec ses propres clés, où les réseaux de cartes ne traitent pas les paiements.
Demandez ensuite ce qui se passe en cas d’échec. La documentation de YooKassa en donne un bon exemple : faute de réponse précise en 30 secondes, le service renvoie HTTP 500, et ce code ne dit pas si l’opération a réussi. Il faut d’abord vérifier le résultat. Elle décrit aussi une clé d’idempotence, grâce à laquelle une requête répétée compte comme l’originale, ce qui aide à éviter des transactions répétées. Demandez donc si le client est protégé d’un double débit, où se trouve le journal et qui est prévenu d’une erreur.
Connecteur prêt, outil sans code ou développement sur mesure : quoi préparer
Trois voies existent, et la bonne est la moins chère de celles qui conviennent. Regardez d’abord les réglages de vos services actuels, car beaucoup de CRM, de créateurs de sites et de services de paiement se connectent déjà entre eux. Sinon, les services d’automatisation sans code relient deux API par une chaîne visuelle : un nouveau contact, une fiche dans le CRM, un message au commercial. Le sur-mesure se justifie quand aucun connecteur n’existe, quand la logique vous est propre, quand les volumes frôlent les limites, ou quand de l’argent est en jeu et que chaque panne compte.
Quelle que soit la voie, préparez d’abord une feuille. Décrivez chaque liaison en une phrase : quand ceci se produit ici, cela doit apparaître là. Notez vos systèmes et vos formules, les champs de données qui circulent, le nombre approximatif d’événements par jour et le titulaire de chaque compte. Avec cette feuille, un studio comme VITON13 Studio, ou votre propre développeur, peut dire quelle voie convient et la chiffrer exactement. Et la question « qu’est-ce qu’une API » laisse place à une autre, plus utile : quels deux systèmes de votre entreprise devraient se parler en premier.
Checklist pratique
- Listez les services que vous payez déjà et vérifiez dans les réglages de chacun si votre formule inclut l’API.
- Écrivez chaque liaison en une phrase : quand ceci se produit dans le système A, cela doit apparaître dans le système B.
- Créez les clés d’API dans vos propres comptes et remettez au prestataire celle aux permissions les plus étroites.
- Convenez du lieu où sont journalisées les erreurs, de la personne alertée en cas de panne et de celle qui relit les avis de changement.
- Testez l’intégration dans l’environnement de test du service, avec des clés de test, avant le premier paiement réel.
Questions et réponses
Une petite entreprise a-t-elle besoin d’un développeur pour utiliser une API ?
Pas toujours. Beaucoup de services fournissent des connecteurs prêts qui s’activent dans les réglages, et les services d’automatisation sans code relient deux systèmes par une chaîne visuelle. Un développeur devient nécessaire quand aucun connecteur n’existe, quand la logique est particulière à votre activité, ou quand des paiements sont en jeu et que les erreurs et les doublons ne peuvent pas être laissés au hasard.
Une clé d’API équivaut-elle au mot de passe de mon compte ?
En pratique, oui. Le guide de Stripe qualifie les clés secrètes d’identifiants du compte, comme un nom d’utilisateur et un mot de passe : le logiciel qui présente la clé agit dans votre compte, dans la limite des permissions de cette clé. Les différences vous servent, car une clé peut être limitée à quelques opérations et révoquée sans changer votre accès personnel.
Que faire si une clé d’API se retrouve dans une discussion ou un e-mail ?
La considérer comme exposée et la remplacer. Stripe recommande de renouveler immédiatement une clé exposée, même sans preuve que quelqu’un l’ait vue : une nouvelle clé est émise, l’ancienne cesse de fonctionner et l’intégration bascule sur la nouvelle. Parcourez ensuite le journal des requêtes pour repérer des appels que vous n’avez pas faits, et cessez d’envoyer des clés par messagerie.
En quoi un webhook diffère-t-il d’une requête ordinaire à une API ?
Par le sens. Dans une requête ordinaire, votre logiciel interroge le service et attend la réponse. Avec un webhook, vous enregistrez une adresse une fois pour toutes et le service y envoie un message lorsqu’un événement survient, par exemple un paiement confirmé. Cela évite les interrogations incessantes, mais votre adresse doit rester joignable et l’expéditeur doit être vérifié.
Une intégration par API peut-elle cesser de fonctionner seule après la mise en ligne ?
Oui, et le plus souvent pour l’une de trois raisons : le service a publié une version avec des changements incompatibles, une clé a expiré ou a été révoquée, ou le volume de requêtes a atteint une limite. Rien de cela ne se voit sur le site tant que les commandes n’ont pas cessé d’arriver dans le CRM. D’où la nécessité d’un journal, d’une alerte et d’un responsable qui lit les avis du service.