API kodów QR

Wiążący kontrakt REST

Poniższy kontrakt dotyczy wszystkich klientów:

POST /v1/codes akceptuje wyłącznie typy url, vcard, wifi, email, sms i location. Pola są płaskie: url; co najmniej vcard_first_name lub vcard_last_name; wifi_ssid; email_to; sms_phone; albo oba location_lat i location_lng.
Tylko kody url mogą być dynamiczne. Żądania utworzenia mogą opcjonalnie zawierać expires_at jako znacznik czasu ISO 8601; ab_enabled, ab_target_url_b i ab_weight_a (cele A/B) są dozwolone dla dynamicznych kodów url; redirect_after_expiry nie jest częścią kontraktu tworzenia.
GET /v1/codes obsługuje tylko limit, cursor i status (live, paused, flagged, draft).
POST /v1/codes/batch akceptuje url, vcard i wifi. Limit wynosi 10 dla Free, 500 dla Pro i 1 000 rekordów dla Business/Agency/Enterprise na żądanie. Skanowanie URL działa synchronicznie dla maksymalnie 50 elementów URL; powyżej 50 wymagane jest skip_url_scan: true.

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`

Tworzenie masowe (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
  }'

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`

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.

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