QRFLOW.codes
offiziellQR-Codes erstellen, gedruckte dynamische Codes neu ausrichten, Links auf der eigenen Domain benennen und Scan-Analysen lesen.
Was kann man mit QRFLOW Codes MCP machen?
- Dynamische QR-Codes erstellen — Bitte den Assistenten, einen
url-Code mitdestination_datazu erstellen und die zu druckendeshort_urlzurückzugeben. - Einen gedruckten Code neu ausrichten — Ändere das Weiterleitungsziel eines bestehenden dynamischen Codes, ohne ihn neu zu drucken, da das Bild die
short_urlenthält. - Einen Code pausieren oder ablaufen lassen — Setze
paused: trueoder ein Enddatum, statt den Code zu löschen, damit ein gedruckter Link sicher nicht mehr weiterleitet. - Scan-Analysen abrufen — Rufe die Gesamtzahl der
Scansüber die gesamte Laufzeit oder eine Aufschlüsselung nach Tag, Land und Gerät für einen Code ab. - Links unter deiner eigenen Domain benennen — Setze einen
slugwiemenuund wähle eine Link-Domain, damit der Code alsgo.example.com/menugedruckt wird. - Codes in großen Mengen erstellen — Generiere Tausende dynamischer Codes aus einer Liste und ordne die zurückgegebenen Codes anhand des Labels den Zeilen zu.
Gehosteter MCP-Server
npx add-mcp 'https://qrflow.codes/mcp'Installiert in Claude Code, Codex, Cursor und mehr
Dokumentation
QRFLOW.codes für Entwickler
Hier starten
Mit QRFLOW.codes erstellst du QR-Codes, die du nach dem Drucken ändern kannst, auf deiner eigenen Domain, mit Scan-Analysen. Außerdem kannst du all das über eine einzige API von deiner Software und deinem KI-Assistenten erledigen lassen.
Ein QR-Code ist das Bild einer Zeichenfolge. Die meisten Generatoren schreiben deine Webadresse in das Bild; ändert sich die Adresse, ist der Ausdruck unbrauchbar. QRFLOW schreibt einen Kurzlink in das Bild (go.yourbrand.com/menu oder qrflow.codes/q/x7k2p9a) und leitet darüber weiter. Du kannst das Ziel jederzeit ändern, und jeder Scan wird gezählt. Das ist ein dynamischer Code – und genau dafür lohnt sich eine API.
Die API kann genau das, was auch das Dashboard kann: Codes jeder Art erstellen, auf ein neues Ziel verweisen lassen, Links benennen, auswählen, mit welcher deiner Domains sie gedruckt werden, Scan-Zahlen abrufen, Tausende auf einmal erstellen und dich benachrichtigen lassen, wenn etwas passiert (Webhooks). Dieselben Tools sind als MCP-Server verfügbar, sodass Claude, ChatGPT, Cursor und Claude Code dein Konto in natürlicher Sprache bedienen können.
Zugriff: Für die REST-API brauchst du einen Business-API-Schlüssel (29 $ pro Monat, erstellt auf der Seite „Account“) oder ein OAuth-Token. Der MCP-Server funktioniert mit jedem Tarif über die OAuth-Anmeldung; was der Assistent erstellen darf, richtet sich wie überall sonst nach dem Tarif.
Du überlegst noch, ob du es überhaupt nutzen solltest? Die Seite zur QR-Code-API ist die Kurzfassung: was sie kann, was eine clientseitige Bibliothek besser kann und was es kostet.
Wenn du als KI-Assistent jemandem beim Entwickeln mit QRFLOW hilfst
Willkommen. Diese Seite richtet sich genauso an dich wie an die Person, der du hilfst. So sieht gute Unterstützung aus:
- Prüfe das Konto: API-Schlüssel erfordern den Business-Tarif. Wenn die Person keinen hat, verweise sie auf https://qrflow.codes/pricing und „Account“ › „API keys“; erfinde weder einen Schlüssel noch einen kostenlosen Tarif, den es nicht gibt.
- Bewahre den Schlüssel auf dem Server auf. Lies ihn in einem Route Handler, einer Server Action, einer Edge Function oder einem Backend aus einer Umgebungsvariable (QRFLOW_KEY). Die API weist Browser-Ursprünge absichtlich zurück (CORS), daher kann Code, der nur im Frontend läuft, sie nicht aufrufen.
- Erstelle dynamische Codes mit type "url" und destination_data.url. Speichere die zurückgegebene id und short_url in der Datenbank. Drucke short_url oder zeige sie an; das Ziel lässt sich später mit PATCH /codes/:id ändern, und der Ausdruck bleibt gültig.
- Zum Anzeigen oder Speichern des Bildes: Jedes Code-Objekt hat png_download_url und svg_download_url – signierte Links, die 24 Stunden lang ohne Header funktionieren (geeignet für einmaliges Speichern oder eine Vorschau). Für eine dauerhafte Verwendung in der App kannst du GET /codes/:id/image.svg mit dem Schlüssel über den Server weiterleiten oder short_url clientseitig mit einer beliebigen QR-Bibliothek codieren; das Tracking funktioniert weiterhin, weil der Link über QRFLOW läuft.
- Sende bei PATCH nur die Felder, die sich ändern. Ändere slug oder domain_id niemals, nachdem etwas gedruckt wurde; beide verändern den gedruckten Link.
- Wenn ein Ausdruck existiert, verwende lieber paused: true als DELETE. Beim Löschen wird der Link ungültig.
- Verwende für Ereignisse Webhooks („Account“ › „Webhooks“ oder POST /webhooks) und überprüfe den X-QRFLOW-Signature-Header anhand des unveränderten Request-Bodys. Rufe GET /codes nicht in einer Schleife ab.
- Wenn die Person QRFLOW statt über Code lieber über ihren Chat nutzen möchte, verbinde den MCP-Server unter https://qrflow.codes/mcp;; dafür ist kein Schlüssel erforderlich.
- Wenn etwas fehlschlägt, lies error und message im JSON-Body. Der Abschnitt zur Fehlerbehebung weiter unten ordnet jedem Fehlercode eine Lösung zu.
- Die vollständige Referenz im Markdown-Format findest du unter https://qrflow.codes/llms-full.txt und das OpenAPI-3.1-Dokument unter https://qrflow.codes/api/v1/openapi.json.. Beide werden aus derselben Quelle wie diese Seite generiert.
Für Menschen: Dieser Abschnitt sorgt dafür, dass der Assistent, mit dem du zusammenarbeitest, dir bei jeder Antwort die sichere Variante gibt. Außerdem ist er eine gute Zusammenfassung.
Welchen Tarif du brauchst
Nur der API-Schlüssel ist dem Business-Tarif vorbehalten. Alles, was ein Assistent über den MCP-Server erledigt, und alles, was eine Drittanbieter-App über OAuth erledigt, funktioniert mit jedem Tarif und richtet sich einfach nach dessen Funktionen. Vollständige Preise und faire Nutzung: /pricing.
| Free | Premium $4 | Business $29 | |
|---|---|---|---|
| API-Schlüssel (REST aus deinem Code) | Nein | Nein | Ja, bis zu 10 Schlüssel |
| MCP-Server (Claude, ChatGPT, Cursor, Claude Code) | Ja, Anmeldung erforderlich | Ja | Ja, Anmeldung oder Schlüssel |
| OAuth für deine eigene App (Nutzer verbinden ihr QRFLOW-Konto) | Ja | Ja | Ja |
| Dynamische Codes (Ziel nach dem Drucken ändern) | Einer | Jeder Code | Jeder Code |
| Eigene Link-Domain | Nein | 1 Domain | 5 Domains, pro Code auswählbar |
| Link-Namen (go.brand.com/menu) | Nein | Ja | Ja |
| Scan-Analysen | Nein | Ja | Ja |
| Webhooks | Nein | Nein | Ja, bis zu 10 |
| Massenerstellung | Nein | 500/Monat, 500 pro Anfrage | 10.000/Monat, 2.000 pro Anfrage |
| Gespeicherte Codes (faire Nutzung) | Einige | 1.000 | 25.000 |
| Teammitglieder | 1 | 1 | 5 |
| Preis | $0 | $4/Monat | $29/Monat |
Zwölf Wörter, die alles erledigen
Konzepte
Lies diese einmal durch, dann sind alle folgenden Endpunkte verständlich.
Static code
Der Inhalt steckt im Bild. WLAN-, Kontaktkarten- (vCard) und Klartext-Codes sind immer statisch, und im Free-Tarif ist jeder Code statisch. Ein statischer Code braucht keinen Server, läuft nie ab und kann weder geändert noch gezählt werden.
Dynamic code
Das Bild enthält einen Kurzlink, über den QRFLOW weiterleitet. url-, phone-, email-, sms- und location-Codes sind in den Tarifen Premium und Business dynamisch. Du kannst sie neu ausrichten, pausieren, ablaufen lassen, umbenennen und zählen, ohne den Ausdruck anzufassen.
short_url
Die genaue Zeichenfolge, die in einem dynamischen Code codiert ist und gedruckt werden soll. Sie lautet https://qrflow.codes/q/<short_code>, bis du eine Domain verbindest; danach lautet sie https://<your domain>/<slug or short_code>.. Jedes Code-Objekt enthält sie.
short_code
Sieben zufällige Zeichen, pro Code eindeutig, bei der Erstellung zugewiesen und danach unveränderlich. Der Fallback-Pfad, wenn ein Code keinen Link-Namen hat.
slug (link name)
Ein lesbarer Pfad auf deiner eigenen Domain: go.example.com/menu. 3 bis 40 Kleinbuchstaben, Ziffern und Bindestriche, innerhalb deines Kontos eindeutig und nur mit einer verbundenen Domain verfügbar. Lege ihn vor dem Drucken fest: Eine Änderung verändert den gedruckten Link.
Link domain
Ein Hostname, der dir gehört (go.example.com), per CNAME auf QRFLOW verweist und auf der Account-Seite verifiziert wurde. Premium erhält eine Domain; Business erhält fünf und kann mit domain_id pro Code eine auswählen. Die älteste aktive Domain ist die Standarddomain.
Kind, type and subtype
type bezeichnet die Codierung: url, text, wifi, vcard, email, phone, sms, location. Ein kind ist eine verständlichere Bezeichnung für das, was Nutzer möchten (instagram, googlereview, whatsapp, pdf, menu, appstore,...). Die meisten kinds sind url-Codes mit gesetztem destination_data.subtype. GET /catalog listet alle kinds mit ihren Feldern auf; kind in einem Code gibt an, um welchen es sich handelt.
destination_data
Die Felder für den Typ als Zeichenfolgen: { url } für eine Website, { ssid, password, encryption } für WLAN, { placeId } für eine Google-Rezension, { handle } für Instagram. Bei einem dynamischen Code kannst du sie jederzeit ersetzen.
Scans
Jede Weiterleitung erfasst Gerätetyp, Land, Stadt, Referrer, Browser, Betriebssystem und Sprache direkt aus der Anfrage sowie einen täglich wechselnden Einweg-Hash, um eindeutige Besucher zu zählen. Es werden keine Cookies gesetzt und die IP-Adresse wird nicht gespeichert. scans in einem Code ist die Gesamtzahl aller Scans; GET /codes/:id/scans schlüsselt sie auf.
Source
Jeder Code speichert, wodurch er erstellt wurde: dashboard, api:<key name>, mcp, canva, app:<connected app> (zum Beispiel app:Google Sheets) oder bulk, mit dem Präfix bulk:, wenn er über eine Massenanfrage erstellt wurde. Das wird im Dashboard und in Webhook-Payloads angezeigt, sodass du die Codes deiner Integration von manuell erstellten unterscheiden kannst.
Workspace
Ein Business-Kontoinhaber kann bis zu vier Teammitglieder einladen. Schlüssel und Webhooks gehören zum Konto des Inhabers; Codes, die von jemandem im Arbeitsbereich erstellt wurden, sind für das gesamte Team sichtbar.
Fünf Minuten
Schnellstart
Schlüssel abrufen
- Öffne im Business-Tarif Account › API keys.
- Benenne den Schlüssel nach seinem Zweck („Shop backend“, „Reporting“) und wähle seine Berechtigungsbereiche aus. Diese lassen sich später nicht ändern; erstelle bei Bedarf einen neuen Schlüssel.
- Kopiere ihn einmalig. Er sieht so aus:
qrf_live_…. Lege ihn in einer Umgebungsvariable namensQRFLOW_KEYab. - Sende ihn bei jeder Anfrage als
Authorization: Bearer $QRFLOW_KEY. Das ist schon die ganze Authentifizierung.
Schlüssel sind für Server gedacht. Füge sie niemals in eine Webseite, eine mobile App oder eine gemeinsam genutzte Tabelle ein; widerrufe und erneuere den Schlüssel, falls er offengelegt wird.
Dieselben fünf Schritte in curl, TypeScript und Python. Jedes Beispiel erstellt einen dynamischen Code, lädt dessen Bild herunter, ändert sein Ziel und ruft die Scans ab.
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
Authentifizierung
API-Schlüssel (Business)
Bis zu 10 pro Konto, jeweils 600 Anfragen pro Minute, gehasht gespeichert und nur einmal angezeigt. Ein Schlüssel enthält die Berechtigungsbereiche, mit denen er erstellt wurde:
| Berechtigungsbereich | Erlaubt |
|---|---|
| profile | GET /me: Tarif, Funktionen, Limits. Jeder Schlüssel hat diesen Bereich. |
| codes:read | Codes auflisten und lesen, Bilder herunterladen. |
| codes:write | Codes erstellen, ändern, dynamisch machen, löschen und in großen Mengen erstellen. |
| analytics:read | GET /codes/:id/scans. |
| domains:read | GET /domains (erforderlich, um domain_id sinnvoll zu verwenden). |
| codes:read / codes:write | Auch für GS1-Produkte: Die /products-Endpunkte verwenden dieselben Code-Berechtigungsbereiche. Ein Schlüssel, der Codes verwaltet, verwaltet also auch Verpackungscodes. |
| webhooks:manage | Webhooks auflisten, erstellen, testen und löschen. |
OAuth 2.0 (jeder Tarif, für Apps und Assistenten)
Wenn die Codes zu den Konten deiner Nutzer statt zu deinem eigenen gehören sollen oder ein Chat-Assistent der Client ist, verwende OAuth. Clients registrieren sich selbst; für öffentliche Clients ist PKCE S256 erforderlich; Tokens können mit resource= an den MCP-Server gebunden werden. Das OAuth-Rezept führt dich durch den Ablauf.
| Endpunkt | URL | Hinweise |
|---|---|---|
| Autorisierung | https://qrflow.codes/oauth/authorize | Sende den Nutzer hierher; er meldet sich an und klickt auf „Allow“. |
| Token | https://qrflow.codes/api/oauth/token | authorization_code- und refresh_token-Grants. Access-Tokens sind 1 Stunde, Refresh-Tokens 90 Tage gültig. |
| Widerruf | https://qrflow.codes/api/oauth/revoke | RFC 7009. Nutzer können die Verbindung auch unter „Account“ › „Connected apps“ trennen. |
| Client registrieren | https://qrflow.codes/api/oauth/register | Dynamische Registrierung nach RFC 7591, ohne Konto erforderlich. Öffentliche Clients erhalten eine dyn_-client_id und müssen PKCE S256 verwenden. |
| Discovery | https://qrflow.codes/.well-known/oauth-authorization-server | RFC 8414. Das MCP-Ressourcendokument befindet sich unter /.well-known/oauth-protected-resource. |
Access-Tokens sind 1 Stunde, Refresh-Tokens 90 Tage gültig. Nutzer sehen verbundene Apps unter „Account“ › „Connected apps“ und können die Verbindung jederzeit trennen. Ein für https://qrflow.codes/mcp ausgestelltes Token wird unter /api/v1 abgelehnt – und umgekehrt.
Das, wonach Nutzer tatsächlich fragen
Anleitungen
Jede Anleitung ist vollständig und direkt aus funktionierendem Code übernommen. Wähle die passende für deinen Stack; der Ablauf ist immer gleich: ein serverseitiger Aufruf mit dem Schlüssel, id und short_url speichern, das Bild anzeigen.
- Next.js
- QR-Code ohne Proxy anzeigen
- Express oder ein beliebiger Node-Server
- Cloudflare Workers, Vercel Edge, Deno Deploy, Supabase Edge Functions
- Python
- Ein QR-Code pro Bestellung, Tisch, Produkt, Ticket oder Veranstaltung
- Das Ziel eines gedruckten Codes ändern
- Codes auf deiner eigenen Domain drucken
- Ein Scan-Diagramm in deinem eigenen Adminbereich
- Webhooks in Next.js empfangen und überprüfen
- Webhooks in Python empfangen
- Tausende Codes aus einer CSV-Datei
- Nutzern ermöglichen, ihr eigenes QRFLOW-Konto zu verbinden (OAuth)
- Zapier, Make, n8n
Next.js: eine Route zum Erstellen eines Codes und eine Route zum Anzeigen
Wann: Du hast eine Next.js-App (App Router) und möchtest eine Schaltfläche, die einen QR-Code erstellt, sowie eine Seite, die ihn anzeigt.
- Lege deinen Schlüssel in .env.local als QRFLOW_KEY ab. Stelle ihm niemals NEXT_PUBLIC_ voran.
- Füge einen POST-Route-Handler hinzu, der den Code erstellt und id sowie short_url zurückgibt.
- Füge eine GET-Route hinzu, die das Bild als Proxy weiterleitet, damit der Browser den Schlüssel nie zu sehen bekommt.
- Speichere id und short_url in deinem eigenen Datensatz (Bestellung, Tisch, Produkt, Veranstaltung).
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>
- Server Actions funktionieren genauso: Rufe
fetchmit dem Schlüssel innerhalb der Action auf. - Beim Pages Router gehört derselbe Code in
pages/api/qr.tsmitreq/res.
QR-Code ohne Proxy anzeigen: short_url selbst rendern
Wann: Du möchtest das Bild sofort im Browser anzeigen und brauchst weder die Frames noch das Logo von QRFLOW.
Jede QR-Bibliothek funktioniert, denn der Code IST der Kurzlink
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.
- Das ist der schnellste Weg für eine Vorschau. Für den Druck lade
/codes/:id/image.svgherunter: Die Datei enthält die gespeicherten Farben, den Frame, die Beschriftungen und das Logo und ist eine Vektorgrafik. - Wenn du später den Slug oder
domain_idänderst, ändert sichshort_url; rendere den Code erneut.
Express oder ein beliebiger Node-Server
Wann: Ein einfaches Node-Backend.
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
Wann: Eine reine fetch-Laufzeitumgebung ohne integrierte Node-Module.
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_...
- Das npm-Paket
qrflow\verwendet nurfetchund WebCrypto und läuft daher unverändert in all diesen Umgebungen.
Python: FastAPI, Flask, Django, ein Skript
Wann: Dein Backend ist in Python geschrieben.
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")
Ein QR-Code pro Bestellung, Tisch, Produkt, Ticket oder Veranstaltung
Wann: Jede Zeile in einer deiner Tabellen benötigt automatisch einen eigenen Code.
- Füge deiner Tabelle zwei Spalten hinzu:
qrflow_code_id(uuid) undqr_short_url(text). - Wenn eine Zeile erstellt wird, sende
POST /codesmit der öffentlichen URL der Zeile und einer Bezeichnung, die sie benennt („Bestellung 10432“, „Tisch 7“). Speichereidundshort_url. - Wenn sich die Seite der Zeile ändert (neue Domain, neuer Pfad), führe
PATCH destination_dataaus. Die gedruckten Codes funktionieren weiterhin. - Wenn die Zeile nicht mehr verwendet wird, führe
PATCH { paused: true }aus, falls etwas gedruckt wurde; andernfallsDELETE. - Brauchst du Tausende auf einmal (ein Menü pro Tisch für 300 Restaurants)? Verwende
POST /codes/bulkin Abschnitten und ordne die zurückgegebenen Codes anhand der Bezeichnung oder der Reihenfolge wieder deinen Zeilen zu.
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 });
- Die faire Nutzung umfasst 25.000 gespeicherte Codes bei Business; die API begrenzt die Anzahl auf das Doppelte. Wenn du dauerhaft einen Code pro Beleg brauchst, sprich zuerst mit uns: hello@qrflow.codes.
Ändern, wohin ein gedruckter Code führt
Wann: Eine Kampagne ist beendet, eine Seite wurde verschoben, ein PDF ersetzt oder eine Saison ist vorbei.
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" } }'
Pausiere den Code oder lege ein Enddatum fest
# 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" }'
- Nur dynamische Codes lassen sich neu zuweisen; bei statischen Codes lautet die Antwort
400 not_dynamic. WLAN-, vCard- und Klartext-Codes enthalten ihren Inhalt im Muster und können nie dynamisch sein. Daher lehntPOST /codes/:id/dynamicsie mit400 not_dynamic_capableab. Bei URL-, Telefon-, E-Mail-, SMS- und Standort-Codes macht Free den ersten Code dynamisch und die übrigen statisch; bei einem kostenpflichtigen Tarif sind alle dynamisch.POST /codes/:id/dynamicwandelt einen statischen Code um, solange das Konto noch über Kontingent verfügt. Rendere und drucke den Code anschließend erneut, da sich das Bild ändert. - Beim nächsten Scan wird das neue Ziel angezeigt. Es gibt keinen Cache, dessen Ablauf du abwarten musst.
Codes auf deiner eigenen Domain drucken
Wann: Du möchtest go.example.com/menu im Code statt qrflow.codes/q/x7k2p9a verwenden.
- Füge auf der Seite „Account“ unter „Your own link domain“
go.example.comhinzu und erstelle bei deinem DNS-Anbieter den dort angezeigten CNAME-Eintrag. Die Verifizierung ist normalerweise innerhalb weniger Minuten abgeschlossen. - Ab dann verwendet
short_urlbei jedem neuen dynamischen Code diese Domain. Auch bestehende Codes werden umgestellt: Ihr Bild enthältqrflow.codes/q/..., das weiterhin weiterleitet, sodass bereits gedruckte Codes funktionieren. - Gib Codes mit
sluglesbare Namen: MitPATCH { "slug": "menu" }wird darausgo.example.com/menu. Erledige das vor dem Drucken. - Bei Business mit mehreren Domains listet
GET /domainsdiese mit ihren IDs auf. Übergibdomain_idbeiPOSToderPATCH, um die Domain für einen Code auszuwählen.
Einen Link benennen und eine Domain auswählen
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
Scan-Diagramm in deinem eigenen Adminbereich
Wann: Du möchtest Scans pro Tag, Land oder Gerät neben deinen eigenen Zahlen sehen.
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
- Eine Anfrage deckt bis zu 92 Tage ab; für längere Zeiträume wiederhole die Anfrage. Datumsangaben sind in UTC.
- Für Live-Zahlen ohne regelmäßige Abfragen kannst du einen Webhook für das Scan-Ereignis abonnieren: Du erhältst alle paar Minuten jeden Scan mit seinen Details in Stapeln.
Webhooks in Next.js empfangen und verifizieren
Wann: Du möchtest in nahezu Echtzeit in deiner eigenen Datenbank erfahren, wenn ein Code gescannt oder geändert wird.
- Erstelle den Webhook unter Account › Webhooks oder mit
POST /webhooks. Kopiere das Secret (whsec_...) einmalig inQRFLOW_WEBHOOK_SECRET. - Lies den unveränderten Request-Body als Text ein, bevor du ihn analysierst; die Signatur umfasst exakt diese Bytes.
- Verifiziere die Signatur und verzweige dann anhand des Ereignisses. Antworte schnell mit 2xx; erledige langsame Aufgaben nach der Antwort oder in einer Warteschlange.
- Klicke beim Webhook auf „Test“, um einen signierten Ping zu erhalten und die Verbindung zu überprüfen.
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 });
}
- Mache deinen Entwicklungsserver lokal über einen Tunnel erreichbar (
cloudflared tunnel --url http://localhost:3000,oder ngrok) und verwende beim Entwickeln dessen HTTPS-URL für den Webhook. - Das npm-Paket übernimmt das für dich:
import { parseWebhook } from "qrflow"\verifiziert und analysiert den Inhalt mit einem einzigen Aufruf (WebCrypto, läuft also auch in Workers und Deno). Der Python-Client enthältverify_webhook.
Webhooks in Python empfangen
Wann: Flask, FastAPI oder Django empfängt dieselben Ereignisse.
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
Tausende Codes aus einer CSV-Datei
Wann: Ein Code pro SKU, Sitzplatz, Asset-Tag oder Mailer.
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");
}
- Bulk erstellt nur dynamische URL-Codes, alle mit denselben Farben. Die Codes werden in der Reihenfolge zurückgegeben, in der du sie gesendet hast, abzüglich abgelehnter Zeilen. Im Zweifelsfall ordnest du sie anhand der Bezeichnung zu.
- Webhooks senden pro Bulk-Anfrage ein
code.created-Ereignis mitcodes[]statt eines Ereignisses pro Code.
Deinen Nutzern ermöglichen, ihr eigenes QRFLOW-Konto zu verbinden (OAuth)
Wann: Du entwickelst ein Produkt für andere und möchtest, dass die Codes in deren QRFLOW-Konten statt in deinem landen.
- Registriere einmalig einen Client:
POST https://qrflow.codes/api/oauth/registermitclient_nameundredirect_uris. Du erhältst eineclient_id(und bei vertraulichen Clients einclient_secret). - Leite den Nutzer zu
/oauth/authorizemitresponse_type=code,client_id,redirect_uri,scope,stateund PKCE (code_challenge,code_challenge_method=S256) weiter. - Tausche den Code unter
/api/oauth/tokenein. Speichere das Refresh-Token; Access-Tokens sind eine Stunde gültig. - Rufe
/api/v1mitAuthorization: Bearer <access\_token\>auf. Alles funktioniert genau wie mit einem Schlüssel, aber im Rahmen des Tarifs des Nutzers.
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
- Die Scopes sind dieselben sechs wie bei API-Schlüsseln. Fordere nur die benötigten an; der Zustimmungsbildschirm listet sie auf.
- Wenn deine App ein Chat-Assistent oder Agent ist, füge der Autorisierungsanfrage
resource=https://qrflow.codes/mcphinzu und verwende stattdessen den MCP-Server; das Token wird an ihn gebunden.
Zapier, Make, n8n: ganz ohne Code
Wann: Du möchtest, dass Scans oder neue Codes in einem Tabellenblatt, einem Slack-Kanal oder einem CRM landen.
- Erstelle einen Catch-Hook-Trigger (Zapier: Webhooks by Zapier › Catch Hook; Make: Custom webhook; n8n: Webhook node) und kopiere dessen HTTPS-URL.
- Füge diese URL unter Account › Webhooks hinzu und wähle die Ereignisse aus. Klicke auf „Test“; der Ping erscheint im Tool und zeigt die Struktur der Nutzdaten.
- Ordne
data.scans[](für Scans) oderdata.code(fürcode.*) deinem Tabellenblatt, deiner Nachricht oder deinem Datensatz zu. - Um über diese Tools Codes zu erstellen, verwende deren HTTP-Modul für
POST /codesmit demAuthorization-Header. Bewahre den Schlüssel im Anmeldedatenspeicher des Tools auf.
- In Zapier gibt es jetzt eine QRFLOW.codes-App: Für die Schritte „Create QR Code“, „Update QR Code“ und „Find“ sowie den sofortigen Trigger „New Scan“ sind weder Webhook-Einrichtung noch API-Schlüssel erforderlich. Siehe QRFLOW mit Zapier. Die folgenden Schritte gelten für Make, n8n und alle anderen Tools.
- Diese Tools können die Signatur nicht verifizieren. Die von ihnen bereitgestellte URL lässt sich nicht erraten und bietet den nötigen Schutz; veröffentliche sie nicht.
- Wenn die Liste bereits in Google Sheets liegt, brauchst du möglicherweise gar keinen Webhook: Das QRFLOW-Add-on für Google Sheets erstellt pro Zeile einen Code und schreibt den Kurzlink sowie die Scan-Anzahl ohne API-Schlüssel zurück in das Tabellenblatt – mit Premium. Siehe das Google-Sheets-Add-on.
Vibe-Coding
Prompts zum Einfügen
Coding-Assistenten erstellen das Richtige, wenn sie die Regeln von Anfang an kennen. Diese Prompts enthalten die Regeln. Füge einen davon ein, ergänze die Angabe in den eckigen Klammern, und der Assistent liest die Markdown-Referenz, bevor er eine Zeile schreibt.
QR-Codes zu meiner App hinzufügen
Claude, ChatGPT, Cursor, Codex, Windsurf, Copilot Chat: in den Chat einfügen
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"].
Deinem Repository QRFLOW beibringen
In CLAUDE.md, AGENTS.md, .cursorrules oder .github/copilot-instructions.md einfügen
## 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.
In Lovable, Bolt, v0, Replit und anderen App-Buildern
Front-End-orientierte Builder, die dir ein Backend bereitstellen (Supabase, serverlose Funktionen)
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
Ein benutzerdefiniertes GPT, das meine Codes verwaltet
ChatGPT › Create a 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).
Was du sagen kannst, sobald der Connector eingerichtet ist
Claude, ChatGPT, Claude Code mit verbundenem QRFLOW-MCP-Server
"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."
MCP-Server
Mit Claude, ChatGPT, Cursor und Claude Code verwenden
QRFLOW ist ein MCP-Server unter https://qrflow.codes/mcp. Verbinde ihn einmal, melde dich an und sage dann zum Beispiel „Erstelle einen QR-Code für unsere Herbstmenü-Seite, benenne ihn menu und verwende meine Domain“, „Leite den Code auf dem Poster in der Lobby auf die neue Seite um“ oder „Wie viele Scans hatte der Flyer letzte Woche, aufgeschlüsselt nach Ländern?“. Der Assistent erhält dieselben Tools wie bei dieser API und unterliegt denselben Regeln. Die Codes erscheinen in deinem Dashboard mit mcp als Quelle.
Kein Entwickler? Die verständliche Anleitung mit den genauen Klicks für jeden Assistenten findest du unter QR-Codes mit deinem KI-Assistenten erstellen.
Wird stündlich unabhängig von Glama bewertet und auf seinen Zustand geprüft. Außerdem ist der Server im Verzeichnis awesome-remote-mcp-servers und in der offiziellen MCP Registry als codes.qrflow/qrflow aufgeführt.
Verbinden
Customize › Connectors › Add custom connector › Adresse einfügen oder bei QRFLOWs Verzeichniseintrag auf „Connect“ klicken. Claude öffnet eine QRFLOW-Anmeldeseite; klicke auf „Allow“. Funktioniert mit jedem Tarif.
https://qrflow.codes/mcp
Settings › Security and login › Developer mode aktivieren, dann Settings › Plugins › + › Adresse einfügen; bei Aufforderung anmelden. Für Plus, Pro, Team, Enterprise und Edu.
https://qrflow.codes/mcp
Ein Befehl, dann /mcp zur Anmeldung. Füge einen Business-Schlüssel als Header hinzu, um die Anmeldung zu überspringen.
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, jeder MCP-Client
Füge einen HTTP-Server unter der URL hinzu. Die OAuth-Anmeldung erfolgt im Browser; alternativ kannst du einen Authorization-Header mit einem Schlüssel übergeben.
{
"mcpServers": {
"qrflow": { "type": "http", "url": "https://qrflow.codes/mcp" }
}
}
Dein eigener Agent (Anthropic- oder OpenAI-SDK)
Richte den MCP-Connector oder das Tool mit einem Business-Schlüssel als Bearer-Token auf die URL aus; ein Browser-Ablauf ist nicht erforderlich.
// Anthropic Messages API, MCP connector
mcp_servers: [{ type: "url", url: "https://qrflow.codes/mcp", name: "qrflow", authorization_token: process.env.QRFLOW_KEY }]
Was der Assistent tun kann
| Tool | Funktion | Scope |
|---|---|---|
| list_code_kinds | Alle Code-Arten mit ihren Feldern und dem erforderlichen Tarif. Der Assistent ruft diese Funktion auf, bevor er etwas Ungewöhnliches erstellt. | profile |
| list_domains | Deine Link-Domains, die Standarddomain und ihre IDs. | domains:read |
| get_qr_image | Ein PNG, das der Assistent anzeigen oder speichern kann, sowie die SVG-URL für den Druck. | codes:read |
| get_account | Tarif, Funktionen und Limits des Kontos. | profile |
So bleibt es sicher
- Der Assistent erhält ausschließlich ein Token für dein Konto, das ausgestellt wird, nachdem du auf einer QRFLOW-Seite auf „Allow“ geklickt hast. Du kannst die Verbindung jederzeit unter Account › Connected apps trennen.
- Tokens sind an den MCP-Server gebunden und können nicht für REST-API-Anfragen wiederverwendet werden.
- Jeder Schreibvorgang durchläuft dieselbe Validierung wie im Dashboard: zulässige Ziele, Tarifprüfungen und Fair-Use-Grenzen.
- Destruktive Tools beschreiben ihr Verhalten sorgfältig:
delete_qr_codeweist das Modell an, bei bereits gedruckten Codes das Pausieren zu bevorzugen. - Die Discovery-Dokumente befinden sich unter
/.well-known/oauth-authorization-serverund/.well-known/oauth-protected-resource; die Registrierung folgt RFC 7591; nur PKCE S256 ist zulässig.
SDKs und die OpenAPI-Spezifikation
- TypeScript / JavaScript:
npm install qrflow(npm). Keine Abhängigkeiten, ESM und CommonJS, vollständige Typen; läuft mit Node 18+, Bun, Deno und Workers. Wiederholt 429-Anfragen automatisch und enthältverifyWebhook/parseWebhook. - Python 3.9+, nur Standardbibliothek: qrflow.py.
- OpenAPI 3.1: /api/v1/openapi.json. In Postman oder Insomnia importieren, einen Client in einer beliebigen Sprache generieren oder als ChatGPT Action einbinden.
- Beide Clients werfen einen typisierten Fehler (
QRFlowErrormitstatus,code,message,retryAfter) und enthalten einen Webhook-Verifizierer. Der TypeScript-Quellcode in einer einzelnen Datei ist weiterhin unter /sdk/qrflow.ts verfügbar, falls Sie ihn lieber direkt in Ihr Projekt übernehmen möchten.
| TypeScript | Python | Aufrufe |
|---|---|---|
| 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) | Die Bildadresse (mit dem Schlüssel abrufen) |
| verifyWebhook(raw, header, secret) | verify_webhook(raw, header, secret) | Signaturprüfung für Zustellungen |
Endpunktreferenz
Basis-URL https://qrflow.codes/api/v1. Anfragen und Antworten sind JSON. Datumsangaben sind ISO 8601 in UTC. Senden Sie bei PATCH nur die Felder, die geändert werden.
GETprofile
Plan, Funktionsmerkmale und die für dieses Konto geltenden Limits sowie die Berechtigungsbereiche des Schlüssels.
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
Native Typen (url, wifi, vcard, email, phone, sms, text, location) und die rund 50 Untertypen (Instagram, Google-Bewertung, WLAN, App Store …), jeweils mit den benötigten Feldern und dem erforderlichen Plan. Kein Schlüssel erforderlich.
curl https://qrflow.codes/api/v1/catalog
GETcodes:read
Neueste zuerst.?limit= bis zu 100,?q= durchsucht Bezeichnungen.
curl "https://qrflow.codes/api/v1/codes?limit=20&q=menu" \
-H "Authorization: Bearer $QRFLOW_KEY"
POSTcodes:write
Es gelten dieselben Regeln wie beim Speichern auf der Website: Codes für url, phone, email, sms und location sind in kostenpflichtigen Plänen dynamisch; Wi-Fi-, vCard- und Text-Codes enthalten ihren Inhalt im Muster. Geben Sie eine Untertyp-ID in destination_data.subtype an, um beispielsweise einen Google-Bewertungscode zu erstellen. Mit domain_id können Sie festlegen, welche Ihrer Link-Domains auf dem Code erscheint (GET /domains listet sie auf).
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
Der Code mit seiner Scan-Anzahl, dem Kurzlink und der Bildadresse.
curl https://qrflow.codes/api/v1/codes/$ID \
-H "Authorization: Bearer $QRFLOW_KEY"
PATCHcodes:write
Mögliche Felder: destination_data (nur dynamische Codes; der Aufdruck bleibt gültig), label, paused, expires_at (ISO oder null), slug (ein Linkname auf Ihrer Domain), domain_id (welche Ihrer Link-Domains für diesen Code verwendet wird; null = Standard des Kontos), fg_color, bg_color, frame_style, frame_caption, frame_caption2. Senden Sie nur die Felder, die Sie ändern.
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
Wird endgültig gelöscht, einschließlich des Scan-Verlaufs. Der aufgedruckte Link eines dynamischen Codes funktioniert dann nicht mehr. Verwenden Sie lieber paused: true, wenn der Code noch im Umlauf ist.
curl -X DELETE https://qrflow.codes/api/v1/codes/$ID \
-H "Authorization: Bearer $QRFLOW_KEY"
204 No Content
POSTcodes:write
Das gedruckte Muster ändert sich (es codiert nun den Kurzlink), daher muss das Bild anschließend neu gerendert werden.
curl -X POST https://qrflow.codes/api/v1/codes/$ID/dynamic \
-H "Authorization: Bearer $QRFLOW_KEY"
GETcodes:read
Druckfertiges SVG mit Rahmen und Farben.?size= legt die Breite des Modulrasters in px fest; die Datei lässt sich ohnehin verlustfrei skalieren.
curl https://qrflow.codes/api/v1/codes/$ID/image.svg \
-H "Authorization: Bearer $QRFLOW_KEY" -o code.svg
GETanalytics:read
?from= und?to= (ISO-Daten, bis zu 92 Tage, standardmäßig die letzten 30) und?group= day, device, country, city, browser, os oder referrer. Dieselben Zahlen wie auf der Analyseseite.
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
Bis zu 2.000 URL-Codes pro Aufruf, alle dynamisch. Wird auf dasselbe monatliche Bulk-Kontingent wie auf der Bulk-Seite angerechnet (10.000 bei Business). Zeilen, die keine Webadressen sind, werden unter rejected zurückgegeben; die übrigen werden erstellt.
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
Die Codes für Einzelhandelsverpackungen. Jedes Produkt besteht aus einer GTIN, der auf der Verpackung aufgedruckten Adresse und den dahinterliegenden Links. Namen und GTINs mit?q= durchsuchen. Business-Plan.
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 und name sind erforderlich; brand und url sind optional. Die Prüfziffer wird vor dem Speichern überprüft, und Formate mit 8, 12, 13 und 14 Ziffern werden alle auf 14 normalisiert. Eine GTIN, die Sie bereits besitzen, führt zu einem 409 statt zu einem zweiten Produkt.
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
Eine GTIN kann gleichzeitig zu mehreren Zielen führen, die jeweils mit ihrem Zweck gekennzeichnet sind. Für ein Telefon wird das Standardziel verwendet; eine App, die einen Typ anfordert, erhält das entsprechende Ziel. Idempotent: Derselbe link_type und batch ersetzt den betreffenden Link, statt einen zweiten hinzuzufügen. So kann ein nächtliches Skript zweimal ausgeführt werden. Übergeben Sie batch, um den Link auf eine Charge zu beschränken. So lässt sich ein Rückruf veröffentlichen, ohne den Rest der Produktion zu ändern.
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
Zählung pro GTIN für die letzten?days= (1 bis 365, standardmäßig 30), aufgeschlüsselt nach Land, Gerät, Linktyp und Charge. went_nowhere zählt Scans ohne gefundenes Ziel und sollte null sein.
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
Ihre verbundenen Domains, ihr Status und die Domain, die dynamische Codes standardmäßig verwenden (default_base). Übergeben Sie die ID einer Domain als domain_id für einen Code, damit dieser eine andere Domain verwendet.
curl https://qrflow.codes/api/v1/domains \
-H "Authorization: Bearer $QRFLOW_KEY"
GETwebhooks:manage
Ihre Webhooks mit ihren Ereignissen, dem letzten Status und der Anzahl der Fehler.
curl https://qrflow.codes/api/v1/webhooks \
-H "Authorization: Bearer $QRFLOW_KEY"
POSTwebhooks:manage
url muss https auf einem öffentlich erreichbaren Host sein; events kann scan, code.created, code.updated oder code.deleted enthalten. Das Signaturgeheimnis wird nur einmal zurückgegeben.
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
Sendet jetzt einen signierten Ping und meldet die Antwort.
curl -X POST https://qrflow.codes/api/v1/webhooks/$WEBHOOK_ID \
-H "Authorization: Bearer $QRFLOW_KEY"
DELETEwebhooks:manage
Beendet alle Zustellungen, einschließlich geplanter Wiederholungsversuche.
curl -X DELETE https://qrflow.codes/api/v1/webhooks/$WEBHOOK_ID \
-H "Authorization: Bearer $QRFLOW_KEY"
204 No Content
GETpublic
Frame-IDs und die jeweiligen Anforderungen (Beschriftung, zweite Zeile), nach Kategorien wie im Customizer gruppiert. Kein Schlüssel erforderlich.
curl https://qrflow.codes/api/v1/frames
Das Code-Objekt
Jeder Endpunkt, der einen Code betrifft, gibt dieselbe Struktur zurück. Ignorieren Sie unbekannte Felder; im Laufe der Zeit kommen neue hinzu.
| Feld | Typ | Bedeutung |
|---|---|---|
| id | uuid | Stabile ID. Verwenden Sie sie bei allen anderen Aufrufen. |
| label | string | null | Der Name im Dashboard. Bis zu 120 Zeichen. Mit?q= durchsuchbar. |
| kind | string | Die Katalog-ID: url, wifi, instagram, googlereview,... kind_label ist der lesbare Name. |
| type | string | Die Codierung: url, text, wifi, vcard, email, phone, sms, location. |
| destination_data | object | Die von Ihnen gesendeten Felder (zuzüglich subtype für Kategorien). destination ist eine einzeilige Zusammenfassung davon. |
| dynamic | boolean | True, wenn Scans über QRFLOW laufen und sich das Ziel ändern lässt. dynamic_capable gibt an, ob dieser Typ in einem kostenpflichtigen Plan dynamisch sein kann. |
| short_code | string | Sieben Zeichen, unveränderlich. |
| short_url | string | Der Link, der für einen dynamischen Code aufgedruckt werden soll. Enthält Ihre Domain und den Slug, sofern festgelegt. |
| domain_id | uuid | null | Die Link-Domain, die für diesen Code verwendet wird; null bedeutet die Standarddomain des Kontos. |
| fg_color, bg_color | hex | Farben der Module und des Hintergrunds. |
| has_logo | boolean | Im Dashboard wurde ein Logo hinzugefügt; image.svg enthält es. |
| frame_style, frame_caption, frame_caption2 | string | null | Frame-ID und Beschriftungen wie im Customizer. |
| scans | integer | Scan-Anzahl insgesamt. |
| created_at, updated_at | ISO 8601 | UTC. |
| manage_url | url | Die Seite des Codes im Dashboard, für einen Link „In QRFLOW öffnen“. |
| image_url | url | GET /codes/:id/image.svg. Erfordert den Authorization-Header; keine öffentliche Bild-URL. |
| svg_download_url, png_download_url | url | Dasselbe SVG (Rahmen, Farben, Logo) und ein einfaches PNG über signierte Links, die 24 Stunden lang ohne Header funktionieren: für <img>-Tags, Skripte und Assistenten, die eine Datei speichern. download_expires_at gibt an, wann sie ablaufen; bei jedem Abruf des Codes werden neue Links zurückgegeben. |
Weitere Strukturen: 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 einmal), Me (id, email, plan, paid, features, limits, auth, scopes) und Error (error, message). Das OpenAPI-Dokument enthält Typdefinitionen für alle Eigenschaften.
Business
Webhooks
QRFLOW ruft Ihre https-URL auf, wenn etwas passiert. Erstellen Sie einen Webhook unter Konto › Webhooks oder mit POST /webhooks; das Signaturgeheimnis erhalten Sie nur einmal. Bis zu 10 pro Konto.
| Ereignis | Wann | data |
|---|---|---|
| scan | Gebündelt: alle paar Minuten, alle neuen Scans seit der letzten Zustellung, bis zu 500 pro Aufruf. | count, from, to, scans[] mit code_id, label, short_code, slug, scanned_at, device, country, city, referrer, browser, os, language |
| code.created | Sofort bei API-Aufrufen und durch Assistenten; innerhalb weniger Minuten bei Erstellung im Dashboard. Eine Bulk-Anfrage sendet ein Ereignis mit bulk: true und codes[]. | code, source |
| code.updated | Gleicher Zeitpunkt. Umfasst Ziel, Bezeichnung, Pause, Ablauf, Linkname, Domain, Farben, Frame und Umwandlung in einen dynamischen Code. | code, changed[] (die Namen der geänderten Felder) |
| code.deleted | Gleicher Zeitpunkt. | code: { id, label, short_code, slug } |
| ping | Wenn Sie auf Test klicken. | webhook_id, message |
Was ankommt
Jede Nutzlast ist { id, event, created_at, data }. id bleibt bei Wiederholungsversuchen derselben Zustellung unverändert, sodass Sie damit Duplikate erkennen können.
{
"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
Signatur überprüfen
X-QRFLOW-Signature: t=<unix seconds>,v1=<hex>. Berechnen Sie mit Ihrem Geheimnis HMAC-SHA256 über ${t}.${rawBody} und vergleichen Sie das Ergebnis in konstanter Zeit mit v1; lehnen Sie die Anfrage ab, wenn t älter als fünf Minuten ist. Verwenden Sie die empfangenen Rohdatenbytes, niemals ein erneut serialisiertes Objekt. Funktionierende Empfänger für Next.js und Python finden Sie in den Rezepten; beide SDKs enthalten außerdem den Hilfsmechanismus.
Zustellungsregeln
- Antworten Sie innerhalb von 8 Sekunden mit einem beliebigen 2xx-Status. Führen Sie die Arbeit erst nach der Antwort aus.
- Alle anderen Antworten werden nach 1, 5, 15, 60, 240 und 720 Minuten erneut versucht.
- Zwanzig aufeinanderfolgende Fehler deaktivieren den Webhook und senden eine E-Mail an den Kontoinhaber. Aktivieren Sie ihn wieder, sobald der Empfänger repariert ist; geplante Wiederholungsversuche werden fortgesetzt.
- URLs müssen https verwenden und auf einem öffentlich erreichbaren Host liegen. localhost, private Bereiche und qrflow.codes selbst werden abgelehnt. Verwenden Sie während der Entwicklung einen Tunnel.
- Klicken Sie auf Test, um einen signierten
pingzu erhalten und den Status zu sehen, den Ihr Server zurückgegeben hat.
Fehler
Jeder Fehler ist { "error": "<code>", "message": "<what to do>" } mit dem unten angegebenen Status. Die Meldung ist für Menschen formuliert; zeigen Sie sie an.
| Status | error | Bedeutung |
|---|
Symptom, Ursache, Lösung
Fehlerbehebung
401 invalid_token bei jedem Aufruf
WarumDer Header ist falsch oder der Schlüssel ist nicht aktiv.
LösungSenden Sie genau Authorization: Bearer qrf_live_… (mit einem Leerzeichen, nicht mit einem Doppelpunkt). Prüfen Sie unter Konto › API-Schlüssel, ob der Schlüssel widerrufen wurde. Wenn Sie ihn aus einem Chat oder Dokument kopiert haben, achten Sie auf einen abschließenden Punkt oder ein typografisches Anführungszeichen.
401 bei /api/v1 mit einem Token, das auf dem MCP-Server funktioniert
WarumFür https://qrflow.codes/mcp ausgestellte Tokens sind daran gebunden.
LösungVerwenden Sie für REST einen API-Schlüssel oder führen Sie einen zweiten OAuth-Ablauf ohne resource= aus, um ein Token für die REST-API zu erhalten.
402 upgrade_required beim Erstellen eines Schlüssels oder Webhooks
WarumBeides sind Business-Funktionen.
LösungFühren Sie unter /pricing ein Upgrade durch oder verwenden Sie den MCP-Server, der in jedem Plan über die Anmeldung funktioniert.
402 bei POST /codes aus einer OAuth-App
WarumDer Plan des Benutzers umfasst nicht die angeforderte Funktion (einen dynamischen Code oder eine Domain).
LösungLesen Sie zuerst die Funktionen mit GET /me aus und passen Sie das Verhalten an: Erstellen Sie den Code trotzdem (im Free-Plan ist er statisch) oder erklären Sie dem Benutzer, welcher Plan erforderlich ist.
403 insufficient_scope
WarumDie Berechtigungsbereiche werden beim Erstellen eines Schlüssels festgelegt. Beheben: Erstellen Sie einen neuen Schlüssel mit den benötigten Berechtigungen und widerrufen Sie den alten. Bei OAuth fordern Sie die Berechtigung im Autorisierungsrequest an.
400 not_dynamic bei PATCH destination_data
Ursache: Der Code ist statisch: ein WLAN-/vCard-/Texttyp oder ein Code, der mit dem Free-Tarif erstellt wurde, nachdem der eine kostenlose dynamische Code bereits verwendet worden war.
Beheben: Für url/phone/email/sms/location führen Sie POST /codes/:id/dynamic aus, solange das Konto noch über Kontingent verfügt, und laden Sie den Code anschließend erneut herunter und drucken Sie ihn erneut aus (das Bild ändert sich). WLAN-, vCard- und Textcodes können nie dynamisch sein; erstellen Sie stattdessen einen url-Code, der eine Seite öffnet.
400 no_domain beim Festlegen von slug
Ursache: Linknamen werden auf Ihrer Domain gespeichert.
Beheben: Verbinden und verifizieren Sie zuerst eine Domain auf der Account-Seite. Auf qrflow.codes/q ist der Pfad immer der short_code.
409 conflict bei slug
Ursache: Einer Ihrer anderen Codes hat diesen Namen.
Beheben: Verwenden Sie GET /codes?q=, um ihn zu finden, oder wählen Sie einen anderen Namen. Namen gelten pro Konto, nicht global.
CORS-Fehler in der Browserkonsole
Ursache: Die API akzeptiert nur Aufrufe von Server zu Server (und Canva). Das ist beabsichtigt: Ein Schlüssel auf einer Webseite ist ein offengelegter Schlüssel.
Beheben: Verschieben Sie den Aufruf in einen Route Handler, eine Server Action, eine Edge Function oder ein Backend und rufen Sie ihn von der Seite aus auf.
Das Bild zeigt eine QRFLOW-Markierung
Ursache: Der Code wurde von jemandem erstellt, der nicht angemeldet ist. Die Markierung wird nur bei anonymen Downloads angezeigt.
Beheben: Jedes Konto entfernt sie, auch das kostenlose. Bilder für gespeicherte Codes enthalten sie nie.
short_url zeigt nach dem Hinzufügen meiner Domain weiterhin qrflow.codes/q/…
Ursache: Die Domain wurde noch nicht verifiziert oder ihr CNAME ist falsch.
Beheben: Prüfen Sie den Status auf der Account-Seite oder mit GET /domains (der Status muss verified sein). Bestehende Codes wechseln automatisch, sobald die Domain verifiziert ist.
image_url liefert in einem <img>-Tag 401
Ursache: Dafür ist der Authorization-Header erforderlich, den ein <img> nicht senden kann.
Beheben: Verwenden Sie svg_download_url oder png_download_url aus demselben Code-Objekt: signierte Links, die 24 Stunden lang ohne Header funktionieren. Für eine dauerhafte Lösung leiten Sie image_url über Ihren Server weiter (siehe das Next.js-Rezept) oder codieren Sie short_url selbst.
Ich brauche ein PNG, kein SVG
Ursache: Das SVG enthält Rahmen und Logo; das PNG ist der einfache Code.
Beheben: GET /codes/:id/image.png (Bearer oder die signierte png_download_url) liefert ein PNG mit 256 bis 2048 px. Für ein PNG mit Rahmen konvertieren Sie das SVG mit sharp oder resvg (sharp(svgBuffer).png().toBuffer()).
Mein Assistent meldete, dass der Bildendpunkt die Anfrage abgelehnt hat, und zeichnete den Code selbst
Ursache: Er hat image_url abgerufen, wofür ein Bearer erforderlich ist.
Beheben: Jeder Code enthält jetzt png_download_url und svg_download_url, und get_qr_image gibt sie zurück; der Assistent kann sie ohne Anmeldung mit curl abrufen. Ein lokal gezeichneter Code, der dieselbe short_url codiert, funktioniert weiterhin und zählt weiterhin Scans, enthält aber weder Rahmen noch Logo.
Webhook kommt nie an
Ursache: URL-Regeln oder der Empfänger.
Beheben: Die URL muss https auf einem öffentlich erreichbaren Host verwenden (kein localhost, keine private IP-Adresse, nicht qrflow.codes). Klicken Sie beim Webhook auf Test: Das Ergebnis zeigt den Status, den Ihr Server zurückgegeben hat. Scan-Ereignisse werden gebündelt und können bis zu etwa fünf Minuten dauern; code.*-Ereignisse aus dem Dashboard werden ebenfalls einige Minuten lang in die Warteschlange gestellt, während API- und MCP-Schreibvorgänge sofort zugestellt werden.
Signatur lässt sich nie verifizieren
Ursache: Sie haben einen neu serialisierten Body signiert.
Beheben: Verifizieren Sie die exakt empfangenen Rohbytes, bevor Sie JSON parsen. Verwenden Sie in Express express.raw({ type: 'application/json' }) für diese Route; in Next.js App Router verwenden Sie await req.text(); in Flask request.get_data(). Berechnen Sie dann HMAC-SHA256 von ${t}.${raw}\.
Webhook hat sich selbst deaktiviert
Ursache: Zwanzig aufeinanderfolgende Fehler.
Beheben: Beheben Sie den Empfänger und aktivieren Sie ihn dann wieder (Account › Webhooks oder löschen Sie ihn und erstellen Sie ihn neu). Sie wurden per E-Mail benachrichtigt, als das geschah. Erneute Zustellversuche aus der Warteschlange werden fortgesetzt.
Doppelte Webhook-Zustellungen
Ursache: Eine langsame 2xx-Antwort (über 8 Sekunden) gilt als Fehler und wird erneut versucht.
Beheben: Antworten Sie zuerst und verarbeiten Sie danach. Deduplizieren Sie anhand der id im Payload, die bei Wiederholungsversuchen stabil bleibt.
429 rate_limited während eines Imports
Ursache: 600 Anfragen pro Minute und Schlüssel.
Beheben: Verwenden Sie POST /codes/bulk (2.000 Codes in einer Anfrage) statt eines POST pro Code oder warten Sie die in Retry-After angegebene Anzahl Sekunden.
Ich habe einen Code gelöscht und auf dem gedruckten Poster steht jetzt „Code not found“
Ursache: Das Löschen ist endgültig und deaktiviert den Link.
Beheben: Es gibt keine Rückgängig-Funktion. Verwenden Sie beim nächsten Mal PATCH { paused: true }; ein pausierter Code zeigt eine hilfreiche Seite an und kann wieder aktiviert werden.
Mein Schlüssel funktioniert nach einem Downgrade nicht mehr
Ursache: Schlüssel funktionieren nach dem Wechsel vom Business-Tarif noch 30 Tage und liefern danach 402 zurück.
Beheben: Abonnieren Sie erneut; es wurde nichts gelöscht, und dieselben Schlüssel funktionieren wieder.
Ist Ihre Frage nicht aufgeführt? Schreiben Sie an hello@qrflow.codes und geben Sie die genaue Anfrage sowie den JSON-Fehler an, den Sie erhalten haben. Business-Konten erhalten bevorzugte Unterstützung.
Limits und faire Nutzung
| Limit | |
|---|---|
| Anfragen pro Minute und Schlüssel | 600. Darüber hinaus 429 mit Retry-After. |
| Schlüssel pro Konto | 10 |
| Webhooks pro Konto | 10 |
| Gespeicherte Codes (faire Nutzung) | 1.000 Premium, 25.000 Business; die API stoppt beim Doppelten davon. |
| Bulk | 500/Monat (500 pro Anfrage) Premium; 10.000/Monat (2.000 pro Anfrage) Business. |
| Link-Domains | 1 Premium, 5 Business |
| Scans | Unbegrenzt. Bei 100.000 Scans pro Code und Monat im Premium-Tarif und 1.000.000 im Business-Tarif erhalten Sie eine Hinweis-E-Mail; es gibt keine Drosselung. |
| Zeitraum für Scan-Analysen | 92 Tage pro Anfrage |
| Seitengröße für Listen | 100 (?limit=) |
| Label / Captions / slug | 120 / 60 / 40 Zeichen |
| Webhook-Timeout und Wiederholungen | 8 Sekunden; Wiederholungen nach 1, 5, 15, 60, 240 und 720 Minuten; Deaktivierung nach 20 aufeinanderfolgenden Fehlern. |
| Nach dem Wechsel vom Business-Tarif | Schlüssel und Webhooks funktionieren noch 30 Tage, danach 402. Es wird nichts gelöscht. |
Faire Nutzung entspricht dem, wofür der Tarif ausgelegt ist. Bei diesem Wert wird nichts gedrosselt; die API stoppt beim Doppelten davon, und Sie werden vorher von einer Person per E-Mail benachrichtigt. Für höhere Volumen: hello@qrflow.codes.
Sicherheit für Sie und die Personen, die scannen
So schützt QRFLOW Ihr Konto
- Schlüssel werden nur einmal angezeigt und als SHA-256-Hashes gespeichert. Niemand bei QRFLOW kann einen Schlüssel wieder auslesen; wenn Sie ihn verlieren, erstellen Sie einen neuen.
- Jede Anfrage ist auf das Konto beschränkt, zu dem der Schlüssel gehört. Eine Code-ID aus einem anderen Konto liefert 404 und wird niemals offengelegt.
- Berechtigungen sind pro Schlüssel festgelegt, sodass ein Schlüssel für ein Reporting-Dashboard keine Codes erstellen oder löschen kann.
- 600 Anfragen pro Minute und Schlüssel; darüber hinaus gibt es einen eindeutigen 429-Fehler, statt alle auszubremsen.
- Ziele sind auf eine Zulassungsliste beschränkt: http, https, mailto, tel, sms, geo und eine kurze Liste von App-Schemas (whatsapp, tg, signal, spotify, App-Stores). javascript:, data: und file: werden bereits beim Erstellen abgelehnt, sodass eine kompromittierte Integration Ihre Codes nicht in einen Angriff verwandeln kann.
- Webhook-URLs müssen https auf öffentlichen Hosts verwenden; QRFLOW ruft niemals private Netzwerke oder sich selbst auf. Jede Zustellung ist signiert und jeder Payload hat eine stabile id.
- OAuth-Clients registrieren sich mit PKCE S256, und Tokens sind an den Server gebunden, für den sie ausgestellt wurden; ein Token für den MCP-Server kann nicht auf der REST-API wiederverwendet werden.
- Jeder kann auf der Account-Seite einen Schlüssel widerrufen oder eine App trennen; die Änderung tritt sofort in Kraft.
Was Sie auf Ihrer Seite tun sollten
- Umgebungsvariablen, niemals Quellcode. Wenn ein Schlüssel in einem Git-Verlauf landet, widerrufen Sie ihn.
- Nur serverseitig. Die API lehnt Browser-Ursprünge ab, aber auch Ihre eigenen Endpunkte, die sie umschließen, benötigen Authentifizierung. Andernfalls kann jeder auf Ihre Rechnung Codes erstellen.
- Geben Sie jeder Integration einen eigenen Schlüssel mit den benötigten Berechtigungen und benennen Sie ihn nach der Integration. Wenn Sie einen Schlüssel widerrufen, ist dann nur eine Sache betroffen.
- Verifizieren Sie Webhook-Signaturen und lehnen Sie Zeitstempel ab, die älter als fünf Minuten sind.
- Wenn Daten Ihrer Nutzer in Labels oder Zielen landen, denken Sie daran, dass QRFLOW sie speichert; vermeiden Sie nach Möglichkeit personenbezogene Daten in Labels.
Was Scans erfassen und was nicht
- Bei jeder Weiterleitung werden Gerätetyp, Land, Stadt, Referrer, Browser, Betriebssystem und Sprache aus der Anfrage abgeleitet und gespeichert. Außerdem wird ein Einweg-Hash aus Code + Tag + IP + User-Agent gespeichert, damit der Eigentümer eindeutige Besucher zählen kann. Der Hash lässt sich nicht in eine Adresse zurückverwandeln.
- Bei der scannenden Person werden keine Cookies gesetzt, und die IP-Adresse selbst wird nicht zusammen mit dem Scan gespeichert. Bekannte Bots und Link-Vorschau-Crawler werden übersprungen.
- Beim Löschen eines Codes werden dessen Scans gelöscht. Beim Löschen des Kontos wird alles gelöscht.
- Vollständiger Text: https://qrflow.codes/privacy und https://qrflow.codes/terms.
Versionierung und Stabilität
Die API ist im Pfad versioniert: /api/v1. Innerhalb von v1 fügen wir Felder, Endpunkte, Typen und Ereignisse hinzu; wir entfernen oder benennen nichts um, und unbekannte Felder in Antworten sollten von Ihrem Code ignoriert werden.
Falls eine Änderung v1 jemals inkompatibel machen muss, wird sie als /api/v2 veröffentlicht, und v1 bleibt mindestens zwölf Monate in Betrieb. Schlüsselinhaber werden 90 Tage vor einer Einstellung per E-Mail benachrichtigt.
Der MCP-Server folgt für seine Tools derselben Regel: Es werden nur Argumente hinzugefügt, und jedes Tool behält seinen Namen.
Das OpenAPI-Dokument unter /api/v1/openapi.json und das Markdown unter /llms-full.txt werden aus dem Code generiert, der die API bereitstellt. Sie beschreiben daher den aktuellen Live-Stand.
Häufige Fragen von Entwicklern
Muss ich für die Nutzung der QRFLOW-API bezahlen?
API-Schlüssel sind im Business-Tarif enthalten, der 29 $ pro Monat kostet und monatlich kündbar ist. Der MCP-Server (Claude, ChatGPT, Cursor, Claude Code) und OAuth für Ihre eigene App funktionieren in jedem Tarif über die Anmeldung; was sie erstellen dürfen, richtet sich nach dem Tarif. GET /catalog, GET /frames und /preview.svg benötigen überhaupt keinen Schlüssel.
Kann ich über die API kostenlos QR-Codes generieren?
Nicht mit einem Schlüssel. Für ein einfaches statisches Bild reicht der kostenlose Generator auf qrflow.codes oder eine beliebige Open-Source-QR-Bibliothek. Die API ist für dynamische Codes, Ihre eigene Domain, Analysen, Bulk und Webhooks gedacht – Funktionen, die zu einem kostenpflichtigen Konto gehören.
Kann ich die API vom Browser aus aufrufen?
Nein. Sie lehnt Browser-Ursprünge ab, damit ein Schlüssel niemals auf einer Webseite landet. Rufen Sie sie von einem Route Handler, einer Server Action, einer Edge Function oder einem Backend aus auf und rufen Sie diesen von Ihrer Seite aus auf.
Welche Bildformate erhalte ich?
SVG mit Ihren Farben, Rahmen, Captions und Logo (GET /codes/:id/image.svg, nominal 256 bis 4096 px) sowie ein einfaches PNG (GET /codes/:id/image.png, 256 bis 2048 px). Für beide ist ein Bearer erforderlich, oder Sie verwenden die signierte svg_download_url / png_download_url, die jedes Code-Objekt enthält und 24 Stunden lang ohne Header funktioniert. Das MCP-Tool get_qr_image gibt das PNG inline sowie beide Links zurück.
Kann ich einen QR-Code ändern, nachdem er gedruckt wurde?
Ja, wenn er dynamisch ist (url, phone, email, sms, location in einem kostenpflichtigen Tarif). Verwenden Sie PATCH /codes/:id mit einem neuen destination_data; das Bild ändert sich nicht, aber der nächste Scan führt zum neuen Ziel. WLAN-, vCard- und Textcodes enthalten ihren Inhalt im Bild und können nicht geändert werden.
Was ist der Unterschied zwischen short_url und dem Ziel?
short_url ist der Link im Bild (go.example.com/menu). Das Ziel ist der Ort, zu dem dieser Link weiterleitet (https://example.com/menu-fall). Sie drucken short_url einmal aus und können das Ziel beliebig oft ändern.
Können Codes meine eigene Domain verwenden?
Ja. Premium verbindet 1 Domain, Business 5; Sie fügen einen CNAME hinzu und verifizieren ihn auf der Account-Seite. Im Business-Tarif wählen Sie pro Code eine Domain mit domain_id aus. Linknamen (slug) erstellen lesbare Pfade darauf.
Was wird über die scannende Person erfasst?
Gerätetyp, Land, Stadt, Referrer, Browser, Betriebssystem und Sprache aus der Anfrage sowie ein täglicher Einweg-Hash, um eindeutige Besucher zu zählen. Keine Cookies, und die IP-Adresse wird nicht gespeichert. Genug für ein Diagramm, aber nicht genug, um jemanden zu identifizieren. Details: https://qrflow.codes/privacy#scans
Gibt es ein npm- oder PyPI-Paket?
npm: npm install qrflow\ (https://www.npmjs.com/package/qrflow), keine Abhängigkeiten, ESM und CommonJS, vollständige TypeScript-Typen, läuft mit Node 18+, Bun, Deno und Workers; es kapselt jeden Endpunkt, wiederholt 429-Anfragen und enthält verifyWebhook/parseWebhook. Python: ein Client in einer einzelnen Datei unter https://qrflow.codes/sdk/qrflow.py (nur Standardbibliothek) mit verify_webhook; ein PyPI-Paket folgt.
Funktioniert es mit Claude, ChatGPT, Cursor und Claude Code?
Ja. QRFLOW ist ein MCP-Server unter https://qrflow.codes/mcp. Fügen Sie ihn als Connector hinzu, melden Sie sich einmal an und stellen Sie Ihre Fragen in einfachen Worten. Elf Tools decken das Erstellen, Bearbeiten, Pausieren, Benennen, Bulk, Analysen, Bilder und Domains ab.
Können sich meine eigenen Nutzer mit ihren QRFLOW-Konten bei meiner App anmelden?
Ja, mit OAuth 2.0. Registrieren Sie einen Client unter /api/oauth/register (kein Konto erforderlich), leiten Sie Benutzer mit PKCE zu /oauth/authorize weiter und rufen Sie die API mit ihrem Token auf. Die Codes werden gemäß ihrem Tarif in ihrem Konto gespeichert.
Wie teste ich Webhooks auf localhost?
Machen Sie Ihren Entwicklungsserver mit einem Tunnel (cloudflared oder ngrok) öffentlich und verwenden Sie dessen https-Adresse als Webhook-URL. Klicken Sie dann unter Account › Webhooks auf Test, um einen signierten Ping zu empfangen. Webhook-URLs müssen öffentliches https verwenden; localhost und private Adressen werden abgelehnt.
Was passiert mit meiner Integration, wenn ich Business kündige?
Schlüssel und Webhooks funktionieren noch 30 Tage lang und antworten danach mit 402. Codes, Scans und Domains bleiben im Konto. Wenn Sie erneut ein Abonnement abschließen, wird alles mit denselben Schlüsseln wieder aktiviert.
Wie erstelle ich über die API einen Google-Bewertungs-, Instagram-, WLAN- oder PDF-Code?
GET /catalog listet alle Arten mit ihren Feldern auf. Senden Sie dann POST /codes mit dem Typ und den Feldern der jeweiligen Art und fügen Sie bei folgenden Arten subtype hinzu: { type: 'url', destination_data: { subtype: 'googlereview', placeId: 'ChIJ…' } }, { type: 'wifi', destination_data: { ssid, password, encryption: 'WPA' } }, { type: 'url', destination_data: { subtype: 'instagram', handle: 'acme' } }.
Kann die API ein Logo auf einen Code hochladen?
Noch nicht. Fügen Sie das Logo im Dashboard hinzu; image.svg enthält es, und has_logo zeigt an, ob es vorhanden ist. Farben, Rahmen und Beschriftungen lassen sich alle über die API festlegen.
Ist die API stabil?
v1 wird nur erweitert; nichts wird entfernt oder umbenannt. Eine inkompatible Änderung würde als v2 veröffentlicht. v1 bliebe mindestens zwölf Monate lang verfügbar, und eine Ankündigung per E-Mail würde 90 Tage im Voraus erfolgen.
Für Agents, Tools und die Assistenten, die dies lesen
Maschinenlesbar
Alles auf dieser Seite ist in einer Form verfügbar, die Software abrufen kann. Alles wird aus dem Code generiert, der die API bereitstellt, und ist daher immer aktuell.
| URL | Beschreibung | |
|---|---|---|
| llms-full.txt | https://qrflow.codes/llms-full.txt | Diese gesamte Referenz als Markdown: Konzepte, alle Endpunkte, alle MCP-Tools, Rezepte, Fehlerbehebung und FAQ. Wird aus derselben Quelle wie diese Seite generiert. |
| developers.md | https://qrflow.codes/developers.md | Dasselbe Dokument für Tools, die a.md abrufen. |
| llms.txt | https://qrflow.codes/llms.txt | Der Website-Index für Assistenten, der hierher verweist. |
| Die API auf einer Seite | https://qrflow.codes/qr-code-api | Was die API leistet, wann eine clientseitige Bibliothek die bessere Wahl ist und was sie kostet. Die Kurzfassung dieser Referenz, um eine Entscheidung zu treffen statt etwas zu entwickeln. |
| openapi.json | https://qrflow.codes/api/v1/openapi.json | OpenAPI 3.1. In Postman, Insomnia, einen Codegenerator oder eine ChatGPT Action importieren. |
| MCP-Server | https://qrflow.codes/mcp | Streamable HTTP, OAuth mit dynamischer Registrierung oder ein Business-Schlüssel als Bearer-Token. |
| server.json | https://qrflow.codes/.well-known/mcp/server.json | Das MCP-Registry-Manifest. |
| OAuth-Erkennung | https://qrflow.codes/.well-known/oauth-authorization-server | RFC-8414-Metadaten; das Dokument zur geschützten Ressource befindet sich daneben. |
| npm-Paket | https://www.npmjs.com/package/qrflow | npm install qrflow. Typisierter Client, keine Abhängigkeiten, Webhook-Verifizierung. Python-Client in einer einzelnen Datei unter https://qrflow.codes/sdk/qrflow.py. |
| GitHub | https://github.com/nativecodeapps/qrflow-sdk | Clients, OpenAPI-Snapshot und ausführbare Beispiele für Next.js, Workers, Express, FastAPI und Flask-Webhooks. Issues und PRs sind willkommen. |
Fragen, Ideen oder Vorschläge für eine Code-Art, die wir hinzufügen sollten: hello@qrflow.codes. Nutzungsbedingungen: /terms. Datenschutz: /privacy.