API de codes QR et webhooks
L’API permet à vos propres logiciels de créer, modifier, lire et supprimer des codes QR, et de lire leurs résumés de scans. Les webhooks envoient une notification signée à votre serveur lorsqu’un code change, qu’un scan humain arrive ou qu’une réponse à un formulaire de page d’atterrissage est enregistrée.
Ce que font l’API et les webhooks
L’API REST se trouve sous le chemin /api/v1 et répond en JSON. Elle peut lister les codes avec une recherche, un filtre par étiquette et des pages de cent éléments au maximum, lire un code, en créer, en modifier et en supprimer, renvoyer le SVG simple d’un code et résumer les scans des trente derniers jours. Une clé est un jeton Bearer qui commence par qrk_ et appartient à un seul espace de travail : une requête ne peut donc toucher que les codes de cet espace.
Un webhook est une adresse HTTPS que vous enregistrez avec les événements qui vous intéressent. L’application envoie un message JSON pour chaque événement : création, modification ou suppression d’un code, enregistrement d’un scan humain ou réponse à un formulaire de page d’atterrissage. Une action de test envoie un événement ping, ce qui vous permet de vérifier votre récepteur avant l’arrivée du trafic réel. Chaque envoi est signé en HMAC-SHA256 avec le secret du webhook, sur l’horodatage et le corps du message.
L’API s’adresse aux personnes qui développent des intégrations, et elle ne modifie pas l’apparence des codes. Le SVG est en noir et blanc, sans logo, ni forme ni couleur particulières, car les images stylisées proviennent de l’éditeur. L’API nécessite l’offre Team. Les clés survivent à un passage à une offre inférieure, mais elles cessent de fonctionner jusqu’à ce que l’espace de travail revienne à une offre qui l’inclut.
Comment commencer à utiliser l’API
-
01
Créer une clé en tant que propriétaire
Ouvrez la page API en tant que propriétaire, donnez à la clé un nom qui identifie le serveur qui l’utilisera, puis créez-la. Le jeton complet n’apparaît qu’une fois : copiez-le aussitôt dans votre gestionnaire de secrets. Ensuite, la page n’affiche plus que le nom, le préfixe, la date de création et la dernière utilisation.
-
02
Envoyer la clé avec chaque requête
Transmettez le jeton dans un en-tête Authorization, avec le mot Bearer, suivi d’un espace, puis du jeton. Appelez d’abord la vérification du compte : la réponse indique l’espace de travail, la clé et les crédits restants, ce qui confirme que la configuration fonctionne. Une clé absente ou incorrecte reçoit une réponse « non autorisé ».
-
03
Créer, modifier et lire des codes
Envoyez le nom, le type (par défaut, un lien web), le contenu et les champs facultatifs : dynamic, slug, expiry, password, un domaine vérifié, tags et style. La création d’un code coûte un crédit, tandis que la lecture et la mise à jour sont gratuites. Une requête qui échoue à la validation renvoie les motifs et restitue le crédit.
Où s’intègre l’API
-
Billetterie et réservations
Lorsqu’un système de réservation confirme une place, il crée un code dynamique pour ce billet et envoie le lien court ainsi que le SVG à l’acheteur. L’e-mail ou le billet dans le portefeuille numérique porte le même code, et personne ne le recopie à la main.
-
Étiquettes de stock et de matériel
Un système d’entrepôt peut créer un code par article, avec le numéro de l’article comme étiquette. Chaque scan est enregistré, et le système peut lire le résumé des trente derniers jours d’un article pour voir quelles étiquettes ont été contrôlées récemment.
-
Menus de restaurant depuis un tableur
Un script peut lire un tableur de liens de menu et mettre à jour le contenu de chaque code dynamique via l’API. Les codes imprimés restent les mêmes, et la mise à jour s’applique dès le scan suivant.
-
Accueil des participants et retours
Une équipe d’événementiel peut publier une page d’atterrissage avec un formulaire et recevoir un webhook pour chaque réponse. Un système distinct réagit à l’événement, de sorte que personne n’a besoin d’interroger les réponses.
-
Surveillance et alertes
Un récepteur de webhooks peut enregistrer les événements de scan par pays et par appareil, puis signaler qu’un code n’est plus scanné. C’est votre système qui décide de ce qui constitue un problème, car l’application transmet les événements sans les juger.
Conseils pour une intégration fiable
- Conservez la clé comme un mot de passe
- Les clés ne sont affichées qu’une fois et conservées uniquement sous forme d’empreinte : l’application ne peut donc pas les réafficher. Si une clé fuit, révoquez-la depuis la page API et créez-en une nouvelle. La révocation interrompt immédiatement toutes les requêtes qui utilisent l’ancien jeton.
- Respectez la limite de débit et les crédits
- Chaque clé peut envoyer 120 requêtes par minute. Au-delà de ce rythme, une requête reçoit une réponse « trop de requêtes ». Lorsque les crédits sont épuisés, la création d’un code renvoie une réponse « paiement requis » dont le code d’erreur indique qu’il ne reste aucun crédit. L’application ne permet pas encore d’acheter des crédits : prévoyez donc vos traitements par lots en fonction du solde.
- Vérifiez les signatures et les horodatages
- Calculez le HMAC-SHA256 de l’horodatage, d’un point et du corps brut avec votre secret, puis comparez-le à l’en-tête de signature. Rejetez les horodatages trop anciens, afin qu’une requête interceptée ne puisse pas être rejouée, et utilisez l’identifiant d’envoi pour ignorer une répétition.
- Utilisez un endpoint que vous contrôlez
- Les adresses de webhook doivent être en HTTPS, ne contenir aucun identifiant et correspondre à des adresses publiques. Les hôtes locaux et les plages de réseaux privés sont refusés, et les redirections ne sont pas suivies. En cas d’échec, l’envoi est repris jusqu’à cinq fois, à intervalles de plus en plus longs.
Questions sur l’API et les webhooks
Quelle offre inclut l’API ?
L’offre Team. La création de clés et de webhooks l’exige, et l’API répond par un statut « paiement requis » lorsque l’espace de travail est sur une offre qui ne l’inclut pas. Les clés existantes sont conservées lors d’un passage à une offre inférieure : elles fonctionnent de nouveau dès que l’offre est rétablie.
À quoi sert un crédit ?
Un crédit est dépensé pour chaque code créé par l’API. La lecture, la modification et la suppression de codes, ainsi que la lecture du résumé des scans, ne coûtent rien. Si une création échoue à la validation, le crédit est restitué.
Combien de crédits un espace de travail reçoit-il au départ ?
Quarante, valeur par défaut dans la base de données pour chaque espace de travail. L’application ne propose pas encore de page pour en acheter davantage : vérifiez donc le solde sur la page API ou avec l’appel de contrôle du compte avant un import volumineux.
Puis-je obtenir le code sous forme d’image depuis l’API ?
Oui, sous forme de SVG simple. Vous choisissez la taille des modules, de un à vingt, et la marge, de zéro à dix. L’image est en noir et blanc, sans logo, et si le contenu est trop long pour un code QR, l’API le signale. Pour les formes, les couleurs ou un logo, utilisez l’éditeur.
À quels événements puis-je m’abonner ?
À la création, à la modification et à la suppression d’un code, à un scan humain et à la réponse à un formulaire de page d’atterrissage. Les requêtes de robots et les aperçus de liens ne déclenchent aucun événement de scan, et un événement de test peut être envoyé à n’importe quel webhook.
Que se passe-t-il si mon endpoint ne répond plus ?
L’envoi est réessayé jusqu’à cinq fois, avec des délais croissants. Chaque tentative dispose d’un délai de connexion de cinq secondes et d’un délai de lecture de dix secondes. Après le dernier échec, l’envoi est marqué comme échoué, et la page des webhooks affiche le code de réponse et la dernière erreur.
Créez votre premier code en une minute
L’éditeur est gratuit. Créez un compte quand vous voulez enregistrer des codes, suivre les scans ou modifier une destination plus tard.