QR-Code per REST-API anlegen: Anleitung mit curl-Beispielen

Schritt 1: Schlüssel anlegen

Im Dashboard unter Konto, Abschnitt „Zugang für CLI, Skripte und Agenten“, legst du einen Schlüssel an. Für die ersten Versuche reicht „nur lesen“. Wähle eine kurze Laufzeit, etwa 30 Tage. Der Schlüssel beginnt mit sqr_live_ und wird nur einmal angezeigt. Leg ihn als Umgebungsvariable ab, damit er nicht in deiner Shell-Historie landet, zum Beispiel über deinen Passwortmanager.

Schritt 2: Die erste Anfrage

Die API liegt unter https://sameqr.com/api/v1. Der Schlüssel gehört in den Authorization-Header, nie in die Adresse:

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

Die erste Anfrage zeigt dein Konto, deinen Tarif und deine Grenzen, die zweite deine Codes mit Kennung, Name, Ziel, Labels, Scan-Zahl und dem Stand _rev.

Schritt 3: Einen Code anlegen

Zum Anlegen brauchst du einen zweiten Schlüssel mit „lesen + schreiben“. Mit einem Leseschlüssel antwortet die API auf ändernde Anfragen mit 403 und dem Code NUR_LESEN. Ein neuer Code braucht mindestens einen Namen und ein Ziel:

curl -X POST https://sameqr.com/api/v1/qr \
  -H "Authorization: Bearer $SAMEQR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Speisekarte","targetUrl":"https://example.com/karte"}'

Scanne den neuen Code mit dem Handy, bevor du weitermachst. Zum Anlegen muss deine Mailadresse bestätigt sein, und der Code zählt gegen das Kontingent deines Tarifs.

Schritt 4: Das Ziel ändern

Zieländerungen sind besonders geschützt. Du brauchst einen Schlüssel „voll“ und schickst den aktuellen Stand des Codes als Kopfzeile X-Confirm mit. Den Stand liefert die Leseanfrage:

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

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"}'

Geändert werden nur die mitgeschickten Felder. Weicht der Stand ab, weil jemand den Code inzwischen geändert hat, wird nichts überschrieben. Über die API gehen höchstens 10 Zieländerungen je Stunde und 30 je Tag, im Dashboard gibt es diese Grenze nicht. Im kostenlosen Tarif ist die Zahl der Zieländerungen je Code begrenzt.

Schritt 5: Fehler und Grenzen verstehen

Fehler kommen immer in derselben Form zurück: ein Objekt error mit status, code und message. Werte sie in deinem Programm aus, statt einfach weiterzumachen.

• 401: Schlüssel fehlt, ist falsch, abgelaufen oder widerrufen.
• 403: Dem Schlüssel fehlt die nötige Stufe, oder dein Tarif erlaubt die Aktion nicht.
• 400 mit BESTAETIGUNG_FEHLT: Für Zieländerung, Offline oder Löschen fehlt X-Confirm mit dem aktuellen Stand.
• 409: Jemand hat den Code zwischendurch geändert.
• 429: Zu viele Anfragen. Je Schlüssel gehen 120 pro Minute, je Stunde 60 im kostenlosen Tarif, 300 in Start, 1.000 in Pro und 5.000 in Agentur.

Alle Anfragen beschreibt /api/v1/openapi.json, die Anleitung steht auf sameqr.com/entwickler.

Fazit: Warum Same-QR

Die REST-API von Same-QR ist aufgeräumt, gut dokumentiert und in jedem Tarif dabei. Sie kann alles, was das Dashboard kann, schützt gedruckte Codes mit Bestätigung und Grenzen vor versehentlichen Zieländerungen, erlaubt Schlüssel in drei Stufen und sie antwortet mit Fehlern, die man versteht.

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