Qu’est-ce qu’une API, et en ai-je besoin ?

Vous croisez ces trois lettres dans le devis de votre webmaster, ou dans la liste des fonctions de votre logiciel comptable : API. Cet article explique de quoi il s’agit, sans que vous ayez besoin de savoir programmer.

La réponse courte

Une API est une porte à l’arrière de votre compte.

Là où vous cliquez dans votre écran de gestion pour voir combien de places restent libres, un autre programme peut demander exactement la même chose par cette porte — sans personne devant un écran. Derrière les deux portes, ce sont les mêmes données : vos produits, vos prix, vos places libres, vos ventes.

La différence, c’est qui entre. Par la porte d’entrée arrive un humain avec une souris. Par la porte de derrière arrive un programme avec une clé.

Quand en avez-vous besoin ?

Uniquement quand vous voulez quelque chose que l’écran de gestion ne fait pas. Par exemple :

• afficher sur votre propre site quelles visites ont encore de la place cette semaine, dans votre mise en page, avec des chiffres justes à l’instant même ;
• laisser votre comptable se servir, pour qu’il récupère lui-même le chiffre d’affaires du mois passé au lieu de recevoir un export de vous ;
• un écran dans le hall d’entrée qui montre le créneau qui va commencer ;
• vendre depuis un programme que vous utilisez déjà, sans devoir d’abord vous connecter à l’écran de gestion.

Et quand n’en avez-vous pas besoin ? Quand vous pouvez le cliquer. Construire une intégration coûte du temps et de l’entretien ; exporter une liste deux fois par mois coûte deux minutes. Ne choisissez la première que lorsque la seconde commence à vous gêner.

Attention : vous n’avez pas à construire cela vous-même. Celui qui le fait — votre webmaster, l’éditeur de votre logiciel comptable, quelqu’un de votre comité qui sait programmer — n’a besoin que de deux choses : l’adresse et une clé. Les deux se trouvent dans votre écran de gestion.

Ce que vous transmettez exactement

Ouvrez Paramètres → Accès API (cet écran est réservé au propriétaire de l’organisation). Sur l’onglet Clés, trois choses s’y trouvent, que vous pouvez transmettre :

1. L’adresse. Une ligne de texte. C’est là que l’autre programme parle.
2. La description technique, le lien qui se termine par openapi.json. Un développeur y voit d’un coup d’œil tout ce qui est possible : quelles données existent, comment les demander, ce qui revient.
3. Une clé, que vous créez vous-même. Voir Créer une clé API.

Il n’a besoin de rien de plus, et vous ne devez rien donner de plus — surtout pas votre mot de passe.

Ce qu’une clé peut et ne peut pas

À la création, vous cochez ce que la clé a le droit de faire. Ce n’est pas une formalité :

• Lecture — tout consulter, ne rien modifier. C’est ce dont la plupart des intégrations ont besoin. Attention : « tout », ce sont aussi vos commandes et vos acheteurs, avec leur nom et leur adresse e-mail.
• Écriture — créer des commandes, les faire payer, les annuler et les rembourser, demander une facture, annuler et renvoyer des billets, enregistrer des entrées, et émettre, utiliser ou prolonger des bons cadeaux et des abonnements annuels.
• Webhooks — indiquer où les messages peuvent être envoyés. Voir Webhooks.
• Paiement externe — déclarer une commande payée sans passer par un prestataire de paiement (virement, espèces). Ne le donnez qu’à une caisse ou une comptabilité que vous gérez vous-même : qui peut le faire, peut émettre des billets sans que l’argent n’entre.

Donnez à chaque intégration sa propre clé, avec seulement ce dont elle a besoin. Vous pouvez alors en révoquer une sans casser le reste, et vous voyez dans la liste laquelle sert encore.

Une clé n’est d’ailleurs pas un mot de passe qui ouvre votre compte : elle ne donne que ce qui y est coché, et elle appartient à une seule organisation. Même si elle traîne quelque part, personne ne peut s’en servir pour consulter les données de quelqu’un d’autre.

D’abord essayer sans risque

À côté d’une clé normale, vous pouvez créer une clé de test. Elle lit exactement les mêmes données. Si elle peut aussi écrire, elle ne crée que des commandes de test : elles ne passent jamais par votre prestataire de paiement, ne comptent pas dans votre chiffre d’affaires et sont supprimées automatiquement après 24 heures. Une clé de test ne peut pas configurer de webhooks.

C’est fait exactement pour ce moment — quelqu’un qui essaie et n’est pas encore sûr de ce qu’il fait. Laissez votre webmaster commencer avec une clé de test et ne passer à l’autre qu’à la fin.

Une chose à savoir : une commande de test bloque quand même une vraie place (jusqu’à sa suppression), et l’e-mail de confirmation part réellement. Faites donc tester votre webmaster avec un produit ou un créneau créé à cet effet.

Et si ça tourne mal ?

Révoquez la clé. Cliquez sur Révoquer dans la liste, et à partir de là elle ne fonctionne plus. L’intégration s’arrête, vos données restent. Il n’existe aucune situation où une clé peut faire quelque chose que vous ne pouvez pas arrêter en un clic.

Ce que cela coûte

L’API fait partie d’une formule plus grande. Sur une formule plus petite, Accès API ne figure pas dans votre menu. Si vous arrivez quand même sur cet écran, vous voyez une explication, la formule qui contient l’API et un bouton Vers l'abonnement — sans clés. Ce que contient chaque formule est indiqué sur la page des tarifs de Passavo.

Pour aller plus loin

• Créer une clé API — l’écran lui-même, pas à pas.
• Webhooks — prévenir votre site qu’une vente a eu lieu, sans qu’il doive le demander sans cesse.
• Configurer des webhooks — l’écran lui-même, pas à pas.
• Le portail développeurs — pour celui qui construit l’intégration.