Eine QR-Code-API: was sich zu automatisieren lohnt — und was nicht

Die meisten QR-Codes sollte ein Mensch einmal anlegen und drucken. Eine API verdient sich dort, wo das unmöglich ist: ein Code je Bestellung, je Buchung, je Anlage, je Nutzer — erzeugt in einem Moment, den niemand vorhersagt, in einer Menge, die niemand klicken will.

Wann eine API richtig ist

• Ein Code je Datensatz in einem System, das Sie ohnehin betreiben: Ticket, Auftrag, Anlagenschild, Sendung.
• Ziele, die sich errechnen lassen. Ist die Ziel-URL aus Ihren Daten ableitbar, ist das Abtippen keine Entscheidung, sondern eine Fehlerquelle.
• Scan-Daten, die in Ihre eigene Auswertung gehören, neben Bestellungen und Umsatz.

Wann nicht

• Eine Marketingkampagne. Ein halbes Dutzend Codes, von Menschen gewählt und gestaltet.
• Alles, wo das Design zählt. Die API erzeugt Codes und verwaltet Ziele; Stil, Rahmen und Vorlagen sind Sache des Editors.
• Ein einmaliger Stapel. Dafür gibt es den CSV-Upload — eine Tabelle ist die schnellere Integration.

Authentifizierung

Der Schlüssel wird im Dashboard erzeugt und einmal angezeigt. Gespeichert wird nur ein SHA-256-Hash samt den ersten Zeichen zur Unterscheidung — ein verlorener Schlüssel lässt sich nicht wiederherstellen, nur ersetzen.

Authorization: Bearer enq_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Die API gehört zum Tarif Business. Es gelten 60 Anfragen pro Minute je Konto; darüber antwortet 429 mit rate_limited — ein Signal zum Bündeln, nicht zum Wiederholen in enger Schleife.

Code erzeugen

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

{ "name": "Bestellung 10432 – Lieferschein", "url": "https://shop.example/orders/10432" }

• Eigene Kennung in den Namen. Der Name macht fünftausend Codes später navigierbar.
• Die zurückgegebene id am Datensatz speichern, sonst heißt Ändern später: nach Namen suchen und hoffen.

Der Rest

• GET /api/v1/qrcodes — Ihre Codes, neueste zuerst, mit Cursor-Paging.
• GET /api/v1/qrcodes/{id} — ein Code.
• PATCH /api/v1/qrcodes/{id} — Ziel ändern. Darauf beruht die ganze Idee des dynamischen Codes.
• DELETE /api/v1/qrcodes/{id} — löschen. Bereits Gedrucktes hört auf zu funktionieren.
• GET /api/v1/qrcodes/{id}/scans — Scans, neueste zuerst, bis zu 1.000.

Was ein Scan-Datensatz enthält

Zeitpunkt, Gerätetyp, Betriebssystem und Browser laut Anfrage, Referrer falls gesendet. Keine Identität, kein Konto und kein Standort — weder Stadt noch Land.

Vor dem Report-Entwurf zu wissen: "wie viele, wann, auf welchem Gerät" ist beantwortbar, "wer" und "wo" nicht.

Fehler, die wirklich vorkommen

• 401 invalid_api_key — Header fehlt oder Schlüssel ersetzt.
• 400 invalid_body — meist eine URL, die keine ist.
• 402 plan_limit_reached — Codelimit erreicht; Business hat keins, also gehört der Schlüssel zu einem kleineren Tarif.
• 429 rate_limited — mehr als 60 Anfragen je Minute.

Zwei Dinge von Anfang an richtig

Erzeugung auf Ihrer Seite idempotent machen. Zweimal gefragt heißt zwei Codes — Wiederholungen und Zeitüberschreitungen fragen irgendwann zweimal.

Nichts drucken, was nicht zurückgelesen wurde. Eine Anfrage nach dem Anlegen verhindert den einzigen Fehler, der sich später nicht korrigieren lässt.

Kurze Antworten

• Welcher Tarif? Business.
• Authentifizierung? Authorization: Bearer enq_….
• Schlüssel verloren? Nicht wiederherstellbar — neu erzeugen, alten widerrufen.
• Ratenlimit? 60 Anfragen pro Minute je Konto.
• Ziel änderbar? Ja, per PATCH.
• Standort in den Scan-Daten? Nein.
• Nur einmalig 500 Codes? CSV-Upload statt Integration.