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

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`

A/B-Testing

Teste zwei verschiedene Ziel-URLs mit gewichteter Weiterleitung:

{
  "type": "url",
  "url": "https://version-a.example.com",
  "ab_enabled": true,
  "ab_target_url_b": "https://version-b.example.com",
  "ab_weight_a": 50
}

Ablauf (Expiry)

QR-Codes können automatisch ablaufen:

{
  "type": "url",
  "url": "https://aktionsseite.example.com",
  "expires_at": "2026-12-31T23:59:59Z",
  "redirect_after_expiry": "https://archiv.example.com"
}

Nach Ablauf wird entweder auf redirect_after_expiry weitergeleitet oder eine 410-Seite angezeigt.

Batch-Erstellung

`POST /v1/codes/batch`

Erstellt bis zu 1.000 QR-Codes in einem einzigen Request. Ideal für Massenanwendungen.

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`

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`

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