Une API de QR codes : quoi automatiser, et quoi surtout pas

La plupart des QR codes devraient être créés par une personne, une fois, puis imprimés. Une API se justifie là où c'est impossible : un code par commande, par réservation, par équipement, par utilisateur — créé à un instant imprévisible et en quantité que personne ne veut cliquer.

Quand l'API est la bonne réponse

• Un code par enregistrement dans un système que vous exploitez déjà : billet, ordre de travail, étiquette d'actif, expédition.
• Des destinations calculées, pas choisies. Si l'URL se déduit de vos données, la ressaisie n'est pas une décision mais une source d'erreurs.
• Des données de scan qui doivent vivre dans votre reporting, à côté des commandes.

Quand ce n'est pas la bonne réponse

• Une campagne marketing. Une demi-douzaine de codes choisis et dessinés par des humains.
• Tout ce où le design compte. L'API crée et redirige ; le style, les cadres et les modèles relèvent de l'éditeur.
• Un lot unique. C'est le rôle de l'import CSV : un tableur est une intégration plus rapide qu'une intégration.

Authentification

La clé est créée dans le tableau de bord et affichée une seule fois. Seul un hachage SHA-256 est conservé, avec ses premiers caractères pour distinguer les clés : une clé perdue ne se récupère pas, elle se remplace.

Authorization: Bearer enq_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

L'API fait partie de l'offre Business. Limite : 60 requêtes par minute et par compte ; au-delà, 429 et rate_limited.

Créer un code

POST /api/v1/qrcodes
Authorization: Bearer enq_…
Content-Type: application/json

{ "name": "Commande 10432 – bon de livraison", "url": "https://shop.example/orders/10432" }

• Mettez votre identifiant dans le nom.
• Stockez l'id renvoyé sur votre enregistrement.

Le reste

• GET /api/v1/qrcodes — vos codes, du plus récent, pagination par curseur.
• GET /api/v1/qrcodes/{id} — un code.
• PATCH /api/v1/qrcodes/{id} — changer la destination. Toute l'idée du code dynamique tient là.
• DELETE /api/v1/qrcodes/{id} — supprimer ; ce qui est imprimé cesse de fonctionner.
• GET /api/v1/qrcodes/{id}/scans — jusqu'à 1 000 scans, du plus récent.

Ce que contient un scan

Heure, type d'appareil, système et navigateur déclarés, référent le cas échéant. Ni identité, ni compte, ni localisation — ni ville ni pays. « Combien, quand, sur quel type d'appareil » : oui. « Qui » et « où » : non.

Erreurs réelles

• 401 invalid_api_key
• 400 invalid_body — le plus souvent une URL qui n'en est pas une.
• 402 plan_limit_reached — Business n'a pas de limite, donc la clé vient d'une offre inférieure.
• 429 rate_limited

Deux choses à faire dès le premier jour

Rendre la création idempotente de votre côté. Deux appels créent deux codes ; les reprises finissent toujours par appeler deux fois.

Ne rien imprimer sans relecture. Une requête après création évite la seule erreur irrécupérable de tout ce système.

Réponses rapides

• Quelle offre ? Business.
• Authentification ? Authorization: Bearer enq_….
• Clé perdue ? Irrécupérable : en créer une et révoquer l'ancienne.
• Limite ? 60 requêtes par minute et par compte.
• Changer la destination ? Oui, PATCH.
• Localisation dans les scans ? Non.
• 500 codes une seule fois ? Import CSV.