Forbhreathnú ar an API

Forbhreathnú ar an API

Tá REST API qr3.app ar fáil ag https://qr3.app/v1/.

Leaganú

Déantar leaganú ar an API tríd an gcosán URL (/v1/). Bíonn mórleagan nua i gcónaí mar thoradh ar athruithe briste (breaking changes).

Formáid an Iarratais

• Content-Type: application/json
• Fíordheimhniú: Authorization: Bearer qr3_sk_xxx
• Idéampóideacht: Is féidir iarratais POST a dhéanamh idéampóideach le Idempotency-Key: <uuid>

Formáid an Fhreagra

Seolann gach freagra rathúil JSON ar ais:

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

Bíonn struchtúr meta.pagination i gcónaí ag freagraí liosta:

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

Formáid Earráide (RFC 7807)

Leanann gach earráid an caighdeán 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	Cineál Earráide	Cur Síos
400	bad-request	JSON neamhbhailí nó réimsí riachtanacha ar iarraidh
401	authentication	API-Key ar iarraidh nó neamhbhailí
403	forbidden	Gan cead rochtana ar an acmhainn seo
404	not-found	Acmhainn nár aimsíodh
409	conflict	Coimhlint Idempotency-Key
422	validation-error	Sonraí ionchuir lochtach (le h-eagar errors)
429	rate-limited	Teorainn ráta sáraithe
500	internal	Earráid inmheánach fhreastalaí

Leathanachú

Úsáideann an API leathanachú bunaithe ar chúrsóir (cursor-based pagination):

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

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

Note

Is é an cúrsóir ID an ruda dheireanaigh ar an leathanach reatha.

Teorainneacha Ráta

Bíonn an méid seo a leanas i ngach freagra:

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

Tagairt API Idirghníomhach

Tástáil gach críochphointe go díreach sa bhrabhsálaí:

→ Oscail Tagairt an API (Scalar, idirghníomhach, le Try-it-out)

DPP-Contract (Céim 4a)

Maidir leis an sreabhadh oibre ceallraí, déanann qr3.app na ródanna seo a dhoiciméadú freisin:

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

Úsáideann leathanaigh an deais, SDKs agus an doiciméadú seo an conradh sonraí céanna.