QR-Codes automatisch erzeugen: API, Webhooks, No-Code

Um elf Uhr abends öffnet eine Ticketkoordinatorin eine Tabelle mit 2.300 Anmeldungen und beginnt, URLs zeilenweise in einen Generator zu kopieren. Bei Zeile sechzig fangen die Fehler an: eine übersprungene Zeile, ein doppelter Dateiname, ein Code, der einen anderen überschreibt. Schwer war an dieser Aufgabe nie etwas. Sie war nur zu lang für Handarbeit, und nächsten Monat steht sie in gleicher Länge wieder da.

Das ist die Form des Problems, das Automatisierung löst. Nicht "wir machen viele Codes", sondern "wir machen einen Code je Datensatz, und Datensätze kommen ständig nach".

Wann Automatisierung ihren Aufwand wert ist

Bauen Sie Automatisierung, wenn ein Code zu einem Ding gehört und nicht zu einer Kampagne. Einer je Bestellung. Einer je Inventarnummer, Mieteinheit, Tisch, Sendung oder Veranstaltungsanmeldung. Das Erkennungszeichen ist, dass die Anzahl mit dem Geschäft wächst und nicht mit dem Marketingkalender.

Das zweite Erkennungszeichen ist der Zeitpunkt. Der Code muss in einem Moment existieren, den niemand planen kann: eine Bestellung um drei Uhr nachts, die einen Lieferschein braucht, ein Gerät, das aus einem Karton geholt und vor Ort in Betrieb genommen wird. Wenn in diesem Moment kein Mensch vor einem Browser sitzt, muss die Erzeugung an einem Ereignis hängen.

Trifft keines von beiden zu, sparen Sie sich die Integration. Ein paar hundert Codes, einmalig aus einer Liste erzeugt, die Sie schon haben, ist ein Fall für einen Massengenerator und eine CSV: eine Spalte mit Zielen hochladen, einen Ordner mit Bildern herunterladen, vor dem Mittagessen fertig, nichts bleibt zu warten. Etliche Teams bauen eine Pipeline für Arbeit, die zweimal im Jahr anfällt.

Die Form einer Erzeugungsanfrage

Anbieter unterscheiden sich in Benennung und Detail, behandeln Sie das also als allgemeine Anatomie und nicht als jemandes tatsächlichen Vertrag. Lesen Sie die Dokumentation des Dienstes, den Sie wählen.

Was hineingeht:

• Die Nutzlast. Was kodiert wird: eine URL, eine Telefonnummer, WLAN-Zugangsdaten, eine Kontaktkarte. Die einzige wirklich erforderliche Eingabe.
• Aussehen. Vorder- und Hintergrundfarbe, Modulform, Logo, Rand und Fehlerkorrekturstufe. Die vier Stufen stellen rund 7, 15, 25 und 30 Prozent eines beschädigten Symbols wieder her, von niedrig nach hoch.
• Ausgabe. Format und Maße. Raster für Bildschirme; Vektor, wenn irgendetwas nachgelagert in eine Druckerei geht.
• Metadaten. Ein Name, ein Ordner, eine Kampagnenbezeichnung. Uninteressant bis Code Nummer 8.000, ab dem sie die einzige Möglichkeit sind, Code Nummer 12 zu finden.

Zurück kommt üblicherweise eines von drei Dingen: rohe Bilddaten, ein JSON-Körper mit dem Bild als Zeichenkette, oder ein JSON-Körper, der auf eine gehostete Datei zeigt, die Sie in einem zweiten Aufruf holen. Beim dritten verbrennen sich Leute die Finger, weil die Antwort schnell kommt und der Bilddownload trotzdem später scheitern kann.

Ein Bild zu erzeugen ist nicht dasselbe wie einen Code anzulegen

Zwei Vorgänge landen unter einer Überschrift und verhalten sich völlig verschieden.

Einen statischen Code zu erzeugen kommt einer reinen Funktion nahe. Ein Ziel geht hinein, ein Bild kommt heraus, beim Anbieter wird nichts gespeichert, und zweimal ausgeführt entsteht dasselbe Bild. Verlieren Sie die Datei, erzeugen Sie sie neu. Es gibt keinen Datensatz, der lecken, brechen oder Geld kosten kann.

Einen dynamischen Code anzulegen ist ein Schreibvorgang. Nun existiert irgendwo ein Datensatz: eine Kennung, eine kurze Weiterleitungs-URL, ein aktuelles Ziel und ein wachsender Stapel Scanereignisse, die Sie als Auswertung lesen können. Weil es ein Schreibvorgang ist, kann er halb scheitern, er kann sich verdoppeln, und er muss aufgeräumt werden, wenn das Ding, auf das er zeigt, verschwindet. Jeder schwierige Teil des Automatisierens von QR-Codes führt auf diese Unterscheidung zurück.

Idempotenz, oder die Nacht, in der ein Webhook vierzig Codes machte

Hier ist der Fehler, der irgendwann in all diesen Integrationen auftaucht. Ein Zahlungsanbieter feuert einen Webhook zu einer angelegten Bestellung. Ihr Handler ruft die QR-API auf, bekommt einen Code zurück, läuft dann beim Schreiben in Ihre eigene Datenbank in eine Zeitüberschreitung und liefert nie eine 200. Der Anbieter versucht es erneut. Fünf Minuten später hat diese Bestellung sechs dynamische Codes, fünf davon verwaist und alle gegen Ihren Tarif gezählt.

Drei Abwehrmaßnahmen, nach Wirksamkeit geordnet:

• Verschlüsseln Sie den Vorgang über Ihren eigenen Datensatz. Eine Eindeutigkeitsbedingung auf der Bestell-ID in der Tabelle, die den Codeverweis hält, ist die billigste Korrektheit, die Sie je kaufen.
• Prüfen Sie, bevor Sie anlegen. Schlagen Sie den vorhandenen Code für diesen Datensatz nach und geben Sie ihn zurück, statt einen weiteren zu prägen. Das macht auch Wiederholungen sicher.
• Senden Sie einen Idempotenzschlüssel, wenn die API einen annimmt. Leiten Sie ihn deterministisch aus Ihrer Datensatz-ID ab, nie aus einem Zeitstempel oder Zufallswert, sonst erzeugt der Wiederholungsversuch einen neuen Schlüssel und hebelt den Zweck aus.

Schreiben Sie den Codeverweis in derselben Transaktion in Ihre Datenbank, die den Auftrag als erledigt markiert. Wenn diese beiden auseinanderdriften können, werden sie es tun.

Ratenlimits, Bündelung und die Nachbefüllung, die sie sprengt

Der Dauerbetrieb ist selten das Problem. Ein Code je Bestellung ist ein Rinnsal. Die Nachbefüllung ist das Problem: der Nachmittag, an dem jemand beschließt, dass alle 40.000 vorhandenen Anlagen Codes brauchen, und die ganze Liste auf einmal abfeuert.

Lesen Sie die veröffentlichten Limits des Dienstes, statt sie zu raten, und bauen Sie trotzdem für den allgemeinen Fall. Eine Warteschlange statt einer Schleife. Eine Obergrenze für gleichzeitige Anfragen. Exponentielles Zurückweichen mit Streuung bei jeder 429 oder 5xx. Ein fortsetzbarer Auftrag, damit ein Absturz bei Element 19.000 nicht bei Element eins neu beginnt. Bietet der Anbieter einen Sammelendpunkt an, nutzen Sie ihn; eine Anfrage für 500 Codes schlägt 500 Anfragen in jeder Hinsicht, auch in Ihren Protokollen.

Verteilen Sie große Nachbefüllungen über Stunden. Nichts an einer fünf Jahre alten Anlage verlangt, dass ihr Code in den nächsten neun Minuten existiert.

Speichern Sie die Kennung, nicht nur das Bild

Das Bild ist das Wertloseste in der Antwort. Speichern Sie neben Ihrem eigenen Datensatz: die Codekennung des Anbieters, die kurze URL, das Ziel zum Zeitpunkt der Anlage und den Erstellungszeitstempel.

Diese Zeile ist es, die Sie einen Code umleiten lässt, wenn die Landingpage umzieht, ein Etikett neu drucken lässt, ohne zu raten, was es kodiert hat, "wer hat das wann gemacht" beantwortet und den Code löschen lässt, wenn der Datensatz verschwindet. Teams, die das auslassen, landen bei einem Dashboard voller Codes, die niemand irgendetwas zuordnen kann, was dasselbe ist wie gar keine zu haben. Selbst für schlichte Ziele aus einem URL-Code-Generator schlägt eine Datenbankspalte einen Ordner voller Dateien namens final_v3.

Auftragsverarbeitung und Verfahrensdokumentation

Sobald eine Automatisierung personenbezogene Daten durch fremde Systeme schiebt, hängt an jedem Glied der Kette ein Vertrag. Der Generator verarbeitet in Ihrem Auftrag, die Automatisierungsplattform in der Mitte ebenfalls, und für beide brauchen Sie einen Vertrag zur Auftragsverarbeitung nach Art. 28 DSGVO. Sitzt ein Dienst außerhalb der EU, kommt die Frage der Übermittlung in ein Drittland hinzu, die über einen Angemessenheitsbeschluss oder über Standardvertragsklauseln beantwortet wird. Tragen Sie beides in Ihr Verzeichnis der Verarbeitungstätigkeiten ein, und zwar an dem Tag, an dem Sie den Ablauf bauen, nicht in dem Monat, in dem die Aufsichtsbehörde danach fragt.

Die zweite deutsche Anforderung betrifft nicht den Datenschutz, sondern das Finanzamt. Wenn Ihr Ablauf Bestell-, Rechnungs- oder Belegdaten anfasst, fällt er unter die Grundsätze zur ordnungsmäßigen Führung und Aufbewahrung von Büchern in elektronischer Form. Verlangt wird dort unter anderem, dass steuerlich relevante Aufzeichnungen nachvollziehbar und unveränderbar bleiben und dass eine Verfahrensdokumentation beschreibt, welches System welche Daten wohin schreibt. Ein Webhook, der still eine Bestellzeile um eine Codekennung ergänzt, gehört in dieses Dokument. Zwei Absätze über Auslöser, Zielfeld, Fehlerbehandlung und Aufbewahrungsdauer genügen dafür, aber sie müssen vorhanden sein, bevor eine Prüfung danach fragt. Derselbe Text hilft übrigens dem Kollegen, der den Ablauf in drei Jahren übernimmt.

Wenn niemand im Team programmiert

Für den größten Teil dieser Aufgaben genügen No-Code-Automatisierungsplattformen. Ein Auslöser reagiert auf eine neue Tabellenzeile, eine Formularantwort oder einen Datensatz im CRM, ein HTTP-Schritt ruft den Generator, ein weiterer Schritt schreibt Kennung und Bild zurück. So gebaute Abläufe laufen jahrelang, ohne dass eine Entwicklerin sie noch einmal anfasst.

Zwei Dinge, die Sie einplanen sollten. Diese Plattformen rechnen nach Aufgaben ab, eine Nachbefüllung kann also an einem Nachmittag das Monatskontingent verbrennen; schieben Sie große Aufträge stattdessen durch einen Massenupload. Und ihre Fehlerbehandlung ist standardmäßig leise, ein Schritt, der um zwei Uhr nachts scheitert, kann also in einem Protokoll liegen, das niemand öffnet. Ergänzen Sie eine ausdrückliche Fehlermeldung in einen Kanal, den ein Mensch liest.

Fangen Sie eng an. Nehmen Sie den einen Datensatztyp, der einen Code am dringendsten braucht, ergänzen Sie in dieser Tabelle eine einzelne Spalte für die Kennung, und erzeugen Sie die ersten zehn von Hand über die API. Scannen Sie alle zehn mit einem echten Telefon. Wenn sie auflösen, verdrahten Sie den Auslöser.