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",
    "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" }'

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 (Druck)	`/v1/codes/:code/qr.pdf`	Print-ready, A4 oder quadratisch

Optional: ?size=N — Modulgröße in Pixeln (2–20, Standard: 4 für PNG/SVG, 3 für PDF)

Nur PDF: ?format=a4|square — Seitenformat (Standard: a4)

# 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

# Druckfertiges A4-PDF
curl https://qr3.app/v1/codes/r7f3Kx/qr.pdf -o qr-druck.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 }'