Entwickler

API- & Integrationsreferenz

Alles, was Sie brauchen, um die Business API aufzurufen, Schlüssel zu verwalten und Webhooks zu empfangen.

Authentifizierung Basis-URL Endpoints API-Schlüssel Berechtigungen Beispiele Scan-Analysen Ordner & Tags Massenerstellung Webhook-Abonnements Webhooks Conversion-Tracking Exporte Tipps & Fehler

Authentifizierung

Die Business API authentifiziert jede Anfrage mit einem API-Schlüssel. Senden Sie ihn im Header X-Api-Key oder als Bearer-Token im Authorization-Header.

Schlüssel beginnen mit dem Präfix qrg_ und werden nur einmal bei der Erstellung angezeigt. Bewahren Sie sie sicher auf – ein Schlüssel lässt sich später nicht erneut abrufen.

Anfragen ohne gültigen Schlüssel liefern 401. Ein Schlüssel ohne die erforderliche Berechtigung erhält 403 mit dem Fehler insufficient_scope. Ressourcen außerhalb Ihres Arbeitsbereichs liefern 404, als gäbe es sie nicht.

Basis-URL

Alle Endpoints der Business API liegen unter dem Präfix /v1.

Ihre QR-Codes listen Sie zum Beispiel unter https://qr-global.com/api/v1/qr-codes auf.

Aufgelöste Basis-URL: https://qr-global.com

Endpoints

Alle Endpoints liegen unter /api/v1 und benötigen einen Schlüssel mit der angegebenen Berechtigung.

Methode	Pfad	Berechtigung	Funktion
GET	/qr-codes	qr:read	QR-Codes auflisten (Filter: type, search, folder_id, tag, archived)
POST	/qr-codes	qr:write	QR-Code erstellen
POST	/qr-codes/bulk	qr:write	Bis zu 100 QR-Codes auf einmal erstellen
GET	/qr-codes/{id}	qr:read	Einen QR-Code abrufen
PUT	/qr-codes/{id}	qr:write	QR-Code, seinen Ordner und seine Tags aktualisieren
DELETE	/qr-codes/{id}	qr:write	QR-Code löschen
GET	/qr-codes/{id}/image	qr:read	Bild rendern (PNG oder SVG)
GET	/qr-codes/{id}/stats	analytics:read	Scan-Statistiken
GET	/qr-codes/{id}/scans	analytics:read	Scan-Protokoll
GET	/folders	qr:read	Ordner auflisten
GET	/tags	qr:read	Tags auflisten
GET	/webhooks	webhooks:manage	Webhook-Abonnements auflisten
POST	/webhooks	webhooks:manage	Ereignisse abonnieren
DELETE	/webhooks/{id}	webhooks:manage	Abonnement beenden

Eine maschinenlesbare Beschreibung (OpenAPI 3.1) für Postman, Codegeneratoren und No-Code-Tools: openapi.json herunterladen

API-Schlüssel

Erstellen und widerrufen Sie Schlüssel auf der Seite „API-Schlüssel“ in Ihrem Dashboard.

Jeder Schlüssel gehört zu Ihrem Arbeitsbereich und übernimmt das Anfragelimit Ihres Tarifs.

Der Widerruf eines Schlüssels wird sofort wirksam.

API-Schlüssel

Berechtigungen (Scopes)

Geben Sie einem Schlüssel beim Erstellen Vollzugriff oder nur die Berechtigungen, die eine Integration braucht. Ein Schlüssel ohne eine Berechtigung erhält 403 mit dem Fehler insufficient_scope und required_scope in der Antwort.

qr:read — QR-Codes lesen: QR-Codes, ihre Bilder, Ordner und Tags auflisten und ansehen.
qr:write — QR-Codes verwalten: QR-Codes erstellen (auch in großen Mengen), bearbeiten, zwischen Ordnern verschieben, mit Tags versehen und löschen.
analytics:read — Analysen lesen: Scan-Statistiken und das Scan-Protokoll jedes QR-Codes.
webhooks:manage — Webhooks verwalten: Endpoints für Ereignisse anmelden und wieder abmelden (Zapier, Make).

Schlüssel, die vor der Einführung der Berechtigungen erstellt wurden, behalten Vollzugriff. Vollzugriff umfasst auch später hinzugefügte Berechtigungen.

Beispiele

curl-Befehle zum Kopieren für den schnellen Einstieg. Ersetzen Sie YOUR_API_KEY durch einen Schlüssel von der Seite „API-Schlüssel“.

QR-Codes auflisten

curl -sS -H "X-Api-Key: YOUR_API_KEY" -H "Accept: application/json" \
  "https://qr-global.com/api/v1/qr-codes"

QR-Code erstellen

Senden Sie QR-Typ und Inhalt – der Server generiert und speichert den Code.

curl -sS -X POST "https://qr-global.com/api/v1/qr-codes" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"url","content":"https://example.com","display_name":"Example link"}'

Bild rendern

Laden Sie eine fertige PNG- oder SVG-Datei — übergeben Sie ?format=png

curl -sS "https://qr-global.com/api/v1/qr-codes/123/image?format=png&size=512" \
  -H "X-Api-Key: YOUR_API_KEY" -o qr.png

# SVG (vector, no size limit on scale):
curl -sS "https://qr-global.com/api/v1/qr-codes/123/image?format=svg" \
  -H "X-Api-Key: YOUR_API_KEY" -o qr.svg

Beispiel-Payload eines Webhooks

{
  "event": "qr.scan.created",
  "timestamp": "2026-04-03T12:00:00+00:00",
  "data": {
    "qr_code_id": 7,
    "qr_code_uuid": "9b2f0c1e-4d4a-4f7e-9a51-2a7c3c1d8e10",
    "type": "url",
    "scan_id": 42,
    "country": "UA",
    "device_type": "mobile",
    "scanned_at": "2026-04-03T12:00:00+00:00"
  }
}

Scan-Analysen

GET /qr-codes/{id}/stats liefert Gesamtwerte, eindeutige Besucher, Top-Länder, Geräte, Browser und Scans pro Tag. GET /qr-codes/{id}/scans liefert das Scan-Protokoll, neueste zuerst, 50 pro Seite (per_page bis 100).

Beide akzeptieren from und to (ein Datum wie 2026-10-01 oder einen vollständigen Zeitstempel) sowie timezone (standardmäßig UTC). Ein Datum ohne Uhrzeit umfasst den ganzen Tag in dieser Zeitzone.

Verfügbar ist nur der Verlaufszeitraum Ihres Tarifs: Ältere Scans werden gelöscht. IP-Adressen und User-Agents von Besuchern werden nie zurückgegeben.

Scan-Statistiken für einen Zeitraum

curl -sS "https://qr-global.com/api/v1/qr-codes/123/stats?from=2026-10-01&to=2026-10-31&timezone=Europe/Kyiv" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

Scan-Protokoll, zweite Seite

curl -sS "https://qr-global.com/api/v1/qr-codes/123/scans?per_page=100&page=2" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

Ordner und Tags

GET /folders und GET /tags listen die Ordner und Tags Ihres Arbeitsbereichs auf. Übergeben Sie folder_id und tags (Tag-Slugs), wenn Sie einen QR-Code erstellen oder aktualisieren: folder_id null nimmt den Code aus seinem Ordner, und tags ersetzt die gesamte Auswahl.

Filtern Sie die QR-Code-Liste mit ?folder_id= oder ?tag=.

QR-Code in einen Ordner verschieben und Tags zuweisen

curl -sS -X PUT "https://qr-global.com/api/v1/qr-codes/123" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "folder_id": 4,
  "tags": [
    "campaign",
    "priority"
  ]
}'

Massenerstellung

POST /qr-codes/bulk erstellt bis zu 100 QR-Codes in einer Anfrage. Dafür ist ein Tarif mit Massenerstellung nötig (wie für den CSV-Import im Dashboard); Ihr Limit aktiver QR-Codes gilt weiterhin.

Jedes Element wird einzeln verarbeitet: Die Antwort führt jedes Element mit dem Status created (und dem neuen Code) oder failed (mit error und errors) auf. Senden Sie nicht den ganzen Stapel erneut, sondern nur die fehlgeschlagenen Elemente.

Zwei QR-Codes erstellen

curl -sS -X POST "https://qr-global.com/api/v1/qr-codes/bulk" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "codes": [
    {
      "type": "url",
      "content": "https://example.com/spring",
      "display_name": "Spring flyer",
      "tags": [
        "campaign"
      ]
    },
    {
      "type": "url",
      "content": "https://example.com/menu",
      "display_name": "Table menu",
      "folder_id": 4
    }
  ]
}'

Webhook-Abonnements (REST hooks)

Zapier, Make und Ihre eigenen Dienste können Ereignisse über die API abonnieren: POST /webhooks mit url und events, zum Beenden DELETE /webhooks/{id}. Es sind dieselben Endpoints, die Sie auf der Seite „Webhooks“ sehen.

Die Antwort auf POST enthält secret, das nur einmal angezeigt wird: Prüfen Sie damit den Header X-Webhook-Signature. Wenn Sie kein eigenes secret (ab 16 Zeichen) senden, generieren wir eines.

Ereignisse: qr.scan.created, subscription.updated, payment.succeeded, lead.captured, rsvp.received, feedback.received, poll.voted. Zum Abonnieren ist ein Tarif mit Webhooks nötig; Beenden funktioniert immer. Ein Arbeitsbereich kann bis zu 25 Endpoints haben.

Scans abonnieren

curl -sS -X POST "https://qr-global.com/api/v1/webhooks" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://hooks.zapier.com/hooks/catch/123/abc/",
  "events": [
    "qr.scan.created"
  ]
}'

Abonnement beenden

curl -sS -X DELETE "https://qr-global.com/api/v1/webhooks/42" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept: application/json"

Webhooks sind im Lite-Tarif verfügbar. Führe ein Upgrade durch, um sie zu aktivieren.

Webhooks

Webhooks senden Ereignisse in Echtzeit an Ihren Endpoint – Sie müssen also nicht abfragen.

Konfigurieren Sie Endpoints auf der Seite „Webhooks“ in Ihrem Dashboard.

Jede Zustellung ist signiert und wird bei Fehlern mit exponentiellem Backoff wiederholt.

Das Scan-Ereignis wird ausgelöst, wenn jemand einen Ihrer QR-Codes scannt.

Prüfen Sie Zustellversuche, Payloads und Antworten im Zustellprotokoll.

Antworten Sie mit einem 2xx-Status, um eine Zustellung zu bestätigen; jeder andere Status gilt als Fehler.

Webhook-Zustellungen

Webhooks sind im Lite-Tarif verfügbar. Führe ein Upgrade durch, um sie zu aktivieren.

Conversion-Tracking

Conversions zeigen einem A/B-Test, welches Ziel Bestellungen oder Anmeldungen bringt, nicht nur Scans. Mit automatischer Optimierung wandert der Traffic zur Variante mit der besten Conversion.

Fügen Sie das Skript in die Seite ein, die Besucher nach dem Abschluss sehen: Bestellbestätigung, Danke- oder Erfolgsseite. Es funktioniert auf jeder Domain und braucht keinen API-Schlüssel.

Snippet

<script src="https://qr-global.com/c.js" async></script>

Jeder Scan hängt an die Ziel-URL einen signierten Parameter qrg_v an, damit die Conversion dem QR-Code und der Variante zugeordnet wird.
Das Skript speichert das Token 30 Tage lang in einem First-Party-Cookie, sodass die Conversion auch zählt, wenn der Besucher vorher andere Seiten aufruft.
Jeder Scan zählt einmal: Ein Neuladen der Danke-Seite fügt keine Conversions hinzu.
Funktioniert für QR-Codes, die auf eine http(s)-Seite weiterleiten.

Exporte

Exportieren Sie Ihre QR-Codes, Scans, Standorte und Aktivitäten als CSV auf der Seite „Exporte“.

Exporte nutzen Ihre Dashboard-Sitzung, keinen API-Schlüssel – öffnen Sie sie, während Sie angemeldet sind.

Exporte

Tipps & häufige Fehler

401 Unauthorized — der API-Schlüssel fehlt oder ist ungültig. Prüfen Sie den Header X-Api-Key.
403 Forbidden — dem Schlüssel fehlt die erforderliche Berechtigung (insufficient_scope) oder Ihr Tarif enthält die Funktion nicht (api_access_required, bulk_not_available, webhooks_not_available).
404 Not Found — die Ressource existiert nicht oder gehört zu einem anderen Arbeitsbereich.
429 Too Many Requests — Sie haben das Minutenlimit Ihres Tarifs erreicht. Warten Sie die im Header Retry-After angegebene Anzahl Sekunden.
Einige Funktionen (z. B. Webhooks) hängen von Ihrem Tarif ab. Führen Sie ein Upgrade durch, wenn ein Endpoint einen Funktionsfehler zurückgibt.
Noch keine Webhook-Zustellungen? Scannen Sie einen Ihrer QR-Codes, um eine auszulösen.
Fehlgeschlagene Webhook-Zustellungen werden automatisch wiederholt; Sie können sie auch manuell im Zustellprotokoll erneut senden.
Teammitglieder handeln innerhalb Ihres Arbeitsbereichs; Schlüssel und Daten sind dem Inhaber des Arbeitsbereichs zugeordnet.

API- & Integrationsreferenz

Authentifizierung

Basis-URL

Endpoints

API-Schlüssel

Berechtigungen (Scopes)

Beispiele

QR-Codes auflisten

QR-Code erstellen

Bild rendern

Beispiel-Payload eines Webhooks

Scan-Analysen

Scan-Statistiken für einen Zeitraum

Scan-Protokoll, zweite Seite

Ordner und Tags

QR-Code in einen Ordner verschieben und Tags zuweisen

Massenerstellung

Zwei QR-Codes erstellen

Webhook-Abonnements (REST hooks)

Scans abonnieren

Abonnement beenden

Webhooks

Conversion-Tracking

Snippet

Exporte

Tipps & häufige Fehler

Nützliche Links