QR-Code-API und Webhooks
Mit der API können Ihre eigenen Programme QR-Codes erstellen, ändern, abrufen und löschen sowie deren Scan-Übersichten lesen. Webhooks schicken eine signierte Nachricht an Ihren Server, sobald sich ein Code ändert, ein Scan durch eine Person eingeht oder ein Landingpage-Formular beantwortet wird.
Was die API und die Webhooks leisten
Die REST-API liegt unter dem Pfad /api/v1 und antwortet im JSON-Format. Sie kann Codes mit einer Suche und einem Tag-Filter in Seiten mit bis zu hundert Codes auflisten, einen Code abrufen, Codes erstellen, ändern und löschen, ein schlichtes SVG eines Codes liefern und die Scans der letzten dreißig Tage zusammenfassen. Ein Schlüssel ist ein Bearer-Token, das mit qrk_ beginnt und zu genau einem Workspace gehört. Eine Anfrage kann daher nur die Codes dieses Workspaces erreichen.
Ein Webhook ist eine HTTPS-Adresse, die Sie für die Ereignisse registrieren, über die Sie informiert werden möchten. Für jedes Ereignis sendet die App eine JSON-Nachricht: Ein Code wird erstellt, geändert oder gelöscht, ein Scan durch eine Person wird erfasst oder ein Landingpage-Formular wird beantwortet. Eine Testaktion sendet ein Ping-Ereignis, mit dem Sie Ihren Empfänger prüfen, bevor echte Daten eintreffen. Jede Zustellung wird mit HMAC-SHA256 und dem Webhook-Secret über Zeitstempel und Body signiert.
Die API richtet sich an Personen, die Integrationen bauen, und sie verändert das Aussehen der Codes nicht. Das SVG ist schlicht schwarzweiß, ohne Logo, Form oder Farbe, weil gestaltete Bilder im Editor entstehen. Die API setzt den Team-Tarif voraus. Schlüssel bleiben bei einem Downgrade erhalten, funktionieren aber erst wieder, wenn der Workspace auf einen Tarif mit API zurückkehrt.
So starten Sie mit der API
-
01
Legen Sie als Inhaber einen Schlüssel an
Öffnen Sie als Inhaber die API-Seite, geben Sie dem Schlüssel einen Namen, etwa den des Servers, der ihn verwenden wird, und legen Sie ihn an. Das vollständige Token wird genau einmal angezeigt. Kopieren Sie es deshalb sofort in Ihren Secret-Manager. Danach zeigt die Seite nur noch den Namen, das Präfix, das Erstellungsdatum und die letzte Verwendung.
-
02
Senden Sie den Schlüssel bei jeder Anfrage mit
Übergeben Sie das Token in einem Authorization-Header, mit dem Wort Bearer, einem Leerzeichen und dem Token. Rufen Sie zuerst den Endpunkt zur Prüfung des Kontos auf. Die Antwort nennt den Workspace, den Schlüssel und die verbleibenden Credits und bestätigt so, dass die Einrichtung funktioniert. Ein fehlender oder falscher Schlüssel erhält die Antwort 401 (nicht autorisiert).
-
03
Codes erstellen, ändern und abrufen
Senden Sie den Namen, die Art (Standard ist ein Weblink), den Inhalt und die optionalen Felder: dynamic, slug, expiry, password, eine verifizierte Domain, tags und style. Das Erstellen eines Codes kostet einen Credit, Lesen und Aktualisieren sind kostenlos. Eine Anfrage, die die Prüfung nicht besteht, liefert die Gründe zurück und gibt den Credit wieder frei.
Wo die API sinnvoll ist
-
Ticketing und Buchungen
Bestätigt ein Buchungssystem einen Platz, erstellt es für dieses Ticket einen dynamischen Code und schickt Kurzlink und SVG an den Käufer. Die E-Mail oder der Wallet-Pass enthält denselben Code, und niemand muss ihn von Hand übertragen.
-
Lagerbestand und Inventaretiketten
Ein Lagerverwaltungssystem kann für jeden Artikel einen Code erstellen, wobei die Artikelnummer als Tag dient. Jeder Scan wird gespeichert. Das System kann die Übersicht der letzten dreißig Tage zu jedem Artikel lesen und so erkennen, welche Tags kürzlich geprüft wurden.
-
Restaurant-Menüs aus einer Tabelle
Ein Skript kann eine Tabelle mit Menülinks auslesen und über die API den Inhalt jedes dynamischen Codes aktualisieren. Die gedruckten Codes bleiben unverändert, und die Änderung gilt ab dem nächsten Scan.
-
Check-in und Feedbackformulare bei Events
Ein Eventteam kann eine Landingpage mit Formular veröffentlichen und für jede Antwort einen Webhook erhalten. Ein separates System reagiert auf das Ereignis, sodass niemand die Antworten abfragen muss.
-
Überwachung und Benachrichtigungen
Ein Webhook-Empfänger kann Scan-Ereignisse nach Land und Gerät speichern und eine Meldung auslösen, sobald ein Code nicht mehr gescannt wird. Was als Problem gilt, entscheidet Ihr System, denn die App liefert die Ereignisse aus und bewertet sie nicht.
Tipps für eine zuverlässige Integration
- Bewahren Sie den Schlüssel wie ein Passwort auf
- Schlüssel werden nur einmal angezeigt und lediglich als Hash gespeichert, deshalb kann die App sie nicht erneut zeigen. Gelangt ein Schlüssel nach außen, widerrufen Sie ihn auf der API-Seite und legen einen neuen an. Mit dem Widerruf werden alle Anfragen mit dem alten Token sofort abgewiesen.
- Beachten Sie das Ratenlimit und die Credits
- Jeder Schlüssel darf 120 Anfragen pro Minute senden. Wird diese Rate überschritten, erhält die Anfrage die Antwort 429 (zu viele Anfragen). Sind die Credits aufgebraucht, antwortet das Erstellen eines Codes mit 402 (Zahlung erforderlich), und der Fehlercode besagt, dass keine Credits mehr übrig sind. Die App bietet derzeit keine Möglichkeit, Credits nachzukaufen. Planen Sie Batch-Jobs deshalb anhand des Restguthabens.
- Prüfen Sie Signaturen und Zeitstempel
- Berechnen Sie mit Ihrem Secret den HMAC-SHA256 aus dem Zeitstempel, einem Punkt und dem unveränderten Request-Body und vergleichen Sie das Ergebnis mit dem Signatur-Header. Weisen Sie Zeitstempel ab, die zu alt sind, damit eine mitgeschnittene Anfrage nicht erneut abgespielt werden kann. Über die Zustell-ID erkennen Sie Wiederholungen und können sie ignorieren.
- Nutzen Sie einen Endpunkt, den Sie selbst betreiben
- Webhook-Adressen müssen HTTPS verwenden, dürfen keine Zugangsdaten enthalten und auf öffentliche Adressen auflösen. Lokale Hosts und private Netzbereiche werden abgelehnt, Weiterleitungen werden nicht verfolgt. Scheitert eine Zustellung, folgen bis zu fünf Wiederholungen mit längeren Pausen.
Fragen zur API und zu Webhooks
Welcher Tarif enthält die API?
Der Team-Tarif. Das Anlegen von Schlüsseln und Webhooks setzt ihn voraus. Ist der Workspace in einem Tarif ohne API, antwortet die API mit 402 (Zahlung erforderlich). Bestehende Schlüssel bleiben bei einem Downgrade erhalten und funktionieren wieder, sobald der Tarif zurückkehrt.
Wofür wird ein Credit verbraucht?
Für jeden über die API erstellten Code wird ein Credit verbraucht. Abrufen, Ändern und Löschen von Codes sowie das Lesen der Scan-Übersicht kosten nichts. Scheitert das Erstellen an der Prüfung, wird der Credit zurückgegeben.
Mit wie vielen Credits startet ein Workspace?
Mit vierzig Credits. Dieser Wert ist in der Datenbank als Standard für jeden Workspace hinterlegt. Die App bietet noch keine Seite zum Nachkauf. Prüfen Sie das Guthaben deshalb auf der API-Seite oder über die Kontoabfrage, bevor Sie einen großen Import starten.
Kann ich den Code über die API als Bild abrufen?
Ja, als schlichtes SVG. Sie legen die Modulgröße zwischen eins und zwanzig und den Rand zwischen null und zehn fest. Das Bild ist schwarzweiß und ohne Logo. Ist der Inhalt zu lang für einen QR-Code, meldet die API das. Für Formen, Farben oder ein Logo verwenden Sie den Editor.
Welche Ereignisse kann ich abonnieren?
Erstellen, Ändern und Löschen eines Codes, ein Scan durch eine Person sowie die Beantwortung eines Landingpage-Formulars. Bot-Anfragen und Link-Vorschauen lösen keine Scan-Ereignisse aus, und ein Testereignis lässt sich an jeden Webhook senden.
Was passiert, wenn mein Endpunkt nicht erreichbar ist?
Die Zustellung wird bis zu fünfmal mit wachsenden Wartezeiten wiederholt. Jeder Versuch hat einen Verbindungs-Timeout von fünf Sekunden und einen Lese-Timeout von zehn Sekunden. Nach dem letzten Fehlschlag wird die Zustellung als fehlgeschlagen markiert, und die Webhook-Seite zeigt den Antwortcode und den letzten Fehler an.
Erstellen Sie Ihren ersten Code in einer Minute
Der Editor ist kostenlos. Legen Sie ein Konto an, wenn Sie Codes speichern, Scans verfolgen oder ein Ziel später ändern möchten.