API de QR code : les critères pour comparer les fournisseurs

Deux fournisseurs promettent une « API de QR code ». Le premier reçoit une chaîne et renvoie un PNG. Le second crée un enregistrement sur ses serveurs, vous donne une URL courte à encoder, compte chaque scan et vous laisse changer la destination le trimestre suivant. Même promesse sur la page d'accueil, mais deux produits différents, avec des pannes différentes et des points de négociation différents.

Deux produits différents partagent un seul nom

Les API qui génèrent des images ne gardent rien en mémoire : vous envoyez un contenu, vous recevez une image. Rien n'est stocké chez le fournisseur, rien n'est mesuré, et si ce fournisseur disparaît, les codes déjà produits continuent de fonctionner, puisqu'un code statique porte sa destination à l'intérieur du motif.

Les API dynamiques gérées sont à état. Le fournisseur crée un code, héberge la redirection, enregistre les scans et expose un appel pour changer la destination plus tard. Tout ce que vous avez imprimé dépend de la capacité de ce service à résoudre les requêtes, sur son infrastructure, pendant toute la durée de vie de l'impression.

goQR.me illustre cette scission au sein d'une même société : elle publie une API QR gratuite documentée à côté de son générateur, tandis que les codes dynamiques et les statistiques relèvent d'un produit payant distinct. Lire la documentation de n'importe quel fournisseur en gardant cette distinction en tête évite bien des confusions, car "API QR" dans un titre peut désigner l'une ou l'autre chose. Si la destination doit rester modifiable après la mise en production, un endpoint d'image ne vous le permettra jamais, et il vous faut des codes dynamiques avec une redirection gérée.

Formats de sortie et vectoriel

Posez trois questions sur la sortie : quels formats matriciels sont pris en charge, si un format vectoriel existe seulement, et si le vectoriel coûte plus cher.

Le vectoriel compte plus que les développeurs ne l'imaginent, parce que le code finit tôt ou tard dans le fichier d'impression de quelqu'un. Le PNG couvre les écrans et les petites étiquettes. Le grand format d'impression réclame du SVG, de l'EPS ou du PDF. Certains fournisseurs incluent le vectoriel gratuitement, d'autres le placent derrière une offre payante, et cette frontière bouge, lisez donc la documentation API actuelle plutôt qu'un article de blog à son sujet, y compris celui-ci.

Vérifiez aussi ce que l'API vous laisse contrôler : zone de silence, niveau de correction d'erreur, taille des modules, couleurs de premier plan et de fond. Un endpoint qui renvoie un PNG de taille fixe sans réglage de marge se battra plus tard contre votre mise en page, et le niveau de correction d'erreur n'est pas un réglage cosmétique quand le code part sur un emballage courbe.

Limites de débit et traitement par lots

Toute API de génération a un plafond. Ce qui diffère, c'est le comportement à ce plafond : un 429 accompagné d'une indication de réessai, un bridage silencieux, un blocage net, ou une facturation de dépassement. Trouvez la réponse dans la documentation actuelle du fournisseur et écrivez votre client contre ce comportement précis plutôt que contre une hypothèse générique.

Le traitement par lots compte au volume. Créer dix mille codes une requête HTTP à la fois est lent et fragile. Demandez s'il existe un endpoint de lot, s'il est asynchrone avec un identifiant de tâche à interroger, et comment les échecs partiels sont signalés. Si un lot de cinq mille renvoie 4 998 succès, vous devez savoir lesquels deux ont échoué et pouvoir ne réessayer que ceux-là. Notre propre générateur en masse existe parce que ce flux est assez courant pour mériter une interface ; via une API, les mêmes questions s'appliquent, simplement avec votre propre logique de réessai.

Authentification, et ce qu'une clé peut faire

Examinez trois propriétés du modèle d'authentification.

• La portée de la clé. Pouvez-vous émettre une clé qui ne fait que produire des images, distincte d'une clé capable de modifier des destinations ? Une clé capable de rediriger tous les codes en circulation relève d'une classe de risque différente d'une clé qui sait seulement dessiner.
• La rotation. Pouvez-vous remplacer une clé sans interruption, et l'ancienne bénéficie-t-elle d'un délai de grâce ?
• Le transport. Les clés placées dans les chaînes de requête finissent dans les journaux serveur, les proxys et l'historique du navigateur. L'authentification par en-tête est le choix par défaut le plus sûr, et si un fournisseur ne gère que les clés en chaîne de requête, traitez les URL générées comme des secrets et gardez-les hors des journaux partagés.

Les clés par environnement méritent aussi une question. Du trafic de préproduction qui contamine les statistiques de scan de production est une erreur courante, banale et coûteuse.

Stockage : pouvez-vous récupérer un code généré l'an dernier

Les équipes oublient celle-là. Pour les API d'image sans état, la réponse est généralement non : l'image existait dans la réponse et rien n'a été conservé. C'est souvent une propriété de confidentialité plutôt qu'un manque, mais cela signifie que votre système fait référence, et que vous devez stocker vous-même le contenu et les paramètres de rendu pour reproduire un code à l'identique.

Pour les plateformes gérées, demandez si vous pouvez lister les codes, les filtrer et exporter l'inventaire avec les destinations et les dates de création. Une API qui crée des codes sans offrir d'endpoint de liste vous laisse incapable d'auditer votre propre parc, ce qui devient un vrai problème la première fois que quelqu'un demande quels codes pointent vers une page que vous venez de supprimer. Ce travail est déjà assez pénible à la main, comme le montre retrouver les codes morts.

Idempotence et webhooks réémis

Deux problèmes liés, un de chaque côté du fil.

Côté écriture : si votre appel de création dépasse le délai, le code a-t-il été créé ? Sans clé d'idempotence, réessayer produit des doublons, et les doublons sur une offre facturée au code coûtent de l'argent et polluent les rapports. Vérifiez si le fournisseur accepte une clé d'idempotence fournie par le client à la création, et sur quelle durée il déduplique. Si ce n'est pas le cas, il vous faut votre propre garde-fou : un identifiant local déterministe, une recherche avant réessai, et un travail de réconciliation.

Côté lecture : si la plateforme envoie des webhooks pour les événements de scan, partez du principe qu'ils arriveront plus d'une fois et parfois dans le désordre. Donnez à chaque événement un identifiant stable, stockez les identifiants déjà traités, et rendez les gestionnaires sûrs à exécuter deux fois. Vérifiez si les webhooks sont signés, et validez la signature au lieu de faire confiance au contenu. Si vous branchez les scans sur d'autres systèmes, l'automatisation via une API ou Zapier hérite de la même exigence à l'autre bout.

Et en France ?

Un test à ajouter à votre grille pour le marché français : les caractères accentués. Depuis 2012, l'Afnic autorise les noms de domaine en .fr avec accents, comme « crêperie-dupont.fr », et beaucoup de pages françaises ont des adresses ou des paramètres avec des lettres accentuées.

Vérifiez que l'API accepte ces adresses sans les corrompre : un domaine accentué doit être converti correctement dans son format technique (punycode), et les accents dans le chemin doivent être encodés proprement. Envoyez trois URL de test, une avec un domaine accentué, une avec « é » dans le chemin, une avec une apostrophe, et scannez les codes obtenus.

Disponibilité, et la licence que vous achetez vraiment

Restent deux points, qui relèvent du contrat plutôt que de la technique.

La disponibilité change de sens selon la position de l'API. Appelez-la une fois au moment du build pour produire une image, et une panne devient une gêne que vous absorbez par des réessais. Placez la redirection du fournisseur sur le chemin de scan d'un support imprimé, et son indisponibilité devient la vôtre, en public, devant un client qui tient son téléphone. Réclamez une page de statut publiée, un historique d'incidents, et l'existence ou non d'un SLA à votre niveau d'offre. Interrogez l'infrastructure de redirection séparément de l'API, car ce sont souvent deux systèmes distincts aux caractéristiques de fiabilité différentes.

La licence est l'autre point. Faites confirmer que les codes générés peuvent servir commercialement et en impression, qu'aucune attribution n'est exigée, et que cette permission survit à la fin de votre abonnement pour les codes déjà produits. Certains fournisseurs l'énoncent clairement : la page du générateur de goQR.me indique que ses codes sont gratuits, avec usage commercial et impression autorisés. D'autres ne disent rien du tout, ce qui n'équivaut pas à un oui.

Un test pratique avant de vous engager. Encodez votre charge utile la plus longue et la plus réaliste via chaque API candidate et scannez le résultat à votre plus petite taille d'impression. La longueur de la charge utile détermine le nombre de modules, et la quantité de données qu'un code peut contenir décide souvent si vos URL doivent d'abord être raccourcies avant d'avoir besoin d'une API.

Ouvrez ensuite les documentations API actuelles des deux fournisseurs côte à côte et notez quatre choses pour chacun : sans état ou géré, vectoriel ou non, lots ou non, et si la redirection dispose de sa propre page de statut.