QR-Code erstellen

Diese Seite ist der Basis-Guide für QR Vello. Sie erklärt, wie du QR-Codes im Dashboard erstellst, welche Code-Typen node-qr unterstützt, wie dynamische Codes funktionieren und welche API-Fläche für externe Integrationen stabil ist.

Dashboard-Flow

Öffne /qr/codes und klicke auf "Create" beziehungsweise "Neuer QR-Code". Der Erstellprozess besteht aus sechs fachlichen Schritten.

1. Typ wählen: statisch oder dynamisch.
2. QR-Art wählen: URL, vCard, WLAN, Text, E-Mail, SMS, Telefon, Geo, Event, PDF oder Landing Page.
3. Inhalt ausfüllen: Ziel-URL, Kontaktdaten, WLAN-Daten oder den jeweiligen Payload.
4. Design festlegen: Farben, Logo, Module, Eyes, Frame, Error-Correction, Margin.
5. Organisation setzen: Tags, Ordner, Kampagne, Brand Kit und optional Custom Domain.
6. Preflight prüfen: Scanbarkeit, Kontrast, Logo-Größe, Margin und empfohlene Druckgröße.

Statisch oder dynamisch

Für alles, was gedruckt, verteilt oder länger genutzt wird, ist dynamic die sichere Wahl. Du kannst das Ziel ändern, den Code pausieren, eine Custom Domain nutzen und Scans auswerten.

Unterstützte QR-Arten

node-qr unterstützt aktuell diese kind-Werte:

Inhalt und Ziel-URL

Bei dynamischen URL-Codes ist targetUrl die steuerbare Zieladresse. Der gedruckte QR-Code bleibt gleich, während du targetUrl später ändern kannst.

Wichtig:

• customSlug kann einen gewünschten Short-Slug anfragen.
• Ein belegter Slug führt zu einem Konflikt, nicht zu einer stillen Änderung.
• folderId, campaignId und tags strukturieren Codes für Reporting.
• customDomainId bindet einen Code an eine aktive Custom Domain.

Design

Das Design ist Teil des QR-Code-Objekts. Unterstützt werden:

• foreground und background
• transparente Hintergründe
• lineare oder radiale Gradients
• Logos mit Größe, Padding, Position, Border und Hintergrundmodus
• Built-in Logos wie WhatsApp, Instagram, TikTok, Facebook, X, LinkedIn, YouTube, E-Mail, Telefon oder URL
• dotStyle: square, rounded, dots, classy, extra-rounded, mosaic, vertical-lines, horizontal-lines, cross, diamond
• eye.outerStyle: square, rounded, circle, leaf, shield
• eye.innerStyle: square, dot, star, diamond
• frame: none, rounded, speech, banner
• errorCorrection: L, M, Q, H
• margin

Für QR-Codes mit Logo ist H meistens der robusteste Error-Correction-Wert. Der Preflight zeigt Warnungen, wenn Logo, Kontrast oder Margin die Scanbarkeit gefährden.

Brand Kit und Auto-Sync

Ein QR-Code kann mit einem Brand Kit verbunden werden:

• brandKitId weist ein Brand Kit zu.
• brandAutoSync hält Felder automatisch mit dem Brand Kit synchron.
• inheritedFromBrand zeigt, welche Felder aus dem Brand Kit stammen.
• brandUpdateAvailable signalisiert, dass ein verknüpftes Brand Kit neuer ist.

Das ist wichtig für Agenturen, Filialstrukturen und Teams, die viele Codes mit konstanter Markenlogik erzeugen.

Preflight

Preflight ist der Qualitätscheck vor Druck oder Livegang. Er prüft unter anderem:

Der Check liefert außerdem empfohlene Druckgrößen für Use Cases wie Visitenkarte, Produktlabel, Flyer, Wand-A4, A3/A2, Poster und Billboard.

Nach dem Erstellen

Nach dem Speichern bekommst du:

• id, version, status
• shortSlug, publicUrl, shortUrl
• Payload-Zusammenfassung und Ziel
• Style-Zusammenfassung
• Organisation mit Tags, Ordner, Kampagne und Custom Domain
• Preflight-Status
• Action-Flags wie canEdit, canArchive, canPause, canDownload, canRollback

Versionen und Rollback

Jede Änderung erhöht die Version. Die Detailseite unterstützt:

• Versionshistorie,
• Diff zwischen alter Version und aktuellem Stand,
• Rollback auf eine frühere Version,
• Duplizieren mit Overrides.

Nutze Rollback, wenn ein Ziel, Design oder Payload versehentlich geändert wurde. Nutze Duplizieren, wenn du eine Kampagne mit ähnlichen Codes aufbauen willst.

Status und Aktionen

Verfügbare Aktionen im Dashboard:

• pausieren und aktivieren,
• archivieren und wiederherstellen,
• duplizieren,
• blockieren und entblocken,
• löschen, wenn die Berechtigung und Policy es erlauben,
• Render als PNG, SVG oder PDF herunterladen.

API: Public v1

Die öffentliche v1-Fläche ist bewusst stabil und eng:

Beispiel: dynamischen URL-Code erstellen

curl -X POST https://api.qr-vello.com/v1/qr-codes \
  -H "Authorization: Bearer qrv_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "dynamic",
    "kind": "url",
    "title": "Store Mainz",
    "payload": {
      "kind": "url",
      "url": "https://example.com/mainz"
    },
    "targetUrl": "https://example.com/mainz",
    "customSlug": "store-mainz",
    "tags": ["retail", "mainz"],
    "style": {
      "foreground": "#111827",
      "background": "#F9FAFB",

Beispiel: vCard-Code

{
  "type": "static",
  "kind": "vcard",
  "title": "Niclas Pilz",
  "payload": {
    "kind": "vcard",
    "firstName": "Niclas",
    "lastName": "Pilz",
    "organization": "QR Vello",
    "title": "Founder"

Dashboard API

Das Dashboard nutzt zusätzlich umfangreiche node-qr-Routen, etwa:

• POST /qr-codes/preview für Render-Preview ohne gespeicherten Code.
• POST /qr-codes/preflight für Preflight vor dem Speichern.
• GET /qr-codes/overview für KPI-Strip, Facets und Attention Items.
• POST /qr-codes/bulk/actions für Massenaktionen.
• GET /qr-codes/:qrCodeId/versions und Rollback-Routen.
• Scan-Analytics unter /qr-codes/:qrCodeId/scans/....

Diese Routen sind die Dashboard-Fläche. Als externer stabiler Vertrag gilt aktuell die dokumentierte Public API v1.