Créer une clé API

Une API est une porte à l'arrière de votre compte. Là où vous cliquez dans votre espace de gestion, un autre programme peut passer par cette porte pour récupérer directement vos données : vos produits, vos tarifs, vos places disponibles, vos ventes.

C'est utile lorsque vous voulez par exemple :

• afficher sur votre propre site quelles visites guidées ont encore de la place cette semaine ;
• laisser votre comptable récupérer automatiquement vos chiffres ;
• relier votre liste de membres à un autre programme.

La personne qui construit cette intégration — votre webmaster, votre logiciel comptable, un ami qui programme — a besoin de deux choses : l'adresse et une clé. Les deux se trouvent sur un seul écran.

Bon à savoir : l'API fait partie d'une formule supérieure. Si vous êtes sur une formule plus petite, Accès API ne figure pas dans votre menu ; si vous arrivez quand même sur l'écran, vous voyez une explication et un bouton Vers l'abonnement, mais pas de clés.

Où aller

Ouvrez dans le menu de gauche Paramètres → Accès API. Seul le rôle Propriétaire voit cet écran.

En haut se trouvent deux onglets : Clés et Webhooks. Cet article porte sur le premier ; les webhooks sont expliqués dans Configurer des webhooks.

Sur l'onglet Clés, vous voyez trois blocs :

1. La connexion — l'adresse et la description technique. Ce sont ces deux informations que vous transmettez à qui construit l'intégration.
2. Nouvelle clé — c'est ici que vous en créez une.
3. Clés — ce qui existe déjà, et la dernière fois que cela a servi.

Créer une clé

Étape 1. Donnez un nom. Pas votre nom à vous, mais celui de ce qui se trouve à l'autre bout : « notre site », « comptabilité », « newsletter ». Ce nom ne sert qu'à vous. Il apparaîtra dans la liste, à côté de « dernière utilisation ». Dans un an, vous saurez encore quelle clé va avec quoi — et laquelle vous pouvez révoquer sans crainte.

Étape 2. Cochez ce que la clé peut faire. Sous Que peut faire cette clé ? se trouvent les droits, ou scopes en jargon. Lecture est déjà coché :

Droit	Ce que le programme peut faire
Lecture	Consulter votre catalogue, vos tarifs, vos places libres, vos réductions, vos bons cadeaux et vos abonnements annuels — et aussi vos commandes, billets, scans et 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	Faire en sorte que nous envoyions une notification vers une adresse à vous dès qu'il se passe quelque chose.
Paiement externe	Déclarer une commande payée sans prestataire de paiement (virement, espèces). Ne fonctionne qu'avec Écriture.

Ne cochez que le strict nécessaire. Un site qui doit seulement montrer les places disponibles se contente de Lecture. Si cette clé reçoit aussi Écriture, une erreur dans ce site peut créer ou rembourser des commandes dont vous ne voulez pas.

Soyez particulièrement prudent avec Paiement externe : qui a ce droit peut émettre des billets sans que l'argent n'entre. Ne le donnez qu'à une caisse ou une comptabilité que vous gérez vous-même.

Vous devez cocher au moins un droit. Une clé sans droit ne pourrait rien faire, et c'est le type d'erreur le plus difficile à retrouver — c'est pourquoi l'écran la refuse.

Étape 3 (facultative). Fixez une date d'expiration. Si vous laissez le champ Expire le (facultatif) vide, la clé reste valable jusqu'à ce que vous la révoquiez. Si vous indiquez une date, elle fonctionne encore ce jour-là puis s'arrête d'elle-même. La date doit être dans le futur. Pratique lorsque vous laissez quelqu'un regarder temporairement : vous n'aurez plus à y penser.

Étape 4 (facultative). Clé de test. Cochez Clé de test (sandbox) pour qui est encore en train de construire. Une telle clé lit les mêmes données qu'une clé normale. Si elle a aussi Écriture, 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 faute de frappe ne peut alors pas provoquer de vrai paiement ni de vrai remboursement. Une clé de test ne peut pas configurer de webhooks.

Attention : jusqu'à sa suppression, une commande de test bloque bien une vraie place, et l'e-mail de confirmation part réellement. Faites tester avec un produit ou un créneau créé à cet effet.

Vous reconnaissez une clé de test à son début : elle commence par pv_test_ au lieu de pv_live_.

Étape 5. Cliquez sur « Créer une clé ».

Vous ne voyez la clé qu'une seule fois

Juste après la création, la clé apparaît dans un cadre. C'est la seule fois que vous la voyez.

Copiez-la maintenant et transmettez-la tout de suite. Si vous rafraîchissez la page, elle a disparu.

Ce n'est pas une contrainte mais une protection. Nous ne conservons pas votre clé : nous n'en gardons qu'une sorte d'empreinte, qui nous permet de la reconnaître mais pas de la relire. Si quelqu'un accédait un jour à notre base de données, il n'aurait pas pour autant accès à vos données. Le revers, c'est que nous ne pouvons plus vous la montrer non plus.

Vous l'avez perdue ? Aucun souci : créez-en une nouvelle et révoquez l'ancienne.

Traitez une clé comme une clé

Qui détient la clé peut faire ce qui est coché dessus — sans mot de passe et sans ouvrir votre compte. Donc :

• ne l'envoyez pas dans une discussion de groupe où elle restera visible ;
• ne la mettez pas dans le code visible de votre site ;
• donnez à chaque intégration sa propre clé. Vous pourrez alors en révoquer une sans casser les autres, et vous verrez dans la liste laquelle sert encore.

Révoquer une clé

Dans la liste, cliquez sur Révoquer à côté de la clé, puis confirmez.

À partir de ce moment, elle ne fonctionne plus. La ligne reste dans la liste avec la mention « Révoquée » : vous pourrez toujours retrouver plus tard quelle intégration existait à quel moment.

Révoquez une clé lorsque :

• vous arrêtez d'utiliser l'outil qui s'en servait ;
• vous l'avez perdue ou elle traîne quelque part ;
• quelqu'un qui la détenait quitte l'organisation.

La création et la révocation d'une clé apparaissent aussi dans le journal d'activité de la personne qui l'a fait (Paramètres → Collaborateurs, cette personne, onglet Activité), avec le moment. La clé elle-même n'y figure jamais.

Quand a-t-elle servi pour la dernière fois ?

Sous chaque clé figure la date de la dernière récupération. Si « pas encore utilisée » s'affiche depuis des mois, plus rien n'y est probablement relié. Révoquez-la sans hésiter — une porte que personne n'utilise n'a pas besoin de rester ouverte.

Ce que vous transmettez à qui construit l'intégration

Trois choses :

1. l'adresse de l'API du bloc La connexion ;
2. la description technique (le lien qui se termine par openapi.json) — un développeur y voit immédiatement tout ce qui est possible ;
3. la clé elle-même, et les droits que vous avez cochés.

Il n'a besoin de rien d'autre.

Et ensuite ?

Vous avez l'adresse et la clé. Ce qui suit est le travail de celui qui construit l'intégration — et vous lui transmettez le portail développeurs. On y trouve la référence complète, avec des exemples de code en quatre langages et un fichier qui s'importe directement dans Postman ou Insomnia.

• Qu'est-ce qu'une API, et en ai-je besoin ? — si vous voulez d'abord savoir de quoi il retourne.
• Webhooks — prévenir votre site qu'une vente a eu lieu, sans qu'il doive le demander sans cesse.
• Configurer des webhooks — l'onglet Webhooks de ce même écran, pas à pas.