QR-Code API: wie man die Generierung in eine Web-App integriert

Die API von codigo-qr.es hat zwei Tiers.

Öffentlicher Endpoint (kein Konto erforderlich):

`POST /api/v1/qr/render` generiert einen statischen QR und gibt das Bild in base64 zurück. Limit: 50 Anfragen pro Tag pro IP.

Pro-Endpoints (erfordern API key):

| Methode | Pfad | Zweck | |---------|------|-------| | `GET` | `/api/v1/qr` | Alle QR-Codes auflisten | | `POST` | `/api/v1/qr` | Statischen oder dynamischen QR erstellen | | `GET` | `/api/v1/qr/{id}` | Details eines QR-Codes | | `PATCH` | `/api/v1/qr/{id}` | Ziel oder Name aktualisieren | | `DELETE` | `/api/v1/qr/{id}` | QR-Code löschen | | `GET` | `/api/v1/qr/{id}/image` | PNG- oder SVG-Bild herunterladen | | `GET` | `/api/v1/qr/{id}/stats` | Scan-Statistiken |

Alle Pro-Antworten folgen `{ "data": {...}, "error": null }`. Bei einem Fehler ist `data` null und `error` enthält `code` und `message`.

Schritt 1. Erstellen Sie ein Konto auf codigo-qr.es.

Schritt 2. Aktivieren Sie den Pro-Plan. Die vollständige API ist Pro-exklusiv für 5,99€/Monat.

Schritt 3. Gehen Sie zu /panel/konto und klicken Sie auf «API key generieren». Das Token wird einmal angezeigt. Speichern Sie es in einem Passwort-Manager oder als Umgebungsvariable.

Fügen Sie diesen Header jeder Anfrage hinzu:

```bash curl https://codigo-qr.es/api/v1/qr \ -H "Authorization: Bearer cqr_ihr_token" ```

Ist der Key ungültig oder der Plan abgelaufen, antwortet die API mit `401 UNAUTHORIZED` oder `403 PLAN_REQUIRED`. Sie können den Key jederzeit im Dashboard widerrufen; er wird sofort ungültig.

Der öffentliche Endpoint ist der schnellste Weg, die API zu testen oder einfache QR-Codes aus einem Skript zu generieren, ohne sich um Authentifizierung zu kümmern:

```bash curl -X POST https://codigo-qr.es/api/v1/qr/render \ -H "Content-Type: application/json" \ -d '{"value":"https://ihrewebsite.de","format":"png","size":512}' ```

Parameter:

- `value` (Pflicht): der Inhalt des QR-Codes. Kann eine URL, Text, eine E-Mail-Adresse oder WLAN-Daten sein.
• `format`: `"png"` (Standard) oder `"svg"`
• `size`: `256`, `512` (Standard) oder `1024`

Die Antwort enthält das Bild in base64 innerhalb des JSON-Envelopes:

```json { "data": { "image": "iVBORw0KGgo...", "format": "png", "size": 512 }, "error": null } ```

Bei mehr als 50 Anfragen pro Tag von derselben IP erhalten Sie `429 RATE_LIMITED`, wobei der Header `Retry-After` angibt, wann das Limit zurückgesetzt wird.

Ein dynamischer QR-Code kodiert eine feste Kurz-URL (`/r/{slug}`), aber sein tatsächliches Ziel lässt sich jederzeit ändern. Der gedruckte Code bleibt dabei unverändert.

Einen dynamischen QR erstellen:

```bash curl -X POST https://codigo-qr.es/api/v1/qr \ -H "Authorization: Bearer cqr_ihr_token" \ -H "Content-Type: application/json" \ -d '{ "label": "Speisekarte Mai", "type": "url", "value": "https://ihrgaststaette.de/speisekarte-mai", "is_dynamic": true, "tracking_mode": "redirect" }' ```

Ziel ohne Nachdruck ändern:

```bash curl -X PATCH https://codigo-qr.es/api/v1/qr/{id} \ -H "Authorization: Bearer cqr_ihr_token" \ -H "Content-Type: application/json" \ -d '{"destination": "https://ihrgaststaette.de/speisekarte-juni"}' ```

Das Bild des QR-Codes herunterladen:

```bash curl -o mein-qr.png \ "https://codigo-qr.es/api/v1/qr/{id}/image?format=png&size=1024" \ -H "Authorization: Bearer cqr_ihr_token" ```

Scan-Statistiken abrufen:

```bash curl "https://codigo-qr.es/api/v1/qr/{id}/stats?period=30d" \ -H "Authorization: Bearer cqr_ihr_token" ```

Antwort: ```json { "data": { "total": 312, "period": "30d", "by_day": [{"date": "2026-05-01", "count": 18}], "by_country": [{"country": "DE", "count": 240}] }, "error": null } ```

Die API lohnt sich, wenn Volumen oder Automatisierung die manuelle QR-Erstellung im Dashboard unpraktisch machen.

E-Commerce: QR auf Lieferscheinen und Rechnungen

Das ERP-System erstellt die PDF-Rechnung. Mit einem Aufruf von `POST /api/v1/qr` erhält es einen QR-Code, der auf die Tracking-URL der Bestellung zeigt. Ändert sich die URL später, aktualisiert `PATCH /api/v1/qr/{id}` das Ziel, ohne dass irgendetwas neu gedruckt werden muss.

Restaurants: Speisekarte pro Tisch aus dem Kassensystem

Das Kassensystem erstellt beim Schichtbeginn einen QR pro Tisch. Er zeigt auf die Tageskarte, die der Koch im CMS pflegt. Der QR-Code am Tisch ändert sich nie, nur das Ziel dahinter. Kein wöchentliches Neu-Laminieren der Karten.

Veranstaltungen: personalisierte Tickets im großen Stil

Ein Ticketing-System generiert mit `POST /api/v1/qr` einen eindeutigen QR pro Ticket und bettet ihn in das PDF ein. Am Eingang prüft der Scanner die Gültigkeit über `GET /api/v1/qr/{id}`.

Logistik: Pakete mit Sendungsverfolgung

Jedes Paket erhält einen QR, der auf seine Tracking-Seite zeigt. Der Kunde scannt ihn vom Etikett und sieht den Status in Echtzeit. Die Scans landen in `GET /api/v1/qr/{id}/stats`.

Die API wendet Rate-Limits an, um die Verfügbarkeit zu gewährleisten.

Öffentliches Tier (`/api/v1/qr/render`):
• Limit: 50 Anfragen pro Tag pro IP
• Zeitfenster: 24 Stunden
• Keine Registrierung erforderlich

Pro-Tier (Endpoints mit API key):
• Limit: 60 Anfragen pro Minute pro Benutzer
• Kein tägliches Gesamtlimit

Bei Überschreitung antwortet die API mit `429 Too Many Requests` und folgenden Headern:

``` X-RateLimit-Limit: 60 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1747612800 Retry-After: 43 ```

`X-RateLimit-Reset` ist der Unix-Timestamp, zu dem der Zähler zurückgesetzt wird. `Retry-After` gibt die Sekunden bis dahin an.

Siehe die vollständige Dokumentation für alle Parameter und Fehlerantworten.