QRFLOW.codes
officielCréez des codes QR, redirigez des codes dynamiques imprimés, nommez des liens sur votre propre domaine et consultez les analyses de scans.
Que pouvez-vous faire avec QRFLOW Codes MCP ?
- Créer des codes QR dynamiques — Demandez à l’assistant de créer un code
urlavecdestination_dataet de renvoyer sonshort_urlà imprimer. - Modifier la destination d’un code imprimé — Changez la destination vers laquelle un code dynamique existant redirige sans le réimprimer, puisque l’image contient le
short_url. - Mettre un code en pause ou le faire expirer — Définissez
paused: trueou une date de fin au lieu de le supprimer, afin qu’un lien imprimé cesse de rediriger en toute sécurité. - Consulter les statistiques de scan — Récupérez le total de
Scansdepuis la création ou une répartition par jour, par pays et par appareil pour un code. - Nommer les liens sur votre propre domaine — Définissez un
slugcommemenuet choisissez un domaine de lien pour que le code s’imprime sous la formego.example.com/menu. - Créer des codes en masse — Générez des milliers de codes dynamiques à partir d’une liste et associez les codes renvoyés aux lignes à l’aide d’un libellé.
Serveur MCP hébergé
npx add-mcp 'https://qrflow.codes/mcp'S’installe dans Claude Code, Codex, Cursor et plus
Documentation
QRFLOW.codes pour les développeurs
Commencer ici
QRFLOW.codes crée des codes QR que vous pouvez modifier après impression, sur votre propre domaine, avec des statistiques de scan, et permet à vos logiciels et à votre assistant IA de tout faire via une seule API.
Un code QR est une image représentant une chaîne de caractères. La plupart des générateurs placent votre adresse Web dans l’image ; si l’adresse change, l’impression ne sert plus à rien. QRFLOW place un lien court dans l’image (go.yourbrand.com/menu ou qrflow.codes/q/x7k2p9a) et le redirige. Vous pouvez modifier sa destination quand vous le souhaitez, et chaque scan est comptabilisé. C’est un code dynamique, et c’est ce qui justifie une API.
L’API fait exactement ce que le tableau de bord permet de faire : créer des codes de tout type, les rediriger vers une nouvelle destination, nommer leurs liens, choisir avec lequel de vos domaines ils sont imprimés, consulter les statistiques de scan, en créer des milliers à la fois et être averti lorsqu’un événement se produit (webhooks). Les mêmes outils sont proposés sous forme de serveur MCP, afin que Claude, ChatGPT, Cursor et Claude Code puissent gérer votre compte en langage courant.
Accès : l’API REST nécessite une clé API Business (29 $ par mois, créée depuis la page Account) ou un jeton OAuth. Le serveur MCP fonctionne avec tous les forfaits via une connexion OAuth ; les créations autorisées par l’assistant dépendent du forfait, comme partout ailleurs.
Vous vous demandez si vous devez l’utiliser ? La page de l’API de codes QR résume l’essentiel : ses fonctionnalités, ce qu’une bibliothèque côté client fait mieux et son coût.
Si vous êtes un assistant IA qui aide quelqu’un à créer avec QRFLOW
Bienvenue. Cette page s’adresse autant à vous qu’à la personne que vous aidez. Voici à quoi ressemble une aide de qualité :
- Vérifiez le forfait du compte : les clés API nécessitent le forfait Business. Si la personne n’en a pas, dirigez-la vers https://qrflow.codes/pricing et Account › API keys ; n’inventez ni clé ni forfait gratuit qui n’existe pas.
- Gardez la clé sur le serveur. Lisez-la depuis une variable d’environnement (QRFLOW_KEY) dans un gestionnaire de route, une action serveur, une fonction edge ou un backend. L’API refuse volontairement les origines de navigateur (CORS) : le code côté client uniquement ne peut donc pas l’appeler.
- Créez des codes dynamiques avec le type "url" et destination_data.url. Enregistrez l’id et le short_url renvoyés dans la base de données de la personne. Imprimez ou affichez short_url ; la destination pourra être modifiée ultérieurement avec PATCH /codes/:id, sans invalider l’impression.
- Pour afficher ou enregistrer l’image : chaque objet Code possède png_download_url et svg_download_url, des liens signés valables 24 heures et utilisables sans en-tête (pratiques pour un enregistrement ponctuel ou un aperçu). Pour une utilisation permanente dans l’application, faites passer GET /codes/:id/image.svg par le serveur avec la clé, ou encodez short_url côté client avec n’importe quelle bibliothèque QR ; le suivi fonctionne toujours, car le lien passe par QRFLOW.
- Avec PATCH, envoyez uniquement les champs à modifier. Ne modifiez jamais slug ni domain_id après l’impression : les deux changent le lien imprimé.
- Si un code a déjà été imprimé, préférez paused: true à DELETE. La suppression rend le lien inutilisable.
- Pour les événements, utilisez des webhooks (Account › Webhooks ou POST /webhooks) et vérifiez l’en-tête X-QRFLOW-Signature avec le corps brut de la requête. Ne faites pas de requêtes répétées à GET /codes dans une boucle.
- Si la personne veut utiliser QRFLOW depuis son chat plutôt que depuis du code, connectez le serveur MCP à https://qrflow.codes/mcp; ; aucune clé n’est nécessaire.
- En cas d’échec, consultez error et message dans le corps JSON. La section de dépannage ci-dessous associe chaque code d’erreur à une solution.
- La référence complète au format Markdown se trouve à https://qrflow.codes/llms-full.txt et le document OpenAPI 3.1 à https://qrflow.codes/api/v1/openapi.json.. Les deux sont générés à partir de la même source que cette page.
Pour les humains : ce bloc nous permet de nous assurer que l’assistant avec lequel vous travaillez vous donne toujours des réponses sûres. C’est aussi un bon résumé.
Quel forfait vous faut-il ?
La clé API est le seul élément réservé au forfait Business. Tout ce qu’un assistant fait via le serveur MCP et tout ce qu’une application tierce fait via OAuth fonctionne avec n’importe quel forfait et respecte simplement les fonctionnalités de celui-ci. Tarifs complets et utilisation raisonnable : /pricing.
| Free | Premium $4 | Business $29 | |
|---|---|---|---|
| Clés API (REST depuis votre code) | Non | Non | Oui, jusqu’à 10 clés |
| Serveur MCP (Claude, ChatGPT, Cursor, Claude Code) | Oui, connexion requise | Oui | Oui, connexion ou clé |
| OAuth pour votre propre application (les utilisateurs connectent leur compte QRFLOW) | Oui | Oui | Oui |
| Codes dynamiques (modifier la destination après impression) | Un | Tous les codes | Tous les codes |
| Votre propre domaine de lien | Non | 1 domaine | 5 domaines, au choix pour chaque code |
| Noms de liens (go.brand.com/menu) | Non | Oui | Oui |
| Statistiques de scan | Non | Oui | Oui |
| Webhooks | Non | Non | Oui, jusqu’à 10 |
| Création en masse | Non | 500/mois, 500 par requête | 10 000/mois, 2 000 par requête |
| Codes enregistrés (utilisation raisonnable) | Quelques-uns | 1 000 | 25 000 |
| Places dans l’équipe | 1 | 1 | 5 |
| Prix | $0 | $4/mois | $29/mois |
Douze mots qui font tout le travail
Concepts
Lisez ces explications une fois et tous les points de terminaison ci-dessous seront clairs.
Static code
Le contenu se trouve dans l’image. Les codes Wi-Fi, les cartes de contact (vCard) et les codes de texte brut sont toujours statiques, et tous les codes le sont avec le forfait Free. Un code statique ne nécessite aucun serveur, n’expire jamais, et ne peut être ni modifié ni comptabilisé.
Dynamic code
L’image contient un lien court que QRFLOW redirige. Les codes url, phone, email, sms et location sont dynamiques avec les forfaits Premium et Business. Vous pouvez modifier leur destination, les mettre en pause, les faire expirer, les renommer et les comptabiliser sans toucher à l’impression.
short_url
La chaîne exacte encodée dans un code dynamique, et celle à imprimer. Il s’agit de https://qrflow.codes/q/<short_code> jusqu’à ce que vous connectiez un domaine, puis de https://<your domain>/<slug or short_code>.. Chaque objet Code la contient.
short_code
Sept caractères aléatoires, uniques pour chaque code, attribués à la création et jamais modifiés. Le chemin de secours lorsqu’un code n’a pas de nom de lien.
slug (link name)
Un chemin lisible sur votre propre domaine : go.example.com/menu. De 3 à 40 lettres minuscules, chiffres et tirets, unique dans votre compte, et disponible uniquement avec un domaine connecté. Définissez-le avant l’impression : le modifier change le lien imprimé.
Link domain
Un nom d’hôte qui vous appartient (go.example.com), dirigé vers QRFLOW par un CNAME et vérifié sur la page Account. Le forfait Premium en inclut un ; le forfait Business en inclut cinq et permet de choisir celui de chaque code avec domain_id. Le domaine actif le plus ancien est celui utilisé par défaut.
Kind, type and subtype
type indique le format d’encodage : url, text, wifi, vcard, email, phone, sms, location. Un type d’usage est un nom plus convivial correspondant à ce que les gens recherchent (instagram, googlereview, whatsapp, pdf, menu, appstore,...). La plupart des types d’usage sont des codes url avec destination_data.subtype défini. GET /catalog répertorie tous les types d’usage et leurs champs ; kind sur un objet Code indique lequel est utilisé.
destination_data
Les champs du type, sous forme de chaînes : { url } pour un site Web, { ssid, password, encryption } pour le Wi-Fi, { placeId } pour un avis Google, { handle } pour Instagram. Pour un code dynamique, vous pouvez les remplacer à tout moment.
Scans
Chaque redirection enregistre le type d’appareil, le pays, la ville, le référent, le navigateur, le système d’exploitation et la langue à partir de la requête elle-même, ainsi qu’un hachage quotidien à sens unique pour compter les visiteurs uniques. Aucun cookie n’est défini et l’adresse IP n’est pas stockée. scans sur un objet Code correspond au total cumulé ; GET /codes/:id/scans en fournit le détail.
Source
Chaque code conserve la trace de son origine : dashboard, api:<key name>, mcp, canva, app:<connected app> (par exemple app:Google Sheets) ou bulk, avec le préfixe bulk: lorsqu’il provient d’une requête groupée. Cette information apparaît dans le tableau de bord et dans les charges utiles des webhooks, ce qui permet de distinguer les codes de votre intégration de ceux créés manuellement.
Workspace
Un propriétaire Business peut inviter jusqu’à quatre coéquipiers. Les clés et les webhooks appartiennent au compte du propriétaire ; les codes créés par n’importe quel membre de l’espace de travail sont visibles par toute l’équipe.
Cinq minutes
Démarrage rapide
Obtenir une clé
- Avec le forfait Business, ouvrez Account › API keys.
- Donnez-lui un nom correspondant à son usage (« Shop backend », « Reporting ») et choisissez ses scopes. Les scopes ne peuvent pas être modifiés par la suite ; créez une nouvelle clé si vous en avez besoin d’autres.
- Copiez-la une seule fois. Elle ressemble à
qrf_live_…. Placez-la dans une variable d’environnement nomméeQRFLOW_KEY. - Envoyez-la dans
Authorization: Bearer $QRFLOW_KEYà chaque requête. C’est tout ce qu’il faut savoir sur l’authentification.
Les clés sont destinées aux serveurs. Ne les placez jamais dans une page Web, une application mobile ou une feuille de calcul partagée ; révoquez-les et créez-en de nouvelles en cas de fuite.
Les mêmes cinq étapes en curl, TypeScript et Python. Chaque exemple crée un code dynamique, télécharge son image, modifie sa destination et récupère ses statistiques de scan.
export QRFLOW_KEY=qrf_live_... # from Account › API keys
# 1. Who am I, what can this key do?
curl https://qrflow.codes/api/v1/me -H "Authorization: Bearer $QRFLOW_KEY"
# 2. Make a dynamic code. Print what comes back as short_url.
curl -X POST https://qrflow.codes/api/v1/codes \
-H "Authorization: Bearer $QRFLOW_KEY" -H "Content-Type: application/json" \
-d '{ "type": "url", "destination_data": { "url": "https://example.com/menu" }, "label": "Table tents" }'
# 3. The print-ready image (SVG, with your colors and frame).
curl "https://qrflow.codes/api/v1/codes/$CODE_ID/image.svg?size=1024" \
-H "Authorization: Bearer $QRFLOW_KEY" -o menu.svg
# 4. Fall menu. The printed code keeps working.
curl -X PATCH https://qrflow.codes/api/v1/codes/$CODE_ID \
-H "Authorization: Bearer $QRFLOW_KEY" -H "Content-Type: application/json" \
-d '{ "destination_data": { "url": "https://example.com/menu-fall" } }'
# 5. How did it do?
curl "https://qrflow.codes/api/v1/codes/$CODE_ID/scans?group=day" -H "Authorization: Bearer $QRFLOW_KEY"
TypeScript (Node 18+, Bun, Deno, Workers)
// npm install qrflow (zero dependencies; ESM + CommonJS; full types)
import { QRFlow, QRFlowError } from "qrflow";
const qr = new QRFlow(process.env.QRFLOW_KEY!);
const { code } = await qr.createCode({
type: "url",
destination_data: { url: "https://example.com/menu" },
label: "Table tents",
});
console.log(code.id, code.short_url); // save both; print short_url
await qr.updateCode(code.id, { destination_data: { url: "https://example.com/menu-fall" } });
const stats = await qr.scans(code.id, { group: "day" });
console.log(stats.total, stats.rows); // [{ key: "2026-09-21", scans: 18 }, ...]
try {
await qr.updateCode(code.id, { slug: "menu" });
} catch (e) {
if (e instanceof QRFlowError) console.log(e.status, e.code, e.message); // 400 no_domain: connect a domain first
}
# Download https://qrflow.codes/sdk/qrflow.py next to your code.
import os
from qrflow import QRFlow, QRFlowError
qr = QRFlow(os.environ["QRFLOW_KEY"])
code = qr.create_code(type="url", destination_data={"url": "https://example.com/menu"}, label="Table tents")["code"]
print(code["id"], code["short_url"]) # save both; print short_url
qr.update_code(code["id"], destination_data={"url": "https://example.com/menu-fall"})
stats = qr.scans(code["id"], group="day")
print(stats["total"], stats["rows"])
try:
qr.update_code(code["id"], slug="menu")
except QRFlowError as e:
print(e.status, e.code, e) # 400 no_domain: connect a domain first
Authentification
Clés API (Business)
Jusqu’à 10 par compte, 600 requêtes par minute chacune, stockées sous forme hachée et affichées une seule fois. Une clé possède les scopes définis lors de sa création :
| Scope | Autorisations |
|---|---|
| profile | GET /me : forfait, fonctionnalités, limites. Toutes les clés l’incluent. |
| codes:read | Lister et consulter les codes, télécharger des images. |
| codes:write | Créer, modifier, rendre dynamiques, supprimer et créer des codes en masse. |
| analytics:read | GET /codes/:id/scans. |
| domains:read | GET /domains (nécessaire pour utiliser domain_id correctement). |
| codes:read / codes:write | Également pour les produits GS1 : les points de terminaison /products partagent les scopes des codes ; une clé qui gère les codes gère aussi les codes d’emballage. |
| webhooks:manage | Lister, créer, tester et supprimer des webhooks. |
OAuth 2.0 (tous les forfaits, pour les applications et les assistants)
Lorsque les codes doivent appartenir aux comptes de vos utilisateurs plutôt qu’au vôtre, ou lorsqu’un assistant conversationnel est le client, utilisez OAuth. Les clients s’enregistrent eux-mêmes ; PKCE S256 est obligatoire pour les clients publics ; les jetons peuvent être liés au serveur MCP avec resource=. Le guide OAuth vous accompagne dans la procédure.
| Point de terminaison | URL | Remarques |
|---|---|---|
| Autorisation | https://qrflow.codes/oauth/authorize | Envoyez l’utilisateur ici ; il se connecte et clique sur Allow. |
| Jeton | https://qrflow.codes/api/oauth/token | Flux authorization_code et refresh_token. Les jetons d’accès sont valables 1 heure, les jetons d’actualisation 90 jours. |
| Révocation | https://qrflow.codes/api/oauth/revoke | RFC 7009. Les utilisateurs peuvent aussi déconnecter l’application depuis Account › Connected apps. |
| Enregistrer un client | https://qrflow.codes/api/oauth/register | Enregistrement dynamique RFC 7591, sans compte requis. Les clients publics reçoivent un dyn_ client_id et doivent utiliser PKCE S256. |
| Découverte | https://qrflow.codes/.well-known/oauth-authorization-server | RFC 8414. Le document de ressource MCP se trouve à /.well-known/oauth-protected-resource. |
Les jetons d’accès sont valables 1 heure et les jetons d’actualisation 90 jours. Les utilisateurs voient les applications connectées dans Account › Connected apps et peuvent les déconnecter à tout moment. Un jeton émis pour https://qrflow.codes/mcp est refusé sur /api/v1, et inversement.
Les demandes les plus courantes
Exemples de mise en œuvre
Chaque exemple est complet et directement tiré de code fonctionnel. Choisissez celui qui correspond à votre stack ; la structure est toujours la même : un appel côté serveur avec la clé, enregistrer id et short_url, puis afficher l’image.
- Next.js
- Afficher le code QR sans proxy
- Express ou tout serveur Node
- Cloudflare Workers, Vercel Edge, Deno Deploy, Supabase Edge Functions
- Python
- Un code QR par commande, table, produit, billet ou événement
- Modifier la destination d’un code déjà imprimé
- Imprimer des codes sur votre propre domaine
- Un graphique des scans dans votre propre interface d’administration
- Recevoir des webhooks dans Next.js et les vérifier
- Recevoir des webhooks en Python
- Des milliers de codes à partir d’un fichier CSV
- Permettre à vos utilisateurs de connecter leur propre compte QRFLOW (OAuth)
- Zapier, Make, n8n
Next.js : une route pour créer un code et une autre pour l’afficher
Quand : vous avez une application Next.js (App Router) et souhaitez un bouton qui crée un code QR ainsi qu’une page qui l’affiche.
- Placez votre clé dans .env.local sous le nom QRFLOW_KEY. Ne lui ajoutez jamais le préfixe NEXT_PUBLIC_.
- Ajoutez un gestionnaire de route POST qui crée le code et renvoie id et short_url.
- Ajoutez une route GET qui sert de proxy pour l’image afin que le navigateur ne voie jamais la clé.
- Enregistrez id et short_url dans votre propre enregistrement (commande, table, produit, événement).
import { NextResponse } from "next/server";
export async function POST(req: Request) {
const { url, label } = await req.json();
const r = await fetch("https://qrflow.codes/api/v1/codes", {
method: "POST",
headers: { Authorization: \`Bearer ${process.env.QRFLOW_KEY}\`, "Content-Type": "application/json" },
body: JSON.stringify({ type: "url", destination_data: { url }, label }),
});
const data = await r.json();
if (!r.ok) return NextResponse.json(data, { status: r.status }); // { error, message }
return NextResponse.json({ id: data.code.id, short_url: data.code.short_url });
}
// Proxies the SVG so the key stays on the server. Check that the signed-in
// user owns this id before you serve it, or anyone with an id can fetch it.
export async function GET(_: Request, { params }: { params: Promise<{ id: string }> }) {
const { id } = await params;
const r = await fetch(\`https://qrflow.codes/api/v1/codes/${id}/image.svg?size=1024\`, {
headers: { Authorization: \`Bearer ${process.env.QRFLOW_KEY}\` },
});
return new Response(r.body, {
status: r.status,
headers: { "Content-Type": "image/svg+xml", "Cache-Control": "private, max-age=3600" },
});
}
<img src={\`/api/qr/${code.id}/image\`} alt={\`QR code for ${code.label}\`} width={256} height={256} />
<a href={code.short_url}>{code.short_url}</a>
- Les Server Actions fonctionnent de la même manière : appelez fetch avec la clé dans l’action.
- Pour Pages Router, placez le même code dans pages/api/qr.ts avec req/res.
Afficher le QR sans proxy : afficher vous-même short_url
Quand : vous voulez afficher l’image immédiatement dans le navigateur et n’avez pas besoin des cadres ni du logo de QRFLOW.
N’importe quelle bibliothèque QR convient, car le code EST le lien court
import QRCode from "qrcode"; // npm i qrcode
// short_url came back from POST /codes. Encode it as-is.
const dataUrl = await QRCode.toDataURL(code.short_url, { width: 512, margin: 2 });
// <img src={dataUrl} /> scans go through QRFLOW, so analytics and re-pointing still work.
- C’est la méthode la plus rapide pour un aperçu. Pour l’impression, téléchargez /codes/:id/image.svg : le fichier contient les couleurs, le cadre, les légendes et le logo enregistrés, et c’est un fichier vectoriel.
- Si vous modifiez ensuite slug ou domain_id, short_url change ; générez à nouveau l’image.
Express ou tout autre serveur Node
Quand : vous avez un backend Node classique.
import express from "express";
const app = express();
app.use(express.json());
const H = { Authorization: \`Bearer ${process.env.QRFLOW_KEY}\`, "Content-Type": "application/json" };
app.post("/qr", async (req, res) => {
const r = await fetch("https://qrflow.codes/api/v1/codes", {
method: "POST", headers: H,
body: JSON.stringify({ type: "url", destination_data: { url: req.body.url }, label: req.body.label }),
});
res.status(r.status).json(await r.json());
});
app.get("/qr/:id.svg", async (req, res) => {
const r = await fetch(\`https://qrflow.codes/api/v1/codes/${req.params.id}/image.svg\`, { headers: H });
res.status(r.status).type("image/svg+xml").send(await r.text());
});
app.listen(3000);
Cloudflare Workers, Vercel Edge, Deno Deploy, Supabase Edge Functions
Quand : vous utilisez un environnement d’exécution qui ne prend en charge que fetch et ne dispose d’aucune API intégrée de Node.
export default {
async fetch(req: Request, env: { QRFLOW_KEY: string }) {
const { url, label } = await req.json();
const r = await fetch("https://qrflow.codes/api/v1/codes", {
method: "POST",
headers: { Authorization: \`Bearer ${env.QRFLOW_KEY}\`, "Content-Type": "application/json" },
body: JSON.stringify({ type: "url", destination_data: { url }, label }),
});
return new Response(r.body, { status: r.status, headers: { "Content-Type": "application/json" } });
},
};
Deno.serve(async (req) => {
const { url, label } = await req.json();
const r = await fetch("https://qrflow.codes/api/v1/codes", {
method: "POST",
headers: { Authorization: \`Bearer ${Deno.env.get("QRFLOW_KEY")}\`, "Content-Type": "application/json" },
body: JSON.stringify({ type: "url", destination_data: { url }, label }),
});
return new Response(await r.text(), { status: r.status, headers: { "Content-Type": "application/json" } });
});
// supabase secrets set QRFLOW_KEY=qrf_live_...
- Le package npm
qrflow\utilise uniquement fetch et WebCrypto ; il fonctionne donc tel quel dans tous ces environnements.
Python : FastAPI, Flask, Django ou un script
Quand : votre backend est en Python.
import os
from fastapi import FastAPI, HTTPException, Response
from qrflow import QRFlow, QRFlowError # https://qrflow.codes/sdk/qrflow.py
app = FastAPI()
qr = QRFlow(os.environ["QRFLOW_KEY"])
@app.post("/qr")
def make_qr(url: str, label: str | None = None):
try:
code = qr.create_code(type="url", destination_data={"url": url}, label=label)["code"]
except QRFlowError as e:
raise HTTPException(e.status, {"error": e.code, "message": str(e)})
return {"id": code["id"], "short_url": code["short_url"]}
@app.get("/qr/{code_id}.svg")
def qr_image(code_id: str):
import urllib.request
req = urllib.request.Request(qr.image_url(code_id), headers={"Authorization": f"Bearer {os.environ['QRFLOW_KEY']}"})
with urllib.request.urlopen(req) as r:
return Response(r.read(), media_type="image/svg+xml")
Un code QR par commande, table, produit, billet ou événement
Quand : chaque ligne de l’une de vos tables doit avoir son propre code, créé automatiquement.
- Ajoutez deux colonnes à votre table : qrflow_code_id (uuid) et qr_short_url (text).
- Lorsqu’une ligne est créée, envoyez une requête POST /codes avec l’URL publique de la ligne et un libellé qui l’identifie (« Commande 10432 », « Table 7 »). Enregistrez id et short_url.
- Lorsque la page de la ligne change (nouveau domaine, nouveau chemin), envoyez une requête PATCH destination_data. Les codes imprimés continuent de fonctionner.
- Lorsque la ligne est retirée, envoyez PATCH { paused: true } si quelque chose a été imprimé ; utilisez DELETE uniquement si rien ne l’a été.
- Vous en avez besoin de milliers à la fois (un menu par table pour 300 restaurants) ? Utilisez POST /codes/bulk par lots et associez les codes renvoyés à vos lignes par libellé ou par commande.
const { code } = await qr.createCode({
type: "url",
destination_data: { url: \`https://example.com/orders/${order.id}\` },
label: \`Order ${order.number}\`,
});
await db.orders.update(order.id, { qrflow_code_id: code.id, qr_short_url: code.short_url });
- L’utilisation raisonnable est limitée à 25,000 codes enregistrés avec Business ; l’API s’arrête au double. Si vous avez besoin d’un code par reçu pour toujours, contactez-nous d’abord : hello@qrflow.codes.
Modifier la destination d’un code imprimé
Quand : une campagne est terminée, une page a changé d’adresse, un PDF a été remplacé ou une saison a changé.
curl -X PATCH https://qrflow.codes/api/v1/codes/$CODE_ID \
-H "Authorization: Bearer $QRFLOW_KEY" -H "Content-Type: application/json" \
-d '{ "destination_data": { "url": "https://example.com/spring" } }'
Mettez-le en pause ou définissez une date de fin
# Scans show a "paused" page instead of redirecting
curl -X PATCH https://qrflow.codes/api/v1/codes/$CODE_ID -H "Authorization: Bearer $QRFLOW_KEY" \
-H "Content-Type: application/json" -d '{ "paused": true }'
# Stops working after the date; null clears it
curl -X PATCH https://qrflow.codes/api/v1/codes/$CODE_ID -H "Authorization: Bearer $QRFLOW_KEY" \
-H "Content-Type: application/json" -d '{ "expires_at": "2026-12-31T23:59:59Z" }'
- Seuls les codes dynamiques peuvent être redirigés ; toute tentative sur un code statique renvoie 400 not_dynamic. Les codes Wi-Fi, vCard et texte brut contiennent leur contenu dans le motif et ne peuvent jamais être dynamiques ; POST /codes/:id/dynamic les refuse donc avec 400 not_dynamic_capable. Pour les codes url, phone, email, sms et location, Free rend le premier dynamique et les autres statiques ; avec un forfait payant, ils sont tous dynamiques. POST /codes/:id/dynamic convertit un code statique tant que le compte dispose encore du quota nécessaire. Générez à nouveau l’image et réimprimez-la ensuite, car son apparence change.
- Un scanner voit la nouvelle destination dès le scan suivant. Aucun délai d’attente lié au cache n’est nécessaire.
Imprimer des codes sur votre propre domaine
Quand : vous voulez que le code contienne go.example.com/menu au lieu de qrflow.codes/q/x7k2p9a.
- Sur la page Account, sous Your own link domain, ajoutez go.example.com et créez l’enregistrement CNAME indiqué chez votre fournisseur DNS. La vérification prend généralement quelques minutes.
- À partir de là, le short_url de chaque nouveau code dynamique utilise ce domaine. Les codes existants changent aussi : leur image contient qrflow.codes/q/..., qui continue de rediriger ; rien de ce qui est imprimé ne cesse donc de fonctionner.
- Donnez aux codes des noms lisibles avec slug : PATCH { "slug": "menu" } crée go.example.com/menu. Faites-le avant l’impression.
- Avec Business et plusieurs domaines, GET /domains les répertorie avec leurs ids ; transmettez domain_id dans POST ou PATCH pour choisir le domaine de chaque code.
Nommez un lien et choisissez un domaine
curl https://qrflow.codes/api/v1/domains -H "Authorization: Bearer $QRFLOW_KEY"
# { "default_base": "https://go.example.com", "domains": [ { "id": "…", "host": "go.example.com", "is_default": true, … }, { "id": "…", "host": "qr.example.fr", … } ] }
curl -X PATCH https://qrflow.codes/api/v1/codes/$CODE_ID -H "Authorization: Bearer $QRFLOW_KEY" -H "Content-Type: application/json" \
-d '{ "slug": "menu", "domain_id": "<id of qr.example.fr>" }'
# short_url is now https://qr.example.fr/menu
Un graphique des scans dans votre propre interface d’administration
Quand : vous voulez consulter les scans par jour, par pays ou par appareil à côté de vos propres chiffres.
const stats = await qr.scans(code.id, { from: "2026-09-01", to: "2026-09-30", group: "day" });
// stats.total -> 412
// stats.rows -> [{ key: "2026-09-01", scans: 18 }, { key: "2026-09-02", scans: 25 }, ...]
// Feed rows straight into Recharts, Chart.js, or a <table>.
const byCountry = await qr.scans(code.id, { group: "country" }); // [{ key: "US", scans: 300 }, { key: "MX", scans: 41 }]
const byDevice = await qr.scans(code.id, { group: "device" }); // mobile, desktop, tablet
- Une requête couvre jusqu’à 92 jours ; effectuez une boucle pour les périodes plus longues. Les dates sont en UTC.
- Pour obtenir des chiffres en temps réel sans interrogation périodique, abonnez un webhook à l’événement de scan : vous recevrez tous les scans avec leurs détails, par lots toutes les quelques minutes.
Recevoir et vérifier les webhooks dans Next.js
Quand : vous voulez savoir quand un code est scanné ou modifié dans votre propre base de données, presque en temps réel.
- Créez le webhook sur Account › Webhooks ou avec POST /webhooks. Copiez une seule fois le secret (whsec_...) dans QRFLOW_WEBHOOK_SECRET.
- Lisez le corps brut sous forme de texte avant de l’analyser ; la signature porte sur les octets exacts.
- Vérifiez la signature, puis traitez l’événement. Répondez rapidement avec un code 2xx ; effectuez les tâches longues après la réponse ou dans une file d’attente.
- Cliquez sur Test dans le webhook pour recevoir un ping signé et vérifier la configuration.
import { createHmac, timingSafeEqual } from "node:crypto";
function verify(raw: string, header: string, secret: string): boolean {
const t = /t=(\d+)/.exec(header)?.[1], v1 = /v1=([a-f0-9]+)/.exec(header)?.[1];
if (!t || !v1 || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
const expected = createHmac("sha256", secret).update(\`${t}.${raw}\`).digest("hex");
return expected.length === v1.length && timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}
export async function POST(req: Request) {
const raw = await req.text();
if (!verify(raw, req.headers.get("x-qrflow-signature") ?? "", process.env.QRFLOW_WEBHOOK_SECRET!)) {
return new Response("bad signature", { status: 401 });
}
const evt = JSON.parse(raw) as { id: string; event: string; created_at: string; data: any };
// evt.id is stable across retries: store it and skip duplicates.
switch (evt.event) {
case "scan": // evt.data.scans[]: code_id, label, slug, scanned_at, device, country, city, referrer, browser, os, language
break;
case "code.created": // evt.data.code, evt.data.source
case "code.updated": // evt.data.code, evt.data.changed[]
case "code.deleted": // evt.data.code { id, label, short_code, slug }
break;
case "ping": // the Test button
break;
}
return new Response(null, { status: 204 });
}
- En local, exposez votre serveur de développement avec un tunnel (cloudflared tunnel --url http://localhost:3000, ou ngrok) et utilisez cette URL https pour le webhook pendant le développement.
- Le package npm s’en charge pour vous :
import { parseWebhook } from "qrflow"\vérifie et analyse en un seul appel (WebCrypto, donc il fonctionne aussi dans Workers et Deno). Le client Python fournit verify_webhook.
Recevoir des webhooks en Python
Quand : Flask, FastAPI ou Django reçoit les mêmes événements.
import os, json
from flask import Flask, request, abort
from qrflow import verify_webhook # https://qrflow.codes/sdk/qrflow.py
app = Flask(__name__)
@app.post("/qrflow")
def hook():
raw = request.get_data() # bytes, before any parsing
if not verify_webhook(raw, request.headers.get("X-QRFLOW-Signature", ""), os.environ["QRFLOW_WEBHOOK_SECRET"]):
abort(401)
evt = json.loads(raw)
if evt["event"] == "scan":
for s in evt["data"]["scans"]:
print(s["code_id"], s["scanned_at"], s["country"], s["device"])
return "", 204
Des milliers de codes à partir d’un CSV
Quand : vous avez besoin d’un code par SKU, par siège, par étiquette d’actif ou par publipostage.
import { parse } from "csv-parse/sync";
import { readFileSync } from "node:fs";
const rows = parse(readFileSync("skus.csv"), { columns: true }) as Array<{ sku: string; url: string }>;
const out: Array<{ sku: string; id: string; short_url: string }> = [];
for (let i = 0; i < rows.length; i += 2000) { // Business: 2,000 per request
const chunk = rows.slice(i, i + 2000);
const { codes, rejected, remaining_this_month } = await qr.bulkCreate(
chunk.map((r) => ({ destination: r.url, label: r.sku })),
);
codes.forEach((c, j) => out.push({ sku: chunk[j].sku, id: c.id, short_url: c.short_url }));
if (rejected.length) console.warn(rejected); // rows that were not web addresses
console.log(remaining_this_month, "left this month");
}
- La création en masse ne prend en charge que les codes url dynamiques, tous avec les mêmes couleurs. Les codes sont renvoyés dans l’ordre d’envoi, à l’exception des lignes rejetées ; en cas de doute, faites la correspondance par libellé.
- Les webhooks envoient un seul événement code.created par requête groupée, avec codes[] au lieu d’un événement par code.
Permettre à vos utilisateurs de connecter leur propre compte QRFLOW (OAuth)
Quand : vous créez un produit pour d’autres personnes et voulez que les codes soient enregistrés dans leurs comptes QRFLOW, et non dans le vôtre.
- Enregistrez un client une seule fois : POST https://qrflow.codes/api/oauth/register avec client_name et redirect_uris. Vous obtenez un client_id (et un client_secret pour les clients confidentiels).
- Redirigez l’utilisateur vers /oauth/authorize avec response_type=code, client_id, redirect_uri, scope, state et PKCE (code_challenge, code_challenge_method=S256).
- Échangez le code sur /api/oauth/token. Enregistrez le jeton d’actualisation ; les jetons d’accès expirent au bout d’une heure.
- Appelez /api/v1 avec Authorization: Bearer <access_token>. Tout fonctionne exactement comme avec une clé, selon le forfait de l’utilisateur.
curl -X POST https://qrflow.codes/api/oauth/register -H "Content-Type: application/json" \
-d '{ "client_name": "Acme Menus", "redirect_uris": ["https://app.example.com/oauth/qrflow"], "token_endpoint_auth_method": "none" }'
# { "client_id": "dyn_…", "redirect_uris": [...], "grant_types": ["authorization_code","refresh_token"], … }
https://qrflow.codes/oauth/authorize?response_type=code&client_id=dyn_…&redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fqrflow
&scope=profile%20codes%3Aread%20codes%3Awrite%20analytics%3Aread&state=…&code_challenge=…&code_challenge_method=S256
- Les portées sont les mêmes six que pour les clés API. Demandez uniquement celles dont vous avez besoin ; l’écran de consentement les répertorie.
- Si votre application est un assistant conversationnel ou un agent, ajoutez resource=https://qrflow.codes/mcp à la requête d’autorisation et communiquez plutôt avec le serveur MCP ; le jeton lui sera associé.
Zapier, Make, n8n : sans aucun code
Quand : vous voulez que les scans ou les nouveaux codes arrivent dans une feuille de calcul, un canal Slack ou un CRM.
- Créez un déclencheur de webhook entrant (Zapier : Webhooks by Zapier › Catch Hook ; Make : Custom webhook ; n8n : nœud Webhook) et copiez son URL https.
- Sur Account › Webhooks, ajoutez cette URL et choisissez les événements. Cliquez sur Test ; le ping apparaît dans l’outil et indique la structure des données.
- Associez data.scans[] (pour un scan) ou data.code (pour code.*) à votre feuille, message ou enregistrement.
- Pour créer des codes depuis ces outils, utilisez leur module HTTP avec POST /codes et l’en-tête Authorization. Conservez la clé dans le gestionnaire d’identifiants de l’outil.
- Zapier propose désormais une application QRFLOW.codes : ses étapes Create QR Code, Update QR Code et Find, ainsi que son déclencheur instantané New Scan, ne nécessitent ni configuration de webhook ni clé API. Consultez QRFLOW avec Zapier. Les étapes ci-dessous concernent Make, n8n et les autres outils.
- Ces outils ne peuvent pas vérifier la signature. L’URL qu’ils vous fournissent est impossible à deviner ; c’est votre seule protection. Ne la publiez nulle part.
- Si votre liste se trouve déjà dans Google Sheets, vous n’avez peut-être pas besoin d’un webhook : le module complémentaire QRFLOW pour Google Sheets crée un code par ligne et inscrit le lien court et le nombre de scans dans la feuille, avec Premium et sans clé API. Consultez le module complémentaire Google Sheets.
Programmation assistée par IA
Prompts à coller
Les assistants de programmation produisent le bon résultat lorsqu’on leur indique les règles dès le départ. Ces prompts contiennent les règles. Collez-en un, remplissez le champ entre crochets et l’assistant lira la référence Markdown avant d’écrire la moindre ligne.
Ajouter des codes QR à mon application
Claude, ChatGPT, Cursor, Codex, Windsurf, Copilot Chat : collez dans la conversation
Add QR codes to this project using the QRFLOW.codes API.
Read https://qrflow.codes/llms-full.txt before writing code; it is the complete reference.
Rules:
- The API key is in the environment variable QRFLOW_KEY. It must only be used server-side (route handler, server action, edge function). Never expose it to the browser.
- Create dynamic codes: POST https://qrflow.codes/api/v1/codes with { "type": "url", "destination_data": { "url": ... }, "label": ... }.
- Save the returned code.id and code.short_url on my record. short_url is what gets printed or displayed.
- Show the image by proxying GET /codes/:id/image.svg through my server, or by encoding short_url with a QR library on the client.
- Handle errors from the JSON body: { "error", "message" }. Map 402 to "upgrade needed", 429 to a retry with the Retry-After header.
What I want: [describe the feature, e.g. "every event in my events table gets a QR code that opens its public page; show it on the event admin page with a download button"].
Présenter QRFLOW à votre dépôt
Ajoutez-le à CLAUDE.md, AGENTS.md,.cursorrules ou.github/copilot-instructions.md
## QR codes (QRFLOW.codes)
- Docs: https://qrflow.codes/llms-full.txt (Markdown), https://qrflow.codes/api/v1/openapi.json (OpenAPI 3.1).
- Base URL https://qrflow.codes/api/v1, header Authorization: Bearer $QRFLOW_KEY. Server-side only.
- Codes are created with POST /codes { type: "url", destination_data: { url }, label }. Store code.id and code.short_url.
- Change the destination with PATCH /codes/:id { destination_data: { url } }. Never change slug/domain_id after printing.
- Image: GET /codes/:id/image.svg (needs the key). Prefer paused: true over DELETE when a print exists.
- Webhooks arrive as POST with X-QRFLOW-Signature (t=,v1=HMAC-SHA256 of "t.rawBody"); verify with the raw body.
Dans Lovable, Bolt, v0, Replit et d’autres générateurs d’applications
Générateurs axés sur le front-end qui fournissent un backend (Supabase, fonctions serverless)
Integrate QRFLOW.codes QR codes. The API refuses browser calls, so create a backend function (Supabase Edge Function / serverless function) that holds the secret QRFLOW_KEY and calls POST https://qrflow.codes/api/v1/codes with { "type": "url", "destination_data": { "url": "<the page URL>" }, "label": "<name>" }. Return code.id and code.short_url to the UI and save them in the database. Render the QR in the UI by encoding short_url with a QR library; add a "Download for print" button that fetches /codes/:id/image.svg through the same backend function. Reference: https://qrflow.codes/llms-full.txt
Un GPT personnalisé qui gère mes codes
ChatGPT › Créer un GPT › Actions
Import from URL: https://qrflow.codes/api/v1/openapi.json
Authentication: API Key › Bearer › paste a Business key with the scopes you want the GPT to have.
Then the GPT can list, create, re-point and report on your codes. For a no-setup version, add the MCP connector instead (Developer mode › Plugins › https://qrflow.codes/mcp).
Choses à dire une fois le connecteur activé
Claude, ChatGPT, Claude Code avec le serveur MCP QRFLOW connecté
"Make a QR code for https://example.com/fall-menu, call it Fall menu, frame caption 'Scan for menu'."
"Which of my codes got the most scans this month? Show a breakdown by country for the top one."
"Point the 'Lobby poster' code at https://example.com/events/october."
"Name the 'Business card' code's link 'hi' on my domain."
"Pause every code with 'Summer' in the label."
"Make 40 codes, one per table, going to https://example.com/order?table=1 through 40."
"Show me the PNG of the 'Front door' code."
Serveur MCP
L’utiliser depuis Claude, ChatGPT, Cursor et Claude Code
QRFLOW est un serveur MCP à https://qrflow.codes/mcp. Connectez-le une fois, connectez-vous, puis dites par exemple « crée un code QR pour la page de notre menu d’automne, nommé menu sur mon domaine », « redirige le code de l’affiche du hall vers la nouvelle page » ou « combien de scans le prospectus a-t-il reçus la semaine dernière, par pays ? ». L’assistant dispose des mêmes outils que cette API, selon les mêmes règles, et les codes apparaissent dans votre tableau de bord avec mcp comme source.
Vous n’êtes pas développeur ? La version en langage courant, avec les étapes exactes pour chaque assistant, se trouve dans Créer des codes QR avec votre assistant IA.
Évalué indépendamment et soumis à un contrôle de disponibilité toutes les heures par Glama, et répertorié dans l’annuaire awesome-remote-mcp-servers ainsi que dans le registre MCP officiel sous le nom codes.qrflow/qrflow.
Connexion
Customize › Connectors › Add custom connector › collez l’adresse, ou cliquez sur Connect dans la fiche de QRFLOW. Claude ouvre une page de connexion QRFLOW ; cliquez sur Allow. Disponible avec tous les forfaits.
https://qrflow.codes/mcp
Settings › Security and login › activez Developer mode, puis Settings › Plugins › + › collez l’adresse ; connectez-vous lorsque vous y êtes invité. Forfaits Plus, Pro, Team, Enterprise et Edu.
https://qrflow.codes/mcp
Une commande, puis /mcp pour vous connecter. Ajoutez une clé Business comme en-tête pour ignorer la connexion.
claude mcp add --transport http qrflow https://qrflow.codes/mcp
# or, with a key:
claude mcp add --transport http qrflow https://qrflow.codes/mcp --header "Authorization: Bearer $QRFLOW_KEY"
Cursor, Windsurf, VS Code, tout client MCP
Ajoutez un serveur HTTP à l’URL. La connexion OAuth s’effectue dans le navigateur ; vous pouvez aussi transmettre une clé dans un en-tête Authorization.
{
"mcpServers": {
"qrflow": { "type": "http", "url": "https://qrflow.codes/mcp" }
}
}
Votre propre agent (SDK Anthropic ou OpenAI)
Pointez le connecteur ou l’outil MCP vers l’URL avec une clé Business comme jeton bearer ; aucun flux de navigateur n’est nécessaire.
// Anthropic Messages API, MCP connector
mcp_servers: [{ type: "url", url: "https://qrflow.codes/mcp", name: "qrflow", authorization_token: process.env.QRFLOW_KEY }]
Ce que l’assistant peut faire
| Outil | Fonction | Portée |
|---|---|---|
| list_code_kinds | Tous les types de codes, leurs champs et le forfait requis. L’assistant appelle cet outil avant de créer un code inhabituel. | profile |
| list_domains | Vos domaines de liens, le domaine par défaut et leurs ids. | domains:read |
| get_qr_image | Un PNG que l’assistant peut afficher ou enregistrer, ainsi que l’URL SVG pour l’impression. | codes:read |
| get_account | Le forfait, les fonctionnalités et les limites du compte. | profile |
Comment la sécurité est assurée
- L’assistant ne détient qu’un jeton pour votre compte, émis après que vous avez cliqué sur Allow sur une page QRFLOW. Vous pouvez le déconnecter à tout moment dans Account › Connected apps.
- Les jetons sont liés au serveur MCP ; ils ne peuvent pas être réutilisés avec l’API REST.
- Chaque écriture suit les mêmes validations que le tableau de bord : destinations autorisées, vérification du forfait et limites d’utilisation raisonnable.
- Les outils destructifs décrivent soigneusement leur fonctionnement :
delete_qr_codeindique au modèle de privilégier la mise en pause lorsqu’un code a été imprimé. - Les documents de découverte se trouvent à
/.well-known/oauth-authorization-serveret/.well-known/oauth-protected-resource; l’enregistrement suit la RFC 7591 ; PKCE S256 uniquement.
SDK et spécification OpenAPI
- TypeScript / JavaScript :
npm install qrflow(npm). Aucune dépendance, ESM et CommonJS, typage complet ; fonctionne avec Node 18+, Bun, Deno et Workers. Gère les nouvelles tentatives pour les réponses 429 et fournitverifyWebhook/parseWebhook. - Python 3.9+, bibliothèque standard uniquement : qrflow.py.
- OpenAPI 3.1 : /api/v1/openapi.json. Importez-le dans Postman ou Insomnia, générez un client dans n’importe quel langage ou associez-le à une action ChatGPT.
- Les deux clients lèvent une erreur typée (
QRFlowErroravecstatus,code,message,retryAfter) et fournissent un vérificateur de webhook. Le fichier source TypeScript autonome est toujours disponible à l’adresse /sdk/qrflow.ts si vous préférez l’intégrer directement à votre projet.
| TypeScript | Python | Appels |
|---|---|---|
| me() | me() | GET /me |
| catalog() | catalog() | GET /catalog |
| listCodes({ limit, q }) | list_codes(limit, q) | GET /codes |
| getCode(id) | get_code(id) | GET /codes/:id |
| createCode(input) | create_code(**fields) | POST /codes |
| updateCode(id, patch) | update_code(id, **patch) | PATCH /codes/:id |
| deleteCode(id) | delete_code(id) | DELETE /codes/:id |
| makeDynamic(id) | make_dynamic(id) | POST /codes/:id/dynamic |
| scans(id, { from, to, group }) | scans(id, from_, to, group) | GET /codes/:id/scans |
| bulkCreate(rows, colors) | bulk_create(rows, **colors) | POST /codes/bulk |
| domains() | domains() | GET /domains |
| listWebhooks() / createWebhook() / testWebhook(id) / deleteWebhook(id) | list_webhooks() / create_webhook() / test_webhook(id) / delete_webhook(id) | /webhooks |
| imageUrl(id, size) | image_url(id, size) | Adresse de l’image (à récupérer avec la clé) |
| verifyWebhook(raw, header, secret) | verify_webhook(raw, header, secret) | Vérification de la signature des livraisons |
Référence des points de terminaison
URL de base https://qrflow.codes/api/v1. Les corps et les réponses sont au format JSON. Les dates sont au format ISO 8601 UTC. N’envoyez que les champs modifiés avec PATCH.
GETprofile
Formule, indicateurs de fonctionnalités et limites applicables à ce compte, ainsi que les autorisations de la clé.
curl https://qrflow.codes/api/v1/me \
-H "Authorization: Bearer $QRFLOW_KEY"
{ "id": "…", "email": "ops@example.com", "plan": "business", "paid": true,
"features": { "dynamic_codes": true, "custom_domain": true, "link_names": true, "gs1": true, "api_keys": true },
"limits": { "saved_codes": 25000, "bulk_per_month": 10000, "bulk_per_request": 2000, "link_domains": 5, "requests_per_minute": 600 },
"auth": "api_key", "scopes": ["codes:read", "codes:write"] }
GETpublic
Types natifs (url, wifi, vcard, email, phone, sms, text, location) et une cinquantaine de sous-types (Instagram, avis Google, Wi-Fi, boutique d’applications…), chacun avec les champs requis et la formule nécessaire. Aucune clé requise.
curl https://qrflow.codes/api/v1/catalog
GETcodes:read
Du plus récent au plus ancien.?limit= jusqu’à 100,?q= recherche dans les libellés.
curl "https://qrflow.codes/api/v1/codes?limit=20&q=menu" \
-H "Authorization: Bearer $QRFLOW_KEY"
POSTcodes:write
Mêmes règles que pour l’enregistrement sur le site : les codes url, phone, email, sms et location sont dynamiques avec les formules payantes ; les codes Wi-Fi, vCard et text intègrent leur contenu dans le motif. Indiquez un identifiant de sous-type dans destination_data.subtype pour créer, par exemple, un code d’avis Google. Le paramètre facultatif domain_id permet de choisir le domaine de liens utilisé pour imprimer le code (GET /domains les répertorie).
curl -X POST https://qrflow.codes/api/v1/codes \
-H "Authorization: Bearer $QRFLOW_KEY" \
-H "Content-Type: application/json" \
-d '{ "type": "url", "destination_data": { "url": "https://example.com/menu" }, "label": "Table tents", "frame_style": "caption-below", "frame_caption": "Scan for menu" }'
{ "code": { "id": "…", "label": "Table tents", "kind": "url", "dynamic": true, "short_code": "x7k2p9a",
"short_url": "https://go.example.com/x7k2p9a", "scans": 0, "image_url": "https://qrflow.codes/api/v1/codes/…/image.svg", … } }
GETcodes:read
Le code avec son nombre de scans, son lien court et l’adresse de son image.
curl https://qrflow.codes/api/v1/codes/$ID \
-H "Authorization: Bearer $QRFLOW_KEY"
PATCHcodes:write
Champs possibles : destination_data (codes dynamiques uniquement, l’impression reste valide), label, paused, expires_at (ISO ou null), slug (nom du lien sur votre domaine), domain_id (domaine de liens utilisé pour imprimer ce code ; null = domaine par défaut du compte), fg_color, bg_color, frame_style, frame_caption, frame_caption2. N’envoyez que les champs que vous modifiez.
curl -X PATCH https://qrflow.codes/api/v1/codes/$ID \
-H "Authorization: Bearer $QRFLOW_KEY" \
-H "Content-Type: application/json" \
-d '{ "destination_data": { "url": "https://example.com/menu-fall" }, "slug": "menu" }'
DELETEcodes:write
Suppression définitive, y compris de l’historique des scans. Le lien imprimé d’un code dynamique cesse de fonctionner. Préférez paused: true si le code est déjà imprimé.
curl -X DELETE https://qrflow.codes/api/v1/codes/$ID \
-H "Authorization: Bearer $QRFLOW_KEY"
204 No Content
POSTcodes:write
Le motif imprimé change (il encode désormais le lien court) ; générez donc à nouveau l’image.
curl -X POST https://qrflow.codes/api/v1/codes/$ID/dynamic \
-H "Authorization: Bearer $QRFLOW_KEY"
GETcodes:read
SVG prêt à imprimer avec le cadre et les couleurs.?size= définit la largeur de la grille des modules en px ; le fichier peut de toute façon être redimensionné sans perte.
curl https://qrflow.codes/api/v1/codes/$ID/image.svg \
-H "Authorization: Bearer $QRFLOW_KEY" -o code.svg
GETanalytics:read
?from= et?to= (dates ISO, jusqu’à 92 jours, 30 derniers jours par défaut) et?group= day, device, country, city, browser, os ou referrer. Les mêmes chiffres que sur la page d’analytique.
curl "https://qrflow.codes/api/v1/codes/$ID/scans?from=2026-09-01&to=2026-09-21&group=day" \
-H "Authorization: Bearer $QRFLOW_KEY"
{ "code_id": "…", "from": "…", "to": "…", "group": "day", "total": 412,
"rows": [ { "key": "2026-09-01", "scans": 18 }, { "key": "2026-09-02", "scans": 25 }, … ] }
POSTcodes:write
Jusqu’à 2 000 codes URL par appel, tous dynamiques. Décomptés de la même allocation mensuelle de création en masse que la page Bulk (10 000 avec Business). Les lignes qui ne sont pas des adresses Web sont renvoyées dans rejected ; les autres sont créées.
curl -X POST https://qrflow.codes/api/v1/codes/bulk \
-H "Authorization: Bearer $QRFLOW_KEY" \
-H "Content-Type: application/json" \
-d '{ "rows": [ { "destination": "https://example.com/t/1", "label": "Table 1" }, { "destination": "https://example.com/t/2", "label": "Table 2" } ] }'
{ "codes": [ … ], "rejected": [], "remaining_this_month": 9998 }
GETcodes:read
Les codes destinés aux emballages de vente au détail. Chaque produit correspond à un GTIN, à l’adresse imprimée sur l’emballage et aux liens associés. Recherchez par nom et GTIN avec?q=. Formule Business.
curl https://qrflow.codes/api/v1/products \
-H "Authorization: Bearer $QRFLOW_KEY"
{ "products": [ { "gtin": "00860001234565", "name": "Wildflower Honey 12 oz",
"digital_link": "https://id.example.com/01/00860001234565",
"page_url": "https://id.example.com/p/00860001234565",
"links": [ { "link_type": "gs1:pip", "url": "…", "is_default": true, "batch": null } ] } ] }
POSTcodes:write
gtin et name sont obligatoires ; brand et url sont facultatifs. Le chiffre de contrôle est vérifié avant toute écriture, et les formats à 8, 12, 13 et 14 chiffres sont tous normalisés à 14 chiffres. Un GTIN que vous possédez déjà entraîne une réponse 409 au lieu de créer un deuxième produit.
curl -X POST https://qrflow.codes/api/v1/products \
-H "Authorization: Bearer $QRFLOW_KEY" -H "Content-Type: application/json" \
-d '{"gtin":"00860001234565","name":"Wildflower Honey 12 oz","brand":"Sunny Acres","url":"https://sunnyacres.example/honey"}'
{ "product": { "gtin": "00860001234565", "digital_link": "https://id.example.com/01/00860001234565", … } }
PUTcodes:write
Un GTIN peut mener à plusieurs destinations à la fois, chacune indiquée par son usage. Un téléphone reçoit la destination par défaut ; une application qui demande un type reçoit celle correspondant à ce type. Idempotent : si link_type et batch sont identiques, le lien est remplacé au lieu d’être ajouté une deuxième fois, ce qui permet d’exécuter deux fois un script nocturne. Transmettez batch pour associer le lien à un lot précis ; c’est ainsi que vous publiez un rappel sans toucher au reste de la production.
curl -X PUT https://qrflow.codes/api/v1/products/00860001234565/links \
-H "Authorization: Bearer $QRFLOW_KEY" -H "Content-Type: application/json" \
-d '{"link_type":"gs1:recallStatus","url":"https://sunnyacres.example/recall-a42","title":"Recall notice","batch":"A42","is_default":true}'
GETanalytics:read
Nombre de scans par GTIN pour les?days= derniers jours (de 1 à 365, 30 par défaut), ventilé par pays, appareil, type de lien et lot. went_nowhere compte les scans sans destination trouvée et devrait être égal à zéro.
curl "https://qrflow.codes/api/v1/products/00860001234565/scans?days=30" \
-H "Authorization: Bearer $QRFLOW_KEY"
{ "gtin": "00860001234565", "days": 30, "total": 412, "went_nowhere": 0,
"by_link_type": [ { "key": "gs1:pip", "scans": 390 }, { "key": "gs1:recallStatus", "scans": 22 } ],
"by_batch": [ { "key": "A42", "scans": 22 } ] }
GETdomains:read
Vos domaines connectés, leur état et celui utilisé par défaut pour imprimer les codes dynamiques (default_base). Transmettez l’identifiant d’un domaine dans domain_id sur un code pour l’imprimer avec un autre domaine.
curl https://qrflow.codes/api/v1/domains \
-H "Authorization: Bearer $QRFLOW_KEY"
GETwebhooks:manage
Vos webhooks, avec leurs événements, leur dernier état et leur nombre d’échecs.
curl https://qrflow.codes/api/v1/webhooks \
-H "Authorization: Bearer $QRFLOW_KEY"
POSTwebhooks:manage
url doit être une adresse https sur un hôte public ; events peut être scan, code.created, code.updated ou code.deleted. Le secret de signature n’est renvoyé qu’une seule fois.
curl -X POST https://qrflow.codes/api/v1/webhooks \
-H "Authorization: Bearer $QRFLOW_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://example.com/hooks/qrflow", "events": ["scan", "code.updated"] }'
{ "webhook": { "id": "…", "url": "…", "events": ["scan", "code.updated"], "active": true, "secret": "whsec_…" } }
POSTwebhooks:manage
Envoie immédiatement un ping signé et indique la réponse.
curl -X POST https://qrflow.codes/api/v1/webhooks/$WEBHOOK_ID \
-H "Authorization: Bearer $QRFLOW_KEY"
DELETEwebhooks:manage
Arrête toutes les livraisons, y compris les nouvelles tentatives en attente.
curl -X DELETE https://qrflow.codes/api/v1/webhooks/$WEBHOOK_ID \
-H "Authorization: Bearer $QRFLOW_KEY"
204 No Content
GETpublic
Identifiants des cadres et éléments requis pour chacun (légende, deuxième ligne), regroupés comme dans le personnalisateur. Aucune clé requise.
curl https://qrflow.codes/api/v1/frames
L’objet Code
Tous les points de terminaison qui manipulent un code renvoient la même structure. Ignorez les champs que vous ne connaissez pas ; de nouveaux champs sont ajoutés au fil du temps.
| Champ | Type | Signification |
|---|---|---|
| id | uuid | Identifiant stable. Utilisez-le dans tous les autres appels. |
| label | string | null | Nom affiché dans le tableau de bord. Jusqu’à 120 caractères. Recherchable avec?q=. |
| kind | string | Identifiant du catalogue : url, wifi, instagram, googlereview,... kind_label est le nom lisible. |
| type | string | Encodage : url, text, wifi, vcard, email, phone, sms, location. |
| destination_data | object | Champs envoyés (plus subtype pour les types). destination en est un résumé sur une ligne. |
| dynamic | boolean | Vrai lorsque les scans passent par QRFLOW et que la destination peut changer. dynamic_capable indique si ce type peut être dynamique avec une formule payante. |
| short_code | string | Sept caractères, ne change jamais. |
| short_url | string | Adresse à imprimer pour un code dynamique. Inclut votre domaine et votre slug, le cas échéant. |
| domain_id | uuid | null | Domaine de liens utilisé pour imprimer ce code ; null signifie le domaine par défaut du compte. |
| fg_color, bg_color | hex | Couleurs des modules et de l’arrière-plan. |
| has_logo | boolean | Un logo a été ajouté dans le tableau de bord ; image.svg l’inclut. |
| frame_style, frame_caption, frame_caption2 | string | null | Identifiant du cadre et légendes, comme dans le personnalisateur. |
| scans | integer | Nombre total de scans depuis la création. |
| created_at, updated_at | ISO 8601 | UTC. |
| manage_url | url | Page du code dans le tableau de bord, pour un lien « Ouvrir dans QRFLOW ». |
| image_url | url | GET /codes/:id/image.svg. Nécessite l’en-tête Authorization ; ce n’est pas une URL d’image publique. |
| svg_download_url, png_download_url | url | Le même SVG (cadre, couleurs, logo) et un PNG simple, accessibles par des liens signés valides pendant 24 heures sans en-tête : pour les balises <img>, les scripts et les assistants qui enregistrent un fichier. download_expires_at indique leur date d’expiration ; chaque lecture du code en génère de nouveaux. |
Autres structures : Scans (code_id, from, to, group, total, rows[key, scans]), Domain (id, host, status, active, is_default, verified_at, grace_until), Webhook (id, url, events, active, last_status, last_delivery_at, consecutive_failures, plus secret une fois), Me (id, email, plan, paid, features, limits, auth, scopes) et Error (error, message). Le document OpenAPI définit le type de chaque propriété.
Business
Webhooks
QRFLOW appelle votre URL https lorsqu’un événement se produit. Créez-en un dans Compte › Webhooks ou avec POST /webhooks ; le secret de signature ne vous est communiqué qu’une seule fois. Jusqu’à 10 par compte.
| Événement | Quand | data |
|---|---|---|
| scan | Par lots : toutes les quelques minutes, tous les nouveaux scans depuis la dernière livraison, jusqu’à 500 par appel. | count, from, to, scans[] avec code_id, label, short_code, slug, scanned_at, device, country, city, referrer, browser, os, language |
| code.created | Immédiatement depuis l’API et les assistants ; en quelques minutes depuis le tableau de bord. Une requête groupée envoie un seul événement avec bulk: true et codes[]. | code, source |
| code.updated | Même délai. Couvre la destination, le libellé, la mise en pause, l’expiration, le nom du lien, le domaine, les couleurs, le cadre et la conversion en code dynamique. | code, changed[] (noms des champs modifiés) |
| code.deleted | Même délai. | code: { id, label, short_code, slug } |
| ping | Lorsque vous cliquez sur Test. | webhook_id, message |
Contenu reçu
Chaque charge utile est { id, event, created_at, data }. id reste stable lors des nouvelles tentatives d’une même livraison ; vous pouvez donc l’utiliser pour dédupliquer.
{
"id": "9b1c6d2e-…",
"event": "scan",
"created_at": "2026-09-21T18:05:00.000Z",
"data": {
"count": 2,
"from": "2026-09-21T18:00:00.000Z",
"to": "2026-09-21T18:04:12.331Z",
"scans": [
{ "code_id": "…", "label": "Table tents", "short_code": "x7k2p9a", "slug": "menu", "scanned_at": "2026-09-21T18:03:40.101Z",
"device": "mobile", "country": "US", "city": "Las Vegas", "referrer": null, "browser": "Safari", "os": "iOS", "language": "en-US" },
{ "code_id": "…", "label": "Table tents", "short_code": "x7k2p9a", "slug": "menu", "scanned_at": "2026-09-21T18:04:12.331Z",
"device": "mobile", "country": "MX", "city": "Tijuana", "referrer": null, "browser": "Chrome", "os": "Android", "language": "es-MX" }
]
}
}
{
"id": "2f0a…",
"event": "code.updated",
"created_at": "2026-09-21T18:06:00.000Z",
"data": {
"code": { "id": "…", "label": "Table tents", "kind": "url", "dynamic": true, "short_url": "https://go.example.com/menu", "scans": 412, "…": "…" },
"changed": ["destination_data"]
}
}
POST /your/endpoint HTTP/1.1
Content-Type: application/json
User-Agent: QRFLOW-Webhooks/1.0 (+https://qrflow.codes/developers)
X-QRFLOW-Event: scan
X-QRFLOW-Signature: t=1758477900,v1=5f1c…e9
Vérifier la signature
X-QRFLOW-Signature: t=<unix seconds>,v1=<hex>. Calculez le HMAC-SHA256 sur ${t}.${rawBody} avec votre secret et comparez-le à v1 en temps constant ; rejetez la requête si t date de plus de cinq minutes. Utilisez les octets bruts reçus, jamais un objet sérialisé à nouveau. Des récepteurs fonctionnels pour Next.js et Python sont disponibles dans les recettes, et les deux SDK incluent l’utilitaire.
Règles de livraison
- Répondez par n’importe quel code 2xx dans les 8 secondes. Effectuez le traitement après avoir répondu.
- Toute autre réponse entraîne de nouvelles tentatives après 1, 5, 15, 60, 240 et 720 minutes.
- Vingt échecs consécutifs désactivent le webhook et envoient un e-mail au propriétaire du compte. Réactivez-le une fois le récepteur corrigé ; les nouvelles tentatives en attente reprendront.
- Les URL doivent être des adresses https sur un hôte public. localhost, les plages privées et qrflow.codes sont refusés. Utilisez un tunnel pendant le développement.
- Cliquez sur Test pour recevoir un
pingsigné et voir le statut renvoyé par votre serveur.
Erreurs
Chaque erreur est { "error": "<code>", "message": "<what to do>" } avec le statut indiqué ci-dessous. Le message est rédigé pour une personne ; affichez-le.
| Statut | error | Signification |
|---|
Symptôme, cause, solution
Dépannage
401 invalid_token à chaque appel
PourquoiL’en-tête est incorrect ou la clé n’est pas active.
SolutionEnvoyez exactement Authorization: Bearer qrf_live_… (avec une espace, pas deux-points). Vérifiez que la clé n’a pas été révoquée dans Compte › Clés API. Si vous l’avez copiée depuis une conversation ou un document, vérifiez qu’elle ne se termine pas par un point ou un guillemet typographique.
401 sur /api/v1 avec un jeton qui fonctionne sur le serveur MCP
PourquoiLes jetons émis pour https://qrflow.codes/mcp lui sont associés.
SolutionUtilisez une clé API pour REST ou exécutez un deuxième flux OAuth sans resource= pour obtenir un jeton pour l’API REST.
402 upgrade_required lors de la création d’une clé ou d’un webhook
PourquoiLes deux sont des fonctionnalités Business.
SolutionPassez à une formule supérieure sur /pricing ou utilisez le serveur MCP, qui fonctionne avec toutes les formules après connexion.
402 sur POST /codes depuis une application OAuth
PourquoiLa formule de l’utilisateur ne comprend pas la fonctionnalité demandée par l’application (un code dynamique, un domaine).
SolutionConsultez d’abord les fonctionnalités de GET /me et adaptez-vous : créez quand même le code (il sera statique avec Free) ou indiquez à l’utilisateur les exigences de la formule.
403 insufficient_scope
PourquoiLes autorisations sont définies lors de la création d’une clé. Corrigez : créez une nouvelle clé avec les autorisations nécessaires et révoquez l’ancienne. Pour OAuth, demandez l’autorisation dans la requête authorize.
400 not_dynamic lors d’un PATCH de destination_data
Pourquoi : le code est statique : un type Wi-Fi/vCard/texte, ou un code créé avec l’offre Free après avoir déjà utilisé l’unique code dynamique gratuit.
Corrigez : pour url/phone/email/sms/location, envoyez POST /codes/:id/dynamic tant que le compte dispose encore de son quota, puis téléchargez et réimprimez le code (l’image change). Les codes Wi-Fi, vCard et texte ne peuvent jamais être dynamiques ; créez plutôt un code url qui ouvre une page.
400 no_domain lors de la définition du slug
Pourquoi : les noms de liens sont associés à votre domaine.
Corrigez : connectez un domaine et vérifiez-le d’abord sur la page Account. Sur qrflow.codes/q, le chemin est toujours le short_code.
409 conflict sur le slug
Pourquoi : un autre de vos codes porte déjà ce nom.
Corrigez : utilisez GET /codes?q= pour le trouver, ou choisissez un autre nom. Les noms sont propres à chaque compte, pas globaux.
Erreur CORS dans la console du navigateur
Pourquoi : l’API n’accepte que les appels de serveur à serveur (et Canva). C’est volontaire : une clé dans une page web est une clé divulguée.
Corrigez : déplacez l’appel dans un gestionnaire de route, une action serveur, une fonction edge ou un backend, puis appelez-le depuis la page.
L’image affiche une marque QRFLOW
Pourquoi : le code a été créé par une personne qui n’est pas connectée. La marque apparaît uniquement sur les téléchargements anonymes.
Corrigez : n’importe quel compte la supprime, y compris l’offre gratuite. Les images d’un code enregistré ne l’affichent jamais.
short_url indique toujours qrflow.codes/q/… après l’ajout de mon domaine
Pourquoi : le domaine n’est pas encore vérifié, ou son CNAME est incorrect.
Corrigez : vérifiez le statut sur la page Account ou avec GET /domains (le statut doit être verified). Les codes existants basculent automatiquement une fois le domaine vérifié.
image_url renvoie 401 dans une balise <img>
Pourquoi : cette URL nécessite l’en-tête Authorization, qu’un <img> ne peut pas envoyer.
Corrigez : utilisez svg_download_url ou png_download_url du même objet Code : ces liens signés fonctionnent pendant 24 heures sans en-tête. Pour une solution permanente, faites passer image_url par votre serveur (voir la recette Next.js) ou encodez vous-même short_url.
Il me faut un PNG, pas un SVG
Pourquoi : le SVG contient le cadre et le logo ; le PNG est le code seul.
Corrigez : GET /codes/:id/image.png (avec un bearer ou le lien signé png_download_url) renvoie un PNG de 256 à 2048 px. Pour obtenir un PNG avec le cadre, convertissez le SVG avec sharp ou resvg (sharp(svgBuffer).png().toBuffer()).
Mon assistant a indiqué que le point de terminaison d’image refusait la requête et a dessiné le code lui-même
Pourquoi : il a récupéré image_url, qui nécessite un bearer.
Corrigez : chaque code contient désormais png_download_url et svg_download_url, et get_qr_image les renvoie ; l’assistant peut les récupérer avec curl sans se connecter. Un code dessiné localement qui encode le même short_url fonctionne toujours et comptabilise toujours les scans, mais il n’a ni cadre ni logo.
Le webhook n’arrive jamais
Pourquoi : les règles relatives à l’URL ou le récepteur.
Corrigez : l’URL doit utiliser https et pointer vers un hôte public (pas localhost, pas d’IP privée, pas qrflow.codes). Cliquez sur Test dans le webhook : le résultat indique le statut renvoyé par votre serveur. Les événements de scan sont regroupés et peuvent prendre jusqu’à environ cinq minutes ; les événements code.* du tableau de bord sont également mis en file d’attente pendant quelques minutes, tandis que les écritures API et MCP sont livrées immédiatement.
La signature n’est jamais vérifiée
Pourquoi : vous avez signé un corps sérialisé à nouveau.
Corrigez : vérifiez la signature à partir des octets bruts exacts reçus, avant l’analyse JSON. Dans Express, utilisez express.raw({ type: 'application/json' }) sur cette route ; dans Next.js App Router, utilisez await req.text() ; dans Flask, request.get_data(). Calculez ensuite le HMAC-SHA256 de ${t}.${raw}\.
Le webhook s’est désactivé tout seul
Pourquoi : vingt échecs consécutifs.
Corrigez : réparez le récepteur, puis réactivez-le (Account › Webhooks, ou supprimez-le et recréez-le). Vous avez reçu un e-mail lorsque cela s’est produit. Les nouvelles tentatives en attente reprennent.
Livraisons de webhook en double
Pourquoi : une réponse 2xx lente (plus de 8 secondes) est considérée comme un échec et entraîne une nouvelle tentative.
Corrigez : répondez d’abord, puis traitez la requête. Dédupliquez à l’aide de l’id du payload, qui reste stable lors des nouvelles tentatives.
429 rate_limited pendant un import
Pourquoi : 600 requêtes par minute et par clé.
Corrigez : utilisez POST /codes/bulk (2 000 codes dans une requête) au lieu d’envoyer un POST par code, ou attendez le nombre de secondes indiqué par Retry-After.
J’ai supprimé un code et l’affiche imprimée indique maintenant « Code not found »
Pourquoi : la suppression est définitive et invalide le lien.
Corrigez : il n’y a pas d’annulation possible. La prochaine fois, utilisez PATCH { paused: true } ; un code en pause affiche une page conviviale et peut être réactivé.
Ma clé a cessé de fonctionner après le passage à une offre inférieure
Pourquoi : les clés restent actives pendant 30 jours après la résiliation de Business, puis renvoient 402.
Corrigez : réabonnez-vous ; rien n’a été supprimé et les mêmes clés fonctionneront à nouveau.
Vous ne trouvez pas votre problème dans la liste ? Écrivez à hello@qrflow.codes en joignant la requête exacte et l’erreur JSON reçue. Les comptes Business bénéficient d’une assistance prioritaire.
Limites et utilisation raisonnable
| Limite | |
|---|---|
| Requêtes par minute et par clé | 600. Au-delà, réponse 429 avec Retry-After. |
| Clés par compte | 10 |
| Webhooks par compte | 10 |
| Codes enregistrés (utilisation raisonnable) | 1 000 Premium, 25 000 Business ; l’API s’arrête au double de cette limite. |
| Envoi groupé | 500/mois (500 par requête) Premium ; 10 000/mois (2 000 par requête) Business. |
| Domaines de liens | 1 Premium, 5 Business |
| Scans | Illimités. E-mail de vérification à 100 000 scans par code et par mois avec Premium, 1 000 000 avec Business ; aucune limitation de débit. |
| Période d’analyse des scans | 92 jours par requête |
| Taille des pages de liste | 100 (?limit=) |
| Libellé / légendes / slug | 120 / 60 / 40 caractères |
| Délai d’expiration et nouvelles tentatives des webhooks | 8 secondes ; nouvelles tentatives après 1, 5, 15, 60, 240 et 720 minutes ; désactivation après 20 échecs consécutifs. |
| Après la résiliation de Business | Les clés et les webhooks restent actifs pendant 30 jours, puis renvoient 402. Rien n’est supprimé. |
L’utilisation raisonnable correspond au volume prévu par le tarif de l’offre. Aucune limitation de débit n’est appliquée à ce seuil ; l’API s’arrête au double et une personne vous contacte d’abord par e-mail. Pour des volumes supérieurs : hello@qrflow.codes.
Sécurité, pour vous et pour les personnes qui scannent
Comment QRFLOW protège votre compte
- Les clés ne sont affichées qu’une seule fois et sont stockées sous forme de hachages SHA-256. Personne chez QRFLOW ne peut retrouver une clé ; si vous la perdez, créez-en une nouvelle.
- Chaque requête est limitée au compte auquel appartient la clé. Un identifiant de code provenant d’un autre compte renvoie une 404, sans jamais divulguer de données.
- Les autorisations sont définies pour chaque clé ; une clé destinée à un tableau de bord de rapports ne peut donc pas créer ni supprimer de codes.
- 600 requêtes par minute et par clé ; au-delà, une réponse 429 claire est renvoyée, sans ralentir les autres utilisateurs.
- Les destinations sont soumises à une liste d’autorisation : http, https, mailto, tel, sms, geo et une courte liste de schémas d’applications (whatsapp, tg, signal, spotify, app stores). javascript:, data: et file: sont rejetés lors de la création ; une intégration compromise ne peut donc pas transformer vos codes en vecteur d’attaque.
- Les URL de webhook doivent utiliser https et pointer vers des hôtes publics ; QRFLOW n’appelle jamais de réseaux privés ni son propre service. Chaque livraison est signée et chaque payload possède un id stable.
- Les clients OAuth s’enregistrent avec PKCE S256 et les jetons sont liés au serveur pour lequel ils ont été émis ; un jeton destiné au serveur MCP ne peut pas être réutilisé sur l’API REST.
- Toute personne peut révoquer une clé ou déconnecter une application sur la page Account ; l’effet est immédiat.
Ce que vous devez faire de votre côté
- Utilisez des variables d’environnement, jamais le code source. Si une clé apparaît dans l’historique git, révoquez-la.
- Côté serveur uniquement. L’API refuse les origines de navigateur, mais vos propres points de terminaison qui l’encapsulent doivent également être authentifiés, sinon n’importe qui peut créer des codes à vos frais.
- Attribuez à chaque intégration sa propre clé, avec les autorisations nécessaires, et donnez-lui le nom de l’intégration. La révocation d’une clé n’affectera alors qu’un seul élément.
- Vérifiez les signatures des webhooks et rejetez les horodatages datant de plus de cinq minutes.
- Si les données de vos utilisateurs sont incluses dans les libellés ou les destinations, n’oubliez pas que QRFLOW les stocke ; évitez autant que possible d’inclure des données personnelles dans les libellés.
Données enregistrées lors des scans, et données qui ne le sont pas
- Chaque redirection enregistre le type d’appareil, le pays, la ville, le référent, le navigateur, le système d’exploitation et la langue, déduits de la requête, ainsi qu’un hachage à sens unique du code + jour + IP + agent utilisateur, afin que le propriétaire puisse compter les visiteurs uniques. Il est impossible de retrouver une adresse à partir de ce hachage.
- Aucun cookie n’est déposé sur l’appareil de la personne qui scanne et l’adresse IP elle-même n’est pas conservée avec le scan. Les robots connus et les robots d’aperçu de liens sont ignorés.
- La suppression d’un code supprime ses scans. La suppression du compte supprime tout.
- Texte intégral : https://qrflow.codes/privacy et https://qrflow.codes/terms.
Versionnement et stabilité
L’API est versionnée dans le chemin : /api/v1. Dans v1, nous ajoutons des champs, des points de terminaison, des types et des événements ; nous ne supprimons ni ne renommons rien, et votre code doit ignorer les champs inconnus dans les réponses.
Si une modification doit un jour rompre la compatibilité avec v1, elle sera publiée sous /api/v2 et v1 restera disponible pendant au moins douze mois. Les propriétaires des clés seront informés par e-mail des dépréciations 90 jours à l’avance.
Le serveur MCP suit la même règle pour ses outils : seuls des arguments sont ajoutés et chaque outil conserve son nom.
Le document OpenAPI à l’adresse /api/v1/openapi.json et le Markdown à l’adresse /llms-full.txt sont générés à partir du code qui sert l’API ; ils décrivent donc la version actuellement en production.
Questions fréquentes des développeurs
Dois-je payer pour utiliser l’API QRFLOW ?
Les clés API sont incluses dans l’offre Business, à 29 $ par mois, sans engagement. Le serveur MCP (Claude, ChatGPT, Cursor, Claude Code) et OAuth pour votre propre application fonctionnent avec toutes les offres après connexion, et les créations possibles dépendent de l’offre. GET /catalog, GET /frames et /preview.svg ne nécessitent aucune clé.
Puis-je générer gratuitement des codes QR avec l’API ?
Pas avec une clé. Pour une image statique simple, le générateur gratuit sur qrflow.codes ou n’importe quelle bibliothèque QR open source fera l’affaire. L’API est destinée aux codes dynamiques, à votre propre domaine, aux analyses, à l’envoi groupé et aux webhooks, fonctionnalités incluses dans une offre payante.
Puis-je appeler l’API depuis le navigateur ?
Non. Elle refuse les origines de navigateur afin qu’une clé ne puisse jamais se retrouver dans une page web. Appelez-la depuis un gestionnaire de route, une action serveur, une fonction edge ou un backend, puis appelez celui-ci depuis votre page.
Quels formats d’image sont disponibles ?
Un SVG avec vos couleurs, votre cadre, vos légendes et votre logo (GET /codes/:id/image.svg, taille nominale de 256 à 4096 px) et un PNG simple (GET /codes/:id/image.png, de 256 à 2048 px). Les deux nécessitent un bearer, ou peuvent être récupérés avec les liens signés svg_download_url / png_download_url présents dans chaque objet Code ; ces liens fonctionnent pendant 24 heures sans en-tête. L’outil MCP get_qr_image renvoie le PNG intégré ainsi que les deux liens.
Puis-je modifier un code QR après l’avoir imprimé ?
Oui, s’il est dynamique (url, phone, email, sms, location avec une offre payante). Utilisez PATCH /codes/:id avec une nouvelle valeur destination_data ; l’image ne change pas, mais le scan suivant redirige vers la nouvelle destination. Les codes Wi-Fi, vCard et texte contiennent leur contenu dans l’image et ne peuvent pas être modifiés.
Quelle est la différence entre short_url et la destination ?
short_url est le lien intégré à l’image (go.example.com/menu). La destination est l’endroit vers lequel ce lien redirige (https://example.com/menu-fall). Vous imprimez short_url une seule fois et pouvez modifier la destination autant de fois que vous le souhaitez.
Les codes peuvent-ils utiliser mon propre domaine ?
Oui. Premium permet de connecter 1 domaine, Business 5 ; ajoutez un CNAME et vérifiez-le sur la page Account. Avec Business, vous pouvez choisir un domaine pour chaque code à l’aide de domain_id. Les noms de liens (slug) créent des chemins lisibles sur ce domaine.
Quelles informations un scan enregistre-t-il sur la personne qui scanne ?
Le type d’appareil, le pays, la ville, le référent, le navigateur, le système d’exploitation et la langue, déduits de la requête, ainsi qu’un hachage quotidien à sens unique pour compter les visiteurs uniques. Aucun cookie, et l’adresse IP n’est pas stockée. De quoi créer un graphique, mais pas identifier qui que ce soit. Détails : https://qrflow.codes/privacy#scans
Existe-t-il un package npm ou PyPI ?
npm : npm install qrflow\ (https://www.npmjs.com/package/qrflow), aucune dépendance, ESM et CommonJS, types TypeScript complets, fonctionne avec Node 18+, Bun, Deno et Workers ; il encapsule chaque point de terminaison, réessaie les requêtes 429 et inclut verifyWebhook/parseWebhook. Python : un client dans un seul fichier à l’adresse https://qrflow.codes/sdk/qrflow.py (bibliothèque standard uniquement) avec verify_webhook ; un package PyPI suivra.
Est-ce compatible avec Claude, ChatGPT, Cursor et Claude Code ?
Oui. QRFLOW est un serveur MCP à l’adresse https://qrflow.codes/mcp. Ajoutez-le comme connecteur, connectez-vous une fois et posez vos questions en langage courant. Onze outils couvrent la création, la modification, la mise en pause, le nommage, l’envoi groupé, les analyses, les images et les domaines.
Mes propres utilisateurs peuvent-ils connecter leurs comptes QRFLOW à mon application ?
Oui, avec OAuth 2.0. Enregistrez un client sur /api/oauth/register (aucun compte nécessaire), redirigez les utilisateurs vers /oauth/authorize avec PKCE, puis appelez l’API avec leur jeton. Les codes sont enregistrés dans leur compte, selon leur forfait.
Comment tester les webhooks sur localhost ?
Exposez votre serveur de développement avec un tunnel (cloudflared ou ngrok) et utilisez son adresse https comme URL de webhook, puis cliquez sur Test dans Account › Webhooks pour recevoir un ping signé. Les URL de webhook doivent être publiques et utiliser https ; localhost et les adresses privées sont refusés.
Que devient mon intégration si j’annule Business ?
Les clés et les webhooks continuent de fonctionner pendant 30 jours, puis renvoient une réponse 402. Les codes, les scans et les domaines restent dans le compte. En vous réabonnant, vous réactivez tout avec les mêmes clés.
Comment créer un code d’avis Google, Instagram, Wi-Fi ou PDF via l’API ?
GET /catalog répertorie tous les types et leurs champs. Envoyez ensuite POST /codes avec le type et les champs correspondants, en ajoutant subtype pour les types concernés : { type: 'url', destination_data: { subtype: 'googlereview', placeId: 'ChIJ…' } }, { type: 'wifi', destination_data: { ssid, password, encryption: 'WPA' } }, { type: 'url', destination_data: { subtype: 'instagram', handle: 'acme' } }.
L’API peut-elle téléverser un logo sur un code ?
Pas encore. Ajoutez le logo dans le tableau de bord ; image.svg l’inclut et has_logo indique sa présence. Les couleurs, les cadres et les légendes peuvent tous être définis via l’API.
L’API est-elle stable ?
La v1 ne fait qu’ajouter des fonctionnalités ; elle ne supprime ni ne renomme rien. Toute modification incompatible serait publiée dans une v2, tandis que la v1 resterait disponible pendant au moins douze mois, avec un préavis de 90 jours par e-mail.
Pour les agents, les outils et les assistants qui lisent ceci
Lisible par machine
Tout le contenu de cette page est disponible dans un format récupérable par logiciel. Il est entièrement généré à partir du code qui sert l’API et n’est donc jamais obsolète.
| URL | Description | |
|---|---|---|
| llms-full.txt | https://qrflow.codes/llms-full.txt | Toute cette référence au format Markdown : concepts, tous les points de terminaison, tous les outils MCP, recettes, dépannage et FAQ. Générée à partir de la même source que cette page. |
| developers.md | https://qrflow.codes/developers.md | Même document, pour les outils qui récupèrent a.md. |
| llms.txt | https://qrflow.codes/llms.txt | L’index du site destiné aux assistants, qui pointe vers cette page. |
| L’API en une page | https://qrflow.codes/qr-code-api | Fonctionnement de l’API, cas où une bibliothèque côté client est préférable et coût. La version courte de cette référence, pour décider plutôt que développer. |
| openapi.json | https://qrflow.codes/api/v1/openapi.json | OpenAPI 3.1. À importer dans Postman, Insomnia, un générateur de code ou une action ChatGPT. |
| Serveur MCP | https://qrflow.codes/mcp | HTTP en flux continu, OAuth avec enregistrement dynamique ou clé Business en tant que bearer. |
| server.json | https://qrflow.codes/.well-known/mcp/server.json | Le manifeste du registre MCP. |
| Découverte OAuth | https://qrflow.codes/.well-known/oauth-authorization-server | Métadonnées RFC 8414 ; le document sur la ressource protégée se trouve à côté. |
| Package npm | https://www.npmjs.com/package/qrflow | npm install qrflow. Client typé, sans dépendances, avec vérification des webhooks. Client Python en un seul fichier sur https://qrflow.codes/sdk/qrflow.py. |
| GitHub | https://github.com/nativecodeapps/qrflow-sdk | Clients, instantané OpenAPI et exemples exécutables pour Next.js, Workers, Express, FastAPI et les webhooks Flask. Les issues et les PR sont les bienvenues. |
Questions, idées ou suggestions de types de code à ajouter : hello@qrflow.codes. Conditions : /terms. Confidentialité : /privacy.