API kodów QR

Przegląd

API kodów (Codes API) to serce qr3.app. Pozwala na tworzenie, aktualizowanie i usuwanie dynamicznych oraz statycznych kodów QR.

Bazowy URL: https://qr3.app/v1/codes

Tworzenie kodu 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

Odpowiedź (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" }
}

Typy kodów QR

Typ	Opis	Pola wymagane
`url`	Adres URL strony internetowej (dynamiczny lub statyczny)	`url`
`vcard`	Wizytówka (vCard 3.0)	`vcard_first_name` lub `vcard_last_name`
`wifi`	Konfiguracja Wi-Fi	`wifi_ssid`
`email`	E-mail (mailto:)	`email_to`
`sms`	SMS	`sms_phone`
`location`	Lokalizacja (geo:)	`location_lat`, `location_lng`

Testy A/B

Przetestuj dwa różne docelowe adresy URL z przekierowaniem ważonym:

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

Wygaśnięcie (Expiry)

Kody QR mogą wygasać automatycznie:

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

Po wygaśnięciu następuje przekierowanie na adres redirect_after_expiry lub wyświetlana jest strona z błędem 410.

Tworzenie masowe (Batch)

`POST /v1/codes/batch`

Tworzy do 1000 kodów QR w jednym żądaniu. Idealne rozwiązanie do zastosowań masowych.

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

Odpowiedź (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
  }
}

Lista kodów QR

`GET /v1/codes`

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

Parametry zapytania (Query parameters):

Parametr	Typ	Domyślnie	Opis
`cursor`	string	—	Kursor do paginacji
`limit`	integer	20	Wyniki na stronę (maks. 100)
`status`	string	—	Filtr: `live`, `paused`, `flagged`, `draft`

Pobieranie kodu QR

`GET /v1/codes/:id`

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

Aktualizacja kodu QR

`PATCH /v1/codes/:id`

Dynamiczne kody QR umożliwiają zmianę docelowego adresu URL w dowolnym momencie — bez konieczności ponownego drukowania kodu 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" }'

Strona docelowa (Landing page) i linki zewnętrzne

Dla dynamicznych kodów url możesz ustawić is_landing_page: true (podczas tworzenia lub za pomocą PATCH). Zeskanowanie kodu spowoduje wtedy wyświetlenie hostowanej przez qr3 strony z plikami publicznymi i linkami zewnętrznymi przypisanymi do kodu, zamiast bezpośredniego przekierowania. Linki zewnętrzne są przekazywane jako tablica links:

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

Od 0 do 20 linków na kod; label musi mieć od 1 do 100 znaków; url musi zaczynać się od http(s) (≤ 2048 znaków).
Każdy adres URL jest sprawdzany za pomocą Google Web Risk — niebezpieczny adres URL zwraca błąd 422.
Jeśli usługa Web Risk jest niedostępna podczas zapisywania, link zostanie mimo to zaakceptowany, ale zostanie oznaczony do ponownej weryfikacji. Codzienne zadanie ponownie sprawdza zapisane linki (oraz regularnie weryfikuje te wcześniej uznane za bezpieczne) i automatycznie wstrzymuje (pauses) kod, jeśli link zostanie później uznany za niebezpieczny.
"links": [] usuwa wszystkie linki. Zobacz przewodnik po stronach docelowych.

Usuwanie kodu QR

`DELETE /v1/codes/:id`

Soft-delete (miękkie usunięcie) — kod QR zostaje zarchiwizowany, a dane o skanowaniach zostają zachowane.

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

Pobieranie obrazów kodów QR

Wszystkie formaty obrazów są publicznie dostępne — uwierzytelnianie nie jest wymagane.

Format	URL	Zastosowanie
SVG (wektorowy)	`/v1/codes/:code/qr.svg`	Web, skalowanie, cyfrowe
PNG (rastrowy)	`/v1/codes/:code/qr.png`	E-mail, prezentacje
PDF (wektorowy)	`/v1/codes/:code/qr.pdf`	Domyślnie: kwadratowy (tylko kod); `?format=a4` dla arkusza do druku
EPS (wektorowy)	`/v1/codes/:code/qr.eps`	Profesjonalne procesy drukowania (Adobe, drukarnie)

Opcjonalnie: ?size=N — rozmiar modułu w pikselach (2–20, domyślnie: 4) dla SVG, PNG i EPS. PDF korzysta ze stałego rozmiaru modułu.

Tylko PDF: ?format=a4|square — format strony (domyślnie: square — tylko kod + strefa ciszy (quiet zone), bez białego obszaru A4; a4 dla gotowego do druku arkusza 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

# 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

Komentarze

Komentarze umożliwiają wymianę opinii (pętle informacji zwrotnej) między agencjami a klientami.

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