Επισκόπηση API

Το REST API του qr3.app είναι προσβάσιμο στη διεύθυνση https://qr3.app/v1/.

Έκδοση

Το API διαθέτει έκδοση μέσω της διαδρομής URL (/v1/). Οι αλλαγές που προκαλούν ασυμβατότητα (breaking changes) οδηγούν πάντα σε μια νέα κύρια έκδοση.

Μορφή αιτήματος

Content-Type: application/json
Ταυτοποίηση: Authorization: Bearer qr3_sk_xxx
Idempotency (Ισοδυναμία): Τα αιτήματα POST μπορούν να γίνουν idempotent με τη χρήση του Idempotency-Key: <uuid>

Μορφή απάντησης

Όλες οι επιτυχείς απαντήσεις επιστρέφουν JSON:

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

Οι απαντήσεις λίστας έχουν πάντα μια δομή meta.pagination:

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

Μορφή σφάλματος (RFC 7807)

Όλα τα σφάλματα ακολουθούν το πρότυπο 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"
}

Κατάσταση	Τύπος σφάλματος	Περιγραφή
400	`bad-request`	Μη έγκυρο JSON ή ελλείποντα υποχρεωτικά πεδία
401	`authentication`	Ελλείπον ή μη έγκυρο API-Key
403	`forbidden`	Δεν υπάρχει εξουσιοδότηση για αυτόν τον πόρο
404	`not-found`	Ο πόρος δεν βρέθηκε
409	`conflict`	Διένεξη Idempotency-Key
422	`validation-error`	Σφάλμα στα δεδομένα εισόδου (με πίνακα `errors`)
429	`rate-limited`	Υπέρβαση ορίου ρυθμού (Rate-Limit)
500	`internal`	Εσωτερικό σφάλμα διακομιστή

Σελιδοποίηση

Το API χρησιμοποιεί σελιδοποίηση με βάση τον κέρσορα (cursor-based pagination):

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

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

Όρια ρυθμού (Rate Limits)

Κάθε απάντηση περιέχει:

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

Διαδραστική αναφορά API

Δοκιμάστε όλα τα endpoints απευθείας στο πρόγραμμα περιήγησης:

→ Άνοιγμα αναφοράς API (Scalar, διαδραστικό, με δυνατότητα δοκιμής Try-it-out)

Συμβόλαιο DPP (Φάση 4a)

Για τη ροή εργασίας μπαταριών, το qr3.app τεκμηριώνει επιπλέον αυτές τις διαδρομές:

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

Οι σελίδες του πίνακα ελέγχου (Dashboard), τα SDKs και αυτή η τεκμηρίωση χρησιμοποιούν το ίδιο συμβόλαιο δεδομένων.