QR-Code-API: QR-Codes automatisch anlegen, ändern und auswerten

Wozu eine QR-Code-API dient

Eine QR-Code-API ist eine Programmierschnittstelle: Statt im Browser zu klicken, schickt dein Programm Anfragen an den QR-Code-Dienst und bekommt Antworten zurück. So entstehen Codes direkt aus einem Shop, einer Warenwirtschaft, einem Skript oder einer Tabelle.

Das lohnt sich, sobald sich Arbeit wiederholt: hundert Codes für Tische oder Produkte, monatliche Scan-Berichte, das Umstellen vieler Ziele nach einem Relaunch. Und es funktioniert nur mit dynamischen Codes. Ein dynamischer QR-Code von Same-QR enthält eine kurze, gleichbleibende Adresse, das Ziel dahinter liegt bei uns und lässt sich jederzeit ändern, ohne neu zu drucken.

Was die Same-QR-API abdeckt

Die REST-API liegt unter https://sameqr.com/api/v1. Sie ruft dieselben Funktionen wie das Dashboard auf, mit denselben Tarifgrenzen und Prüfungen:

• QR-Codes auflisten, lesen, anlegen, ändern und löschen.
• Die Statistik eines Codes: Scans, Anlagedatum, Zahl der Zieländerungen.
• Gastseiten wie Speisekarte, Preisliste, Öffnungszeiten, Linkseite, Aktion, Weingut, Wein-E-Label und Kontakt anlegen, ändern, veröffentlichen und offline nehmen.
• Eine Speisekarte aus bis zu vier Fotos oder einem PDF einlesen.
• Labels und Kundenprojekte verwalten und Anfragen aus Kontaktformularen lesen.

Eine maschinenlesbare Beschreibung aller Anfragen liegt unter /api/v1/openapi.json, die Anleitung auf sameqr.com/entwickler.

API-Schlüssel und Rechte

Den Schlüssel legst du im Dashboard unter Konto, Abschnitt „Zugang für CLI, Skripte und Agenten“ an. Du wählst eine von drei Stufen, „nur lesen“, „lesen + schreiben“ (anlegen, Namen und Texte ändern) oder „voll“ (zusätzlich Ziele ändern, offline nehmen, löschen), und eine Laufzeit von 30, 90, 180 oder 365 Tagen, wenn nötig auch unbegrenzt. Der Schlüssel beginnt mit sqr_live_ und wird genau einmal angezeigt. Gespeichert wird bei uns nur eine Prüfsumme.

Ein Schlüssel, der nur lesen darf, bekommt bei jeder ändernden Anfrage eine klare Absage. Für Berichte und Auswertungen ist das die richtige Wahl. Alles, was verändert, wohin ein gedruckter Code führt, ist zusätzlich geschützt: Zieländerungen, Offline-Nehmen und Löschen verlangen die Stufe „voll“ und eine Bestätigung mit dem zuvor gelesenen Stand, und über die API gehen davon höchstens 10 je Stunde und 30 je Tag. Im Dashboard gibt es diese Grenze nicht. Jeder Schlüssel lässt sich jederzeit widerrufen und ist dann sofort ungültig.

Ein typischer Ablauf

Der Schlüssel gehört in den Authorization-Header, nie in eine Adresse. Den Schlüssel legst du vorher als Umgebungsvariable ab. So listest du deine Codes auf und änderst das Ziel eines Codes:

curl -H "Authorization: Bearer $SAMEQR_API_KEY" https://sameqr.com/api/v1/qr

curl -X PATCH https://sameqr.com/api/v1/qr/<id> \
  -H "Authorization: Bearer $SAMEQR_API_KEY" -H "Content-Type: application/json" \
  -H "X-Confirm: <stand>" \
  -d '{"targetUrl":"https://example.com/karte-neu"}'

Den Wert für X-Confirm, den Stand, liefert die Leseanfrage auf /api/v1/qr/<id>. Geändert wird nur, was du mitschickst. Wer sichergehen will, dass niemand zwischendurch denselben Code geändert hat, schickt den gelesenen Stand als _rev mit. Hat sich etwas geändert, wird nichts überschrieben, und die Antwort enthält den aktuellen Stand. Fehler kommen immer im selben Format zurück, mit Status, Code und einer verständlichen Meldung.

Grenzen und gute Praxis

Je Schlüssel gehen höchstens 120 Anfragen pro Minute. Dazu kommt eine Grenze je Stunde, die vom Tarif abhängt: 60 im kostenlosen Tarif, 300 in Start, 1.000 in Pro und 5.000 in Agentur. Die Grenzen fangen Fehler ab, etwa ein Skript in einer Endlosschleife, und stören ehrliche Nutzung nicht.

• Erst mit einem Leseschlüssel ausprobieren, dann schreiben.
• Neue Abläufe an einem einzelnen Code testen und mit dem Handy scannen.
• Löschen vermeiden, wo ein neues Ziel reicht. Gelöschte Codes und ihre Kurzlinks kommen nicht zurück.
• Für jedes Programm einen eigenen Schlüssel anlegen und ihn in einem Passwortmanager oder einer Umgebungsvariable halten.

Fazit: Warum Same-QR

Same-QR gibt dir die API nicht als teures Extra, sondern in jedem Tarif, mit denselben Funktionen wie im Dashboard: Codes, Statistik, Speisekarten, Gastseiten, Labels und Projekte. Dazu kommen klare Rechte je Schlüssel, ehrliche Fehlermeldungen und eine nächtliche Prüfung aller Ziele, die dir per Mail meldet, wenn eines nicht erreichbar ist.

Leg gleich los: Registriere dich kostenlos auf sameqr.com, zwei dynamische QR-Codes sind dauerhaft gratis. API, CLI und MCP-Server gibt es in jedem Tarif, die Dokumentation steht auf sameqr.com/entwickler.

Häufig gestellte Fragen