API áttekintés

A qr3.app REST API a https://qr3.app/v1/ címen érhető el.

Verziókezelés

Az API az URL-útvonalon keresztül verziózott (/v1/). A breaking change-ek (visszafelé nem kompatibilis változások) mindig új főverziót eredményeznek.

Kérés formátuma

Content-Type: application/json
Hitelesítés: Authorization: Bearer qr3_sk_xxx
Idempotencia: A POST kérések idempotenssé tehetők az Idempotency-Key: <uuid> fejléccel

Válasz formátuma

Minden sikeres válasz JSON formátumot ad vissza:

{
  "id": "qr_abc123",
  "type": "url",
  "url": "https://example.com",
  "short_url": "https://qr3.app/r7f3Kx",
  "created_at": "2026-03-15T10:00:00.000Z"
}

A listás válaszok mindig tartalmaznak egy meta.pagination struktúrát:

{
  "data": [...],
  "meta": {
    "request_id": "req_xxx",
    "pagination": {
      "has_more": true,
      "next_cursor": "qr_abc",
      "total_count": 142
    }
  }
}

Hibaformátum (RFC 7807)

Minden hiba az RFC 7807 Problem Details szabványt követi:

{
  "type": "https://docs.qr3.app/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "QR code qr_xxx not found",
  "instance": "/v1/codes/qr_xxx"
}

Státusz	Hibatípus	Leírás
400	`bad-request`	Érvénytelen JSON vagy hiányzó kötelező mezők
401	`authentication`	Hiányzó vagy érvénytelen API-kulcs
403	`forbidden`	Nincs jogosultság ehhez az erőforráshoz
404	`not-found`	Az erőforrás nem található
409	`conflict`	Idempotency-Key konfliktus
422	`validation-error`	Hibás bemeneti adatok (egy `errors` tömbbel)
429	`rate-limited`	Sebességkorlát (Rate Limit) túllépve
500	`internal`	Belső szerverhiba

Lapozás

Az API kurzor-alapú lapozást használ:

# Erste Seite
GET /v1/codes?limit=20

# Nächste Seite
GET /v1/codes?limit=20&cursor=qr_lastid

Sebességkorlátok (Rate Limits)

Minden válasz tartalmazza a következőket:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 28
X-RateLimit-Reset: 1742040120

Interaktív API-referencia

Tesztelje az összes végpontot közvetlenül a böngészőben:

→ API-referencia megnyitása (Scalar, interaktív, Try-it-out lehetőséggel)

DPP-Contract (4a. fázis)

Az akkumulátor-munkafolyamathoz (Batterie-Workflow) a qr3.app ezenkívül az alábbi útvonalakat is dokumentálja:

POST /v1/dpp
GET /v1/dpp
GET /v1/dpp/:id
POST /v1/dpp/validate
GET /v1/dpp/:id/qr.svg
GET /v1/dpp/:id/qr.png
GET /v1/dpp/:id/qr.pdf
GET /v1/dpp/:id/qr.eps
GET /01/...
GET /dpp/:gtin/:serial?lot=...

A Dashboard oldalak, az SDK-k és ez a dokumentáció ugyanazt az adatszerződést (data contract) használják.