Alles über die API — auch skriptbar
Codes anlegen, Ziele aktualisieren, Statistiken und Monitoring-Status abfragen — alles, was das Dashboard kann, kann auch Ihre eigene Anwendung. Verfügbar ab dem Professional-Tarif.
Bearer-Token
Jede Anfrage wird per Authorization: Bearer-Header authentifiziert. API-Schlüssel legen Sie unter Integrationen in Ihrem Konto an (nyqra.de/app/integrationen) — der volle Schlüssel wird nur einmal direkt nach dem Anlegen angezeigt.
curl https://nyqra.de/api/qr-codes \
-H "Authorization: Bearer nyqra_live_ihr_schluessel"Der Kernfall: PUT auf einen bestehenden Code
curl -X PUT https://nyqra.de/api/qr-codes/123 \
-H "Authorization: Bearer nyqra_live_ihr_schluessel" \
-H "Content-Type: application/json" \
-d '{
"target_url": "https://ihre-seite.de/sommer-2026"
}'await fetch("https://nyqra.de/api/qr-codes/123", {
method: "PUT",
headers: {
"Authorization": `Bearer ${process.env.NYQRA_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({ target_url: "https://ihre-seite.de/sommer-2026" })
});Die Code-ID (hier 123) ist die numerische ID aus der Antwort von GET /api/qr-codes bzw. POST /api/qr-codes — nicht der sechsstellige Kurzcode selbst.
Für API-Schlüssel geöffnete Endpunkte
Nur diese Routen akzeptieren einen API-Schlüssel. Benutzerverwaltung, Teams, Einladungen und Organisationseinstellungen bleiben bewusst ausschließlich per Login erreichbar.
| Methode | Pfad | Zweck | Scope |
|---|---|---|---|
| GET | /api/qr-codes | Alle Codes auflisten | qr_codes:read |
| POST | /api/qr-codes | Neuen Code anlegen | qr_codes:write |
| GET | /api/qr-codes/{id} | Einzelnen Code abrufen | qr_codes:read |
| PUT | /api/qr-codes/{id} | Ziel, Titel oder Status ändern | qr_codes:write |
| GET | /api/qr-codes/{id}/history | Versionshistorie abrufen | versions:read |
| GET | /api/qr-codes/{id}/health | Aktuellen Monitoring-Status abrufen | monitoring:read |
| POST | /api/qr-codes/{id}/check-now | Sofortige Zielprüfung anstoßen | monitoring:check |
| GET | /api/qr-codes/{id}/analytics | Scan-Statistiken zu einem Code | analytics:read |
| GET | /api/analytics/* | Aggregierte Scan-Statistiken | analytics:read |
| GET | /api/organization | Organisationsstammdaten lesend | organization:read |
Ein Schlüssel erhält beim Anlegen genau die Scopes, die die erstellende Rolle selbst besitzt — keine Rechte-Eskalation möglich. Nur Owner und Admin dürfen API-Schlüssel und Webhooks verwalten.
Damit ein Skript nie das Dashboard ausbremst
| Ebene | Lesend (GET) | Schreibend |
|---|---|---|
| pro API-Schlüssel | 300 / Minute | 60 / Minute |
| pro Organisation (alle Schlüssel zusammen) | 1.000 / Minute | 200 / Minute |
Bei Überschreitung: HTTP 429 mit Retry-After-Header.
Live benachrichtigt werden
Abonnieren Sie reale Ereignisse aus Ihrem QR-Code-Bestand, statt regelmäßig abzufragen — jede Zustellung ist per HMAC-SHA256 signiert.
| Ereignis | Auslöser |
|---|---|
| qr_code.created | Neuer Code angelegt |
| qr_code.updated | Code geändert (nur bei echter Änderung) |
| qr_code.deleted | Code archiviert/gelöscht |
| qr_code.rolled_back | Auf eine frühere Version zurückgesetzt |
| redirect_rule.created | Neue Smart-Redirect-Regel |
| redirect_rule.updated | Smart-Redirect-Regel geändert |
| monitoring.healthy | Ziel wieder erreichbar (ohne vorherigen Ausfall) |
| monitoring.warning | Ziel liefert eine Warnung (z. B. langsame Antwort) |
| monitoring.offline | Ziel nicht erreichbar |
| monitoring.recovered | Ziel nach einem Ausfall wieder erreichbar |
| api_key.revoked | Ein API-Schlüssel wurde widerrufen |
analytics.threshold_reached ist beim Anlegen eines Webhooks bereits auswählbar, wird aber aktuell von keinem Schwellenwert-Mechanismus ausgelöst — es gibt bislang kein Alarmmodell für Scan-Zahlen. Ehrlich vorbereitet, aber noch ungenutzt.
{
"event_id": "8b6e...-uuid",
"event_type": "qr_code.created",
"created_at": "2026-07-28T12:00:00.000Z",
"tenant_id": "5c2f...-uuid",
"resource_type": "qr_code",
"resource_id": "123",
"api_version": "2026-01-01",
"data": { "code": "A1B2C3", "title": "…", "target_url": "…" }
}const crypto = require("crypto");
function isValidNyqraWebhook(secret, rawBody, timestamp, signatureHeader) {
const ageSeconds = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp));
if (ageSeconds > 300) return false; // Replay-Schutz: 5 Minuten Toleranz
const expected = crypto.createHmac("sha256", secret)
.update(`${timestamp}.${rawBody}`).digest("hex");
const provided = signatureHeader.replace("sha256=", "");
const a = Buffer.from(expected, "hex");
const b = Buffer.from(provided, "hex");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
// Header: X-NYQRA-Signature ("sha256=…"), X-NYQRA-Timestamp, X-NYQRA-Event-IdNach 5 erfolglosen Zustellversuchen (sofort, nach 1 Min., 5 Min., 30 Min., 2 Std.) wird der Webhook automatisch deaktiviert, nicht gelöscht — reaktivieren Sie ihn nach Behebung der Störung manuell.
Aktuell reines REST
Es gibt derzeit keine offiziellen Client-Bibliotheken — die API ist über jeden HTTP-Client nutzbar (curl, fetch, Postman, …). Ehrlich gesagt, statt einen Fahrplan zu versprechen, den es noch nicht gibt.