API Coduri QR

Prezentare generală

API-ul pentru coduri este inima qr3.app. Cu acesta poți crea, actualiza și șterge coduri QR dinamice și statice.

URL de bază: https://qr3.app/v1/codes

Creare cod QR

`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

Răspuns (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" }
}

Tipuri de coduri QR

Tip	Descriere	Câmpuri obligatorii
`url`	URL site web (dinamic sau static)	`url`
`vcard`	Carte de vizită (vCard 3.0)	`vcard_first_name` sau `vcard_last_name`
`wifi`	Configurație Wi-Fi	`wifi_ssid`
`email`	E-mail (mailto:)	`email_to`
`sms`	SMS	`sms_phone`
`location`	Locație (geo:)	`location_lat`, `location_lng`

Testare A/B

Testează două URL-uri de destinație diferite cu redirecționare ponderată:

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

Expirare (Expiry)

Codurile QR pot expira automat:

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

După expirare, se va redirecționa fie către redirect_after_expiry, fie se va afișa o pagină 410.

Creare în lot (Batch)

`POST /v1/codes/batch`

Creează până la 1.000 de coduri QR într-o singură cerere. Ideal pentru aplicații în masă.

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

Răspuns (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
  }
}

Listă coduri QR

`GET /v1/codes`

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

Parametri Query:

Parametru	Tip	Implicit	Descriere
`cursor`	string	—	Cursor pentru paginare
`limit`	integer	20	Rezultate pe pagină (max. 100)
`status`	string	—	Filtru: `live`, `paused`, `flagged`, `draft`

Obținere cod QR

`GET /v1/codes/:id`

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

Actualizare cod QR

`PATCH /v1/codes/:id`

Codurile QR dinamice permit modificarea URL-ului de destinație în orice moment — fără a fi necesară retipărirea codului QR.

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

Pagini de destinație și linkuri externe

Pentru codurile url dinamice, poți seta is_landing_page: true (la creare sau prin PATCH). O scanare va afișa atunci o pagină găzduită de qr3 cu fișierele publice și linkurile externe ale codului, în loc să redirecționeze. Linkurile externe sunt transmise ca un tablou (array) links:

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

0–20 de linkuri per cod; label are între 1 și 100 de caractere; url trebuie să fie http(s) (≤ 2048 de caractere).
Fiecare URL este verificat cu Google Web Risk — un URL nesigur returnează 422.
Dacă Web Risk nu este accesibil în momentul salvării, linkul este totuși acceptat, dar este marcat pentru o nouă verificare. Un job zilnic verifică din nou linkurile salvate (și periodic pe cele clasificate ca sigure) și suspendă automat codul dacă un link este detectat ulterior ca fiind nesigur.
"links": [] șterge toate linkurile. Vezi ghidul pentru pagini de destinație.

Ștergere cod QR

`DELETE /v1/codes/:id`

Ștergere soft (Soft-Delete) — codul QR este arhivat, datele de scanare sunt păstrate.

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

Descărcare imagini QR

Toate formatele de imagine sunt accesibile public — nu este necesară autentificarea.

Format	URL	Utilizare
SVG (vectorial)	`/v1/codes/:code/qr.svg`	Web, scalare, digital
PNG (raster)	`/v1/codes/:code/qr.png`	E-mail, prezentări
PDF (vectorial)	`/v1/codes/:code/qr.pdf`	Implicit: pătrat (doar codul); `?format=a4` pentru o foaie de tipărit
EPS (vectorial)	`/v1/codes/:code/qr.eps`	Fluxuri de lucru profesionale de tipărire (Adobe, tipografii)

Opțional: ?size=N — dimensiunea modulului în pixeli (2–20, implicit: 4) pentru SVG, PNG și EPS. PDF-ul utilizează o dimensiune fixă a modulului.

Doar PDF: ?format=a4|square — formatul paginii (implicit: square — doar codul + zona de liniște (quiet zone), fără spațiu alb A4; a4 pentru o foaie A4 gata de tipărit)

# 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

Comentarii

Comentariile permit bucle de feedback între agenții și clienți.

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