Ħarsa Ġenerali tal-API

Ħarsa Ġenerali tal-API

L-API REST ta’ qr3.app hija aċċessibbli fuq https://qr3.app/v1/.

Verżjonar

L-API hija verżjonata permezz tal-mogħdija tal-URL (/v1/). Bidliet li jikkawżaw ksur (breaking changes) dejjem iwasslu għal verżjoni ewlenija ġdida.

Format tat-Talba

• Content-Type: application/json
• Awtentikazzjoni: Authorization: Bearer qr3_sk_xxx
• Idempotenza: It-talbiet POST jistgħu jsiru idempotenti bl-użu ta’ Idempotency-Key: <uuid>

Format tar-Rispons

Ir-risponsi kollha li jirnexxu jirritornaw JSON:

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

Ir-risponsi tal-lista dejjem għandhom struttura ta’ meta.pagination:

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

Format tal-Iżbalji (RFC 7807)

L-iżbalji kollha jsegwu l-istandard 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"
}

Status	Tip ta’ Żball	Deskrizzjoni
400	bad-request	JSON invalidu jew oqsma obbligatorji neqsin
401	authentication	API key nieqes jew invalidu
403	forbidden	M’hemmx permess għal din ir-riżorsa
404	not-found	Ir-riżorsa ma nstabitx
409	conflict	Konflitt tal-Idempotency-Key
422	validation-error	Dejta tal-input mhux valida (b’array ta’ errors)
429	rate-limited	Limitu tar-rata maqbuż
500	internal	Żball intern tas-server

Paġinazzjoni

L-API tuża paġinazzjoni bbażata fuq cursor:

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

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

Note

Il-cursor huwa l-ID tal-aħħar oġġett fuq il-paġna kurrenti.

Limiti tar-Rata

Kull rispons fih:

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

Referenza tal-API Interattiva

Ittestja l-endpoints kollha direttament fil-browser:

→ Iftaħ ir-Referenza tal-API (Scalar, interattiv, b’Try-it-out)

Kuntratt DPP (Fażi 4a)

Għall-fluss tax-xogħol tal-batterija, qr3.app jiddokumenta wkoll dawn ir-rotot:

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

Il-paġni tad-dashboard, l-SDKs u din id-dokumentazzjoni jużaw l-istess kuntratt tad-dejta.