API pārskats

qr3.app REST API ir pieejams adresē https://qr3.app/v1/.

Versiju pārvaldība

API versiju pārvaldība tiek nodrošināta, izmantojot URL ceļu (/v1/). Būtiskas izmaiņas (breaking changes) vienmēr rada jaunu galveno versiju.

Pieprasījuma formāts

Content-Type: application/json
Autentifikācija: Authorization: Bearer qr3_sk_xxx
Idempotence: POST pieprasījumus var padarīt idempotentus, izmantojot galveni Idempotency-Key: <uuid>

Atbildes formāts

Visas veiksmīgās atbildes atgriež JSON:

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

Saraksta atbildēm vienmēr ir meta.pagination struktūra:

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

Kļūdu formāts (RFC 7807)

Visas kļūdas atbilst standartam RFC 7807 Problem Details:

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

Statuss	Kļūdas veids	Apraksts
400	`bad-request`	Nederīgs JSON vai trūkstoši obligātie lauki
401	`authentication`	Trūkstoša vai nederīga API atslēga
403	`forbidden`	Nav piekļuves tiesību šim resursam
404	`not-found`	Resurss nav atrasts
409	`conflict`	Idempotency-Key konflikts
422	`validation-error`	Ievades datu kļūda (ar `errors` masīvu)
429	`rate-limited`	Pārsniegts pieprasījumu ierobežojums (rate limit)
500	`internal`	Iekšēja servera kļūda

Lapošana

API izmanto uz kursoru balstītu lapošanu:

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

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

Pieprasījumu ierobežojumi (Rate Limits)

Katra atbilde satur:

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

Interaktīvā API atsauce

Pārbaudiet visus galapunktus tieši pārlūkprogrammā:

→ Atvērt API atsauci (Scalar, interaktīva, ar Try-it-out iespēju)

DPP-Contract (Phase 4a)

Akumulatoru darba plūsmai (workflow) qr3.app papildus dokumentē šos maršrutus:

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=...

Vadības paneļa (dashboard) lapas, SDKs un šī dokumentācija izmanto vienu un to pašu datu līgumu (data contract).