Automatiser la création de QR codes : API, webhooks, sans code

À 23 h, une responsable billetterie ouvre un tableur de 2 300 inscriptions et commence à coller les adresses une à une dans un générateur. Vers la soixantième ligne, les erreurs arrivent : une ligne oubliée, un nom de fichier en double, un code enregistré par-dessus un autre. Rien n'était difficile, c'était simplement trop long à faire à la main, et ce sera aussi long le mois prochain.

C'est la forme du problème que l'automatisation résout. Non pas "nous faisons beaucoup de codes", mais "nous faisons un code par enregistrement, et les enregistrements continuent d'arriver".

Quand l'automatisation vaut son coût

L'automatisation se justifie dès lors qu'un code est attaché à un objet et non à une opération de communication. Un code par commande. Un par étiquette d'immobilisation, par logement loué, par table de restaurant, par colis ou par inscription à un événement. Le repère est simple : le volume suit l'activité, pas le calendrier marketing.

Le deuxième signe est le moment. Le code doit exister à un instant que personne ne peut planifier : une commande passée à trois heures du matin qui a besoin d'un bon de livraison, un appareil sorti d'un carton et mis en service sur site. Si aucun humain n'est devant un navigateur à cet instant, la génération doit se brancher sur un événement.

Si ni l'un ni l'autre n'est vrai, laissez tomber l'intégration. Quelques centaines de codes produits une fois, à partir d'une liste que vous avez déjà, c'est un travail pour un générateur en masse et un CSV : téléversez une colonne de destinations, téléchargez un dossier d'images, terminé avant midi, sans rien à maintenir. Beaucoup d'équipes bâtissent un pipeline pour un travail qui a lieu deux fois par an.

La forme d'une requête de génération

Les prestataires diffèrent par les noms et les détails : voyez ceci comme une anatomie générale et non comme le contrat réel de quiconque. Lisez la documentation du service que vous choisissez.

À l'entrée :

• La charge utile. Ce qui est encodé : une URL, un numéro de téléphone, des identifiants Wi-Fi, une fiche de contact. La seule donnée réellement obligatoire.
• L'apparence. Couleurs de premier plan et de fond, forme des modules, logo, marge, et niveau de correction d'erreurs. Les quatre niveaux récupèrent environ 7, 15, 25 et 30 pour cent d'un symbole abîmé, du plus bas au plus haut.
• La sortie. Format et dimensions. Matriciel pour les écrans ; vectoriel si quoi que ce soit en aval part chez un imprimeur.
• Les métadonnées. Un nom, un dossier, un libellé de campagne. Sans intérêt jusqu'au code numéro 8 000, moment où elles sont le seul moyen de retrouver le code numéro 12.

Au retour, vous verrez généralement l'une de trois choses : des octets d'image bruts, un corps JSON contenant l'image encodée en chaîne, ou un corps JSON pointant vers un fichier hébergé que vous récupérez en un second appel. C'est le troisième qui brûle les gens, parce que la réponse arrive vite et que le téléchargement de l'image peut encore échouer plus tard.

Générer une image n'est pas créer un code

Deux opérations sont rangées sous un même titre et ne se comportent absolument pas pareil.

Générer un code statique est proche d'une fonction pure. Une destination entre, une image sort, rien n'est stocké côté prestataire, et l'exécuter deux fois produit la même image. Perdez le fichier, vous le régénérez. Il n'y a pas d'enregistrement à fuiter, à casser ou à payer.

Créer un code dynamique est une écriture. Un enregistrement existe désormais quelque part : un identifiant, une URL de redirection courte, une destination actuelle et une pile croissante d'événements de scan que vous pouvez lire comme des statistiques. Parce que c'est une écriture, elle peut échouer à moitié, elle peut être dupliquée, et il faut la nettoyer quand la chose visée disparaît. Chaque partie difficile de l'automatisation des QR codes remonte à cette distinction.

Idempotence, ou la nuit où un webhook a fait quarante codes

Voici la panne qui finit par apparaître dans toutes ces intégrations. Un prestataire de paiement déclenche un webhook de commande créée. Votre gestionnaire appelle l'API QR, reçoit un code, puis dépasse le délai en écrivant dans votre propre base et ne renvoie jamais de 200. Le prestataire réessaie. Cinq minutes plus tard, cette commande a six codes dynamiques, cinq orphelins et tous décomptés de votre forfait.

Trois défenses, par ordre d'efficacité :

• Clé l'opération sur votre propre enregistrement. Une contrainte d'unicité sur l'identifiant de commande dans la table qui porte la référence du code est la correction la moins chère que vous achèterez jamais.
• Vérifiez avant de créer. Cherchez le code existant pour cet enregistrement et renvoyez-le au lieu d'en frapper un autre. Cela rend aussi les rejeux sans danger.
• Envoyez une clé d'idempotence si l'API en accepte une. Dérivez-la de façon déterministe de l'identifiant de votre enregistrement, jamais d'un horodatage ou d'une valeur aléatoire, sinon la nouvelle tentative génère une clé neuve et anéantit l'intérêt.

Écrivez la référence du code dans votre base au sein de la même transaction qui marque le travail comme terminé. Si ces deux-là peuvent diverger, ils divergeront.

Limites de débit, lots, et la reprise d'historique qui les fait sauter

Le trafic de régime n'est presque jamais le problème. Un code par commande est un filet d'eau. La reprise d'historique est le problème : l'après-midi où quelqu'un décide que les 40 000 actifs existants ont besoin de codes et lance toute la liste d'un coup.

Lisez les limites publiées du service au lieu de les deviner, puis construisez quand même pour le cas général. Une file d'attente plutôt qu'une boucle. Un plafond de requêtes simultanées. Un retrait exponentiel avec jitter sur tout 429 ou 5xx. Un travail reprenable, pour qu'un plantage à l'élément 19 000 ne recommence pas à l'élément un. Si le prestataire propose un point d'entrée par lot, utilisez-le ; une requête pour 500 codes bat 500 requêtes sur tous les plans, y compris vos journaux.

Étalez les grosses reprises sur plusieurs heures. Rien chez un actif vieux de cinq ans n'exige que son code existe dans les neuf minutes.

Enregistrez l'identifiant, pas seulement l'image

L'image est la chose la moins précieuse de la réponse. Stockez, à côté de votre propre enregistrement : l'identifiant du code chez le prestataire, l'URL courte, la destination au moment de la création, et l'horodatage de création.

C'est cette ligne qui vous permet de réorienter un code quand la page de destination déménage, de réimprimer une étiquette sans deviner ce qu'elle encodait, de répondre à "qui a fait cela et quand", et de supprimer le code quand l'enregistrement disparaît. Les équipes qui l'omettent se retrouvent avec un tableau de bord plein de codes que personne ne peut relier à quoi que ce soit, ce qui revient à n'en avoir aucun. Même pour de simples destinations issues d'un générateur de code URL, une colonne de base de données vaut mieux qu'un dossier de fichiers nommés final_v3.

Et en France ?

Un piège attend presque toutes les automatisations montées depuis un tableur français : le format CSV. Réglé en français, Excel exporte les fichiers CSV avec des points-virgules comme séparateurs, et non des virgules, et écrit les nombres décimaux avec une virgule.

Un outil ou une API qui attend un CSV « à l'anglaise » lira alors toute la ligne comme une seule colonne, ou confondra une virgule décimale avec un séparateur. Avant d'automatiser, vérifiez le séparateur attendu par votre générateur, choisissez l'encodage UTF-8 pour conserver les accents, et testez l'import sur trois lignes avant de lancer les 2 300.

Si personne dans l'équipe ne programme

Les outils d'automatisation sans code couvrent la plupart des besoins. Un déclencheur se lance sur une nouvelle ligne de tableur, une réponse de formulaire ou une fiche du CRM ; une étape HTTP appelle le générateur ; une dernière étape enregistre le résultat. Des intégrations de ce type fonctionnent pendant des années sans qu'un développeur ait à y toucher.

Deux points à anticiper. Ces plateformes facturent à la tâche, une reprise d'historique peut donc brûler le quota d'un mois en un après-midi ; passez les gros travaux par un téléversement en masse à la place. Et leur gestion d'erreur est discrète par défaut, une étape qui échoue à deux heures du matin peut donc rester dans un journal que personne n'ouvre. Ajoutez une notification d'échec explicite vers un canal qu'un humain lit.

Commencez étroit. Choisissez le type d'enregistrement qui a le plus besoin d'un code, ajoutez une seule colonne à cette table pour l'identifiant, et générez les dix premiers via l'API à la main. Scannez les dix avec un vrai téléphone. S'ils se résolvent, branchez le déclencheur.