API Coduri QR

Contract REST obligatoriu

Următorul contract se aplică tuturor clienților:

POST /v1/codes acceptă numai tipurile url, vcard, wifi, email, sms și location. Câmpurile sunt plate: url; cel puțin vcard_first_name sau vcard_last_name; wifi_ssid; email_to; sms_phone; sau ambele location_lat și location_lng.
Doar codurile url pot fi dinamice. Cererile de creare pot include opțional expires_at ca marcaj temporal ISO 8601; ab_enabled, ab_target_url_b și ab_weight_a (destinații A/B) sunt acceptate pentru coduri url dinamice; redirect_after_expiry nu face parte din contractul de creare.
GET /v1/codes acceptă numai limit, cursor și status (live, paused, flagged, draft).
POST /v1/codes/batch acceptă url, vcard și wifi. Limita este de 10 pentru Free, 500 pentru Pro și 1.000 de înregistrări pentru Business/Agency/Enterprise per cerere. Scanările URL rulează sincron pentru cel mult 50 de elemente URL; peste 50 este necesar skip_url_scan: true.

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`

Creare în lot (Batch)

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

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`

Update contract: url may be changed only for an existing type: "url" code, and its value must use http:// or https://. Other code types must not receive url; invalid requests return 422.

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