QR-Codes API

Übersicht

Die Codes-API ist das Herzstück von qr3.app. Damit erstellst, aktualisierst und löschst du dynamische und statische QR-Codes.

Basis-URL: https://qr3.app/v1/codes

Verbindlicher REST-Vertrag

Der folgende Vertrag ist für alle Clients maßgeblich:

POST /v1/codes akzeptiert nur die Typen url, vcard, wifi, email, sms und location. Die Felder sind flach: url; mindestens vcard_first_name oder vcard_last_name; wifi_ssid; email_to; sms_phone; beziehungsweise location_lat und location_lng.
Nur url-Codes können dynamisch sein. Erstellen-Aufrufe dürfen optional expires_at mit einem ISO-8601-Zeitpunkt enthalten; ab_enabled, ab_target_url_b und ab_weight_a (A/B-Destinations) sind für dynamische url-Codes zulässig; redirect_after_expiry gehört nicht zum Erstellen-Vertrag.
GET /v1/codes unterstützt ausschließlich limit, cursor und status (live, paused, flagged, draft).
POST /v1/codes/batch akzeptiert url, vcard und wifi. Das Limit beträgt Free 10, Pro 500 und Business/Agency/Enterprise 1.000 Einträge pro Anfrage. URL-Scans laufen synchron für höchstens 50 URL-Einträge; bei mehr als 50 ist skip_url_scan: true erforderlich.

QR-Code erstellen

`POST /v1/codes`

curl -X POST https://qr3.app/v1/codes \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "url",
    "url": "https://example.com",
    "title": "Mein erster QR-Code",
    "tags": ["marketing", "q1"],
    "is_dynamic": true
  }'

const code = await qr3.codes.create({
  type: 'url',
  url: 'https://example.com',
  title: 'Mein erster QR-Code',
  tags: ['marketing', 'q1'],
  is_dynamic: true,
});

qr3 create https://example.com --title "Mein QR-Code" --tags marketing,q1

Response (HTTP 201):

{
  "data": {
    "id": "qr_a1b2c3d4",
    "short_code": "r7f3Kx",
    "redirect_url": "https://qr3.app/r7f3Kx",
    "image_svg_url": "https://qr3.app/v1/codes/r7f3Kx/qr.svg",
    "image_png_url": "https://qr3.app/v1/codes/r7f3Kx/qr.png",
    "image_pdf_url": "https://qr3.app/v1/codes/r7f3Kx/qr.pdf",
    "image_eps_url": "https://qr3.app/v1/codes/r7f3Kx/qr.eps",
    "type": "url",
    "target_url": "https://example.com",
    "is_dynamic": true,
    "status": "live",
    "tags": ["marketing", "q1"],
    "total_scans": 0,
    "created_at": "2026-03-15T10:00:00.000Z"
  },
  "meta": { "request_id": "req_xyz123" }
}

QR-Code-Typen

Typ	Beschreibung	Pflichtfelder
`url`	Website-URL (dynamisch oder statisch)	`url`
`vcard`	Visitenkarte (vCard 3.0)	`vcard_first_name` oder `vcard_last_name`
`wifi`	WLAN-Konfiguration	`wifi_ssid`
`email`	E-Mail (mailto:)	`email_to`
`sms`	SMS	`sms_phone`
`location`	Standort (geo:)	`location_lat`, `location_lng`

Batch-Erstellung

`POST /v1/codes/batch`

curl -X POST https://qr3.app/v1/codes/batch \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "type": "url", "url": "https://produkt-1.example.com", "tags": ["batch"] },
      { "type": "url", "url": "https://produkt-2.example.com", "tags": ["batch"] },
      { "type": "wifi", "wifi_ssid": "GastWLAN", "wifi_password": "geheim123" }
    ],
    "skip_url_scan": false
  }'

Response (HTTP 201):

{
  "data": {
    "created": [
      { "id": "qr_...", "short_code": "abc123", "redirect_url": "https://qr3.app/abc123" },
      { "id": "qr_...", "short_code": "def456", "redirect_url": "https://qr3.app/def456" },
      { "id": "qr_...", "short_code": "ghi789", "status": "live" }
    ],
    "total": 3,
    "failed": 0
  }
}

QR-Code-Liste

`GET /v1/codes`

curl https://qr3.app/v1/codes?status=live&limit=20 \
  -H "Authorization: Bearer qr3_sk_..."

Query-Parameter:

Parameter	Typ	Standard	Beschreibung
`cursor`	string	—	Cursor für Pagination
`limit`	integer	20	Ergebnisse pro Seite (max. 100)
`status`	string	—	Filter: `live`, `paused`, `flagged`, `draft`

QR-Code abrufen

`GET /v1/codes/:id`

curl https://qr3.app/v1/codes/qr_a1b2c3d4 \
  -H "Authorization: Bearer qr3_sk_..."

QR-Code aktualisieren

`PATCH /v1/codes/:id`

Aktualisierungsvertrag: url darf nur bei einem bestehenden Code mit type: "url" geändert werden und muss mit http:// oder https:// beginnen. Andere Code-Typen dürfen kein Feld url erhalten; ungültige Anfragen liefern 422.

Dynamische QR-Codes ermöglichen es, die Ziel-URL jederzeit zu ändern — ohne den QR-Code neu drucken zu müssen.

curl -X PATCH https://qr3.app/v1/codes/qr_a1b2c3d4 \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://neue-zielseite.example.com", "status": "live" }'

Landingpage & externe Links

Für dynamische url-Codes kannst du is_landing_page: true setzen (beim Erstellen oder per PATCH). Ein Scan zeigt dann eine von qr3 gehostete Seite mit den öffentlichen Dateien und externen Links des Codes, statt weiterzuleiten. Externe Links werden als links-Array übergeben:

{
  "is_landing_page": true,
  "links": [
    { "label": "Datenblatt", "url": "https://example.com/datenblatt.pdf" },
    { "label": "Zertifikat", "url": "https://example.com/zertifikat.pdf" }
  ]
}

0–20 Links pro Code; label ist 1–100 Zeichen; url muss http(s) sein (≤ 2048 Zeichen).
Jede URL wird mit Google Web Risk geprüft — eine unsichere URL liefert 422.
Ist Web Risk beim Speichern nicht erreichbar, wird der Link trotzdem akzeptiert, aber zur erneuten Prüfung vorgemerkt. Ein täglicher Job prüft gespeicherte Links erneut (und sauber eingestufte Links regelmäßig nach) und pausiert den Code automatisch, falls ein Link später als unsicher erkannt wird.
"links": [] löscht alle Links. Siehe den Landingpage-Leitfaden.

QR-Code löschen

`DELETE /v1/codes/:id`

Soft-Delete — der QR-Code wird archiviert, Scan-Daten bleiben erhalten.

curl -X DELETE https://qr3.app/v1/codes/qr_a1b2c3d4 \
  -H "Authorization: Bearer qr3_sk_..."

QR-Bilder herunterladen

Alle Bildformate sind öffentlich zugänglich — keine Authentifizierung erforderlich.

Format	URL	Verwendung
SVG (Vektor)	`/v1/codes/:code/qr.svg`	Web, Scaling, Digital
PNG (Raster)	`/v1/codes/:code/qr.png`	E-Mail, Präsentationen
PDF (Vektor)	`/v1/codes/:code/qr.pdf`	Standard: quadratisch (nur der Code); `?format=a4` für ein Druckblatt
EPS (Vektor)	`/v1/codes/:code/qr.eps`	Profi-Druck-Workflows (Adobe, Druckereien)

Optional: ?size=N — Modulgröße in Pixeln (2–20, Standard: 4) für SVG, PNG und EPS. Das PDF nutzt eine feste Modulgröße.

Nur PDF: ?format=a4|square — Seitenformat (Standard: square — nur Code + Quiet Zone, kein A4-Weißraum; a4 für ein druckfertiges A4-Blatt)

# SVG für Web
curl https://qr3.app/v1/codes/r7f3Kx/qr.svg

# PNG in hoher Auflösung
curl https://qr3.app/v1/codes/r7f3Kx/qr.png?size=10 -o qr-hires.png

# Kompaktes PDF (nur der Code, Standard)
curl https://qr3.app/v1/codes/r7f3Kx/qr.pdf -o qr.pdf

# Druckfertiges A4-Blatt
curl "https://qr3.app/v1/codes/r7f3Kx/qr.pdf?format=a4" -o qr-a4.pdf

Kommentare

Kommentare ermöglichen Feedback-Schleifen zwischen Agenturen und Kunden.

`GET /v1/codes/:id/comments`

`POST /v1/codes/:id/comments`

`PATCH /v1/codes/:id/comments/:commentId`

`DELETE /v1/codes/:id/comments/:commentId`

Dashboard-Kommentare werden dem erstellenden Nutzer zugeordnet (author_id); Kommentare über reine API-Keys bleiben unattribuiert (author_id: null). Löschen darf einen Kommentar nur der Autor selbst oder ein org_admin/ws_admin — reine API-Keys können nur unattribuierte API-Kommentare löschen.

# Kommentar hinzufügen
curl -X POST https://qr3.app/v1/codes/qr_a1b2c3d4/comments \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "body": "QR-Code bitte auf grünen Hintergrund abstimmen.", "author_name": "Max Müller" }'

# Offene Kommentare auflisten
curl "https://qr3.app/v1/codes/qr_a1b2c3d4/comments?resolved=false" \
  -H "Authorization: Bearer qr3_sk_..."

# Kommentar als erledigt markieren
curl -X PATCH https://qr3.app/v1/codes/qr_a1b2c3d4/comments/cmt_xyz \
  -H "Authorization: Bearer qr3_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "resolved": true }'