QR-Code-API auswählen: die Fragen vor dem Vertrag

Zwei Anbieter bewerben beide eine QR-Code-API. Der eine nimmt eine Zeichenkette in einer Anfrage entgegen und gibt ein PNG zurück. Der andere legt einen Datensatz auf seinen Servern an, händigt Ihnen eine kurze URL zum Kodieren aus, zählt jeden Scan darauf und lässt Sie das Ziel im nächsten Quartal ändern. Dieselbe Formulierung auf der Marketingseite, zwei verschiedene Produkte, zwei verschiedene Fehlerbilder, und für einen deutschen Einkauf zwei völlig verschiedene Vertragsgespräche.

Zwei verschiedene Produkte teilen sich einen Namen

APIs zur Bilderzeugung sind zustandslos. Sie übergeben Inhalt, Sie bekommen ein Bild zurück. Auf Anbieterseite bleibt nichts bestehen, nichts wird getrackt, und wenn der Anbieter verschwindet, funktionieren Ihre bereits erzeugten Codes weiter, weil ein statischer Code sein Ziel im Muster selbst trägt.

Verwaltete dynamische APIs sind zustandsbehaftet. Der Anbieter prägt einen Code, hostet die Weiterleitung, protokolliert Scans und stellt einen Aufruf bereit, mit dem Sie das Ziel später ändern. Alles, was Sie gedruckt haben, hängt davon ab, dass dieser Dienst Anfragen auflöst, auf deren Infrastruktur, für die gesamte Lebensdauer des Drucks.

goQR.me zeigt die Trennung innerhalb eines Unternehmens: Neben dem Generator wird eine dokumentierte kostenlose QR-API veröffentlicht, während dynamische Codes und Analysen in einem separaten kostenpflichtigen Produkt stecken. Die Dokumentation eines beliebigen Anbieters mit dieser Unterscheidung im Kopf zu lesen, erspart viel Verwirrung, denn "QR-API" in einer Überschrift kann beides bedeuten. Wenn das Ziel nach dem Versand änderbar sein muss, wird ein Bild-Endpunkt Ihnen das nie bieten, und Sie brauchen dynamische Codes mit verwalteter Weiterleitung.

Ausgabeformate und Vektor

Fragen Sie drei Dinge zur Ausgabe ab: welche Rasterformate unterstützt werden, ob überhaupt ein Vektorformat verfügbar ist und ob Vektor extra kostet.

Vektor ist wichtiger, als Entwickler erwarten, weil der Code irgendwann meist doch in der Druckdatei von jemandem landet. PNG deckt Bildschirme und kleine Etiketten ab. Großformatiger Druck will SVG, EPS oder PDF. Manche Anbieter liefern Vektor kostenlos mit, andere stellen ihn hinter eine kostenpflichtige Stufe, und diese Grenze verschiebt sich, lesen Sie also die aktuelle API-Dokumentation statt irgendeines Blogbeitrags darüber, diesen eingeschlossen.

Prüfen Sie außerdem, was die API steuern lässt: Ruhezone, Fehlerkorrekturstufe, Modulgröße sowie Vorder- und Hintergrundfarbe. Ein Endpunkt, der ein PNG in fester Größe ohne Randsteuerung zurückgibt, wird später gegen Ihr Layout arbeiten, und die Fehlerkorrekturstufe ist keine kosmetische Einstellung, wenn der Code auf gewölbte Verpackungen kommt.

Rate Limits und Batching

Jede Generierungs-API hat eine Obergrenze. Unterschiedlich ist das Verhalten an dieser Grenze: ein 429 mit Retry-Hinweis, eine stille Drosselung, eine harte Sperre oder eine Zusatzgebühr. Finden Sie die Antwort in der aktuellen Dokumentation des Anbieters und schreiben Sie Ihren Client gegen dieses konkrete Verhalten statt gegen eine allgemeine Annahme.

Bei Volumen zählt Batching. Zehntausend Codes einzeln per HTTP-Anfrage zu prägen ist langsam und fragil. Fragen Sie, ob es einen Batch-Endpunkt gibt, ob er asynchron mit einer Job-ID zum Abfragen arbeitet und wie Teilfehler gemeldet werden. Wenn ein Batch von fünftausend 4.998 Erfolge zurückgibt, müssen Sie wissen, welche zwei fehlgeschlagen sind, und nur diese erneut versuchen können. Unser eigener Massengenerator existiert, weil dieser Ablauf häufig genug ist, um eine Oberfläche zu verdienen. Über eine API gelten dieselben Fragen, nur mit Ihrer eigenen Retry-Logik.

Authentifizierung, und was ein Schlüssel darf

Betrachten Sie drei Eigenschaften des Auth-Modells.

• Geltungsbereich des Schlüssels. Können Sie einen Schlüssel ausstellen, der nur Bilder rendert, getrennt von einem, der Ziele ändern darf? Ein Schlüssel, der jeden aktiven Code umbiegen kann, gehört in eine andere Risikoklasse als einer, der nur zeichnen darf.
• Rotation. Können Sie einen Schlüssel ohne Ausfallzeit tauschen, und bekommt der alte Schlüssel eine Schonfrist?
• Transport. Schlüssel in Query-Strings landen in Serverlogs, Proxys und im Browserverlauf. Auth über Header ist die sicherere Voreinstellung, und wenn ein Anbieter nur Query-String-Schlüssel unterstützt, behandeln Sie die erzeugten URLs als Geheimnisse und halten Sie sie aus geteilten Logs heraus.

Auch nach Schlüsseln pro Umgebung sollten Sie fragen. Staging-Traffic, der die Scan-Analysen der Produktion verunreinigt, ist ein häufiger, langweiliger und teurer Fehler.

Speicherung: Bekommen Sie einen Code von vor einem Jahr zurück

Diesen Punkt vergessen Teams. Bei zustandslosen Bild-APIs lautet die Antwort meist nein: Das Bild existierte in der Antwort, und nichts wurde aufbewahrt. Das ist oft eher eine Datenschutzeigenschaft als eine Lücke, bedeutet aber, dass Ihr System die führende Quelle ist und Sie Inhalt und Render-Parameter selbst speichern müssen, um einen Code exakt zu reproduzieren.

Fragen Sie bei verwalteten Plattformen, ob Sie Codes auflisten, filtern und den Bestand samt Zielen und Erstellungsdaten exportieren können. Eine API, die Codes anlegt, aber keinen Listen-Endpunkt bietet, macht Sie unfähig, Ihren eigenen Bestand zu prüfen. Das wird beim ersten Mal zum echten Problem, wenn jemand fragt, welche Codes auf eine gerade gelöschte Seite zeigen. Diese Arbeit ist von Hand schmerzhaft genug, wie tote Codes aufspüren zeigt.

Idempotenz und wiederholte Webhooks

Zwei verwandte Probleme, eines auf jeder Seite der Leitung.

Auf der Schreibseite: Wenn Ihr Erstellungsaufruf in einen Timeout läuft, wurde der Code angelegt oder nicht? Ohne Idempotenzschlüssel erzeugt ein erneuter Versuch Duplikate, und Duplikate kosten in einem Tarif mit Abrechnung pro Code Geld und verschmutzen das Reporting. Prüfen Sie, ob der Anbieter beim Anlegen einen vom Client gelieferten Idempotenzschlüssel akzeptiert und wie lange er dedupliziert. Falls nicht, brauchen Sie einen eigenen Schutz: eine deterministische lokale ID, eine Abfrage vor dem erneuten Versuch und einen Abgleichjob.

Auf der Leseseite: Wenn die Plattform Webhooks für Scan-Ereignisse schickt, gehen Sie davon aus, dass sie mehr als einmal und gelegentlich in falscher Reihenfolge ankommen. Geben Sie jedem Ereignis eine stabile ID, speichern Sie die bereits verarbeiteten IDs, und machen Sie Handler sicher für doppelte Ausführung. Prüfen Sie, ob Webhooks signiert sind, und verifizieren Sie die Signatur, statt der Nutzlast zu vertrauen. Wenn Sie Scans in andere Systeme verdrahten, erbt Automatisierung über API oder Zapier dieselbe Anforderung am anderen Ende.

Beschaffung in Deutschland: Vertrag, Vergabe, Rechnung

Allgemeine Geschäftsbedingungen werden nach deutschem Recht streng geprüft, und ein pauschaler Haftungsausschluss oder eine einseitige Preisanpassungsklausel hält gegenüber einem deutschen Kunden nicht zwangsläufig. Trotzdem wollen Sie darüber nicht streiten, wenn eine Weiterleitung für vierzigtausend gedruckte Codes ausfällt. Verhandeln Sie stattdessen vier Punkte schriftlich: eine Verfügbarkeitszusage mit benannter Reaktionszeit, eine Vorlaufzeit für Preisänderungen, die Herausgabe der vollständigen Codeliste samt Scan-Daten in einem maschinenlesbaren Format bei Vertragsende, und eine Frist, in der die Weiterleitungen nach einer Kündigung weiterlaufen. Der letzte Punkt ist der wichtigste, weil er entscheidet, ob eine Kündigung Ihre Auflage entwertet.

Auf der Datenschutzseite gehören ein Vertrag zur Auftragsverarbeitung, eine aktuelle Liste der Unterauftragnehmer mit Widerspruchsrecht bei Neuaufnahmen, eine Angabe zum Serverstandort und ein Löschkonzept dazu. Für gedruckte Serien lohnt zusätzlich eine technische Forderung mit vertraglicher Wirkung: Lassen Sie die Weiterleitung auf einer Subdomain Ihrer eigenen Domain laufen, nicht auf der des Anbieters. Dann hängt Ihre Auflage am eigenen Namen, und ein Anbieterwechsel ist eine Umstellung im DNS statt ein Nachdruck.

Zwei Formalien übersehen deutsche Käufer regelmäßig. Öffentliche Auftraggeber, also Kommunen, Schulen, Hochschulen und Kliniken in öffentlicher Hand, dürfen kein Abo mit der Firmenkarte abschließen, sondern sind an das Vergaberecht mit seinen Schwellenwerten und Verfahrensarten gebunden; das verlängert die Beschaffung um Monate und muss in die Projektplanung. Und bei der Rechnung: Unternehmen in Deutschland müssen elektronische Rechnungen in einem strukturierten Format empfangen können, öffentliche Auftraggeber verlangen ein festgelegtes Format. Ein Anbieter, der nur ein PDF per Mail schickt, erzeugt in Ihrer Buchhaltung dauerhaft Handarbeit, und das ist ein Auswahlkriterium wie jedes andere.

Uptime, und die Lizenz, die Sie tatsächlich kaufen

Zwei Fragen bleiben am Ende übrig, und beide entscheiden sich im Vertrag statt in der Dokumentation. Die erste betrifft die zugesagte Verfügbarkeit, die zweite das, was Sie an Rechten tatsächlich einkaufen.

Uptime bedeutet je nach Einsatzort etwas anderes. Rufen Sie die API einmal zur Buildzeit auf, um ein Bild zu rendern, ist ein Ausfall eine Unannehmlichkeit, die Sie mit Wiederholungen überbrücken. Steckt die Weiterleitung des Anbieters im Scan-Pfad gedruckter Materialien, wird deren Ausfall zu Ihrem Ausfall, öffentlich, vor einer Kundin mit dem Telefon in der Hand. Verlangen Sie eine veröffentlichte Statusseite, eine Störungshistorie und die Auskunft, ob es in Ihrer Stufe ein SLA gibt. Fragen Sie nach der Redirect-Infrastruktur getrennt von der API, denn das sind oft verschiedene Systeme mit unterschiedlicher Zuverlässigkeit.

Der zweite Punkt ist die Lizenz. Lassen Sie sich bestätigen, dass erzeugte Codes kommerziell und im Druck verwendet werden dürfen, dass keine Namensnennung nötig ist und dass diese Erlaubnis das Ende Ihres Abonnements für bereits erzeugte Codes überdauert. Manche Anbieter sagen das klar: Die Generatorseite von goQR.me nennt ihre Codes kostenlos mit erlaubter kommerzieller und gedruckter Nutzung. Andere sagen gar nichts, was nicht dasselbe ist wie ein Ja.

Ein praktischer Test, bevor Sie sich festlegen. Kodieren Sie Ihre längste realistische Nutzlast über jede infrage kommende API und scannen Sie das Ergebnis in Ihrer kleinsten Druckgröße. Die Länge der Nutzlast bestimmt die Modulanzahl, und wie viele Daten ein Code fassen kann entscheidet oft darüber, ob Ihre URLs eher gekürzt werden müssen als eine API zu brauchen.

Legen Sie dann die aktuellen API-Dokumentationen beider Anbieter nebeneinander und notieren Sie für jeden vier Dinge: zustandslos oder verwaltet, Vektor oder nicht, Batch oder nicht, und ob die Weiterleitung eine eigene Statusseite hat.