Files API

Επισκόπηση

Το Files API φιλοξενεί αρχεία στο qr3 και παρέχει μια σταθερή URL διεύθυνση. Ο κώδικας QR δείχνει σε αυτή τη URL διεύθυνση — μπορείτε να αντικαταστήσετε το αρχείο πίσω από αυτήν ανά πάσα στιγμή, χωρίς να εκτυπώσετε ξανά τον κώδικα.

Βασική URL: https://qr3.app/v1/files

Προαιρετικά, μπορείτε να συνδέσετε ένα αρχείο με έναν κώδικα μέσω του code_id. Αυτή είναι η βάση για τη landing page ανά κώδικα, η οποία παραθέτει όλα τα δημόσια αρχεία ενός κώδικα.

Οι υποστηριζόμενοι τύποι ελέγχονται μέσω magic byte και όχι από το όνομα του αρχείου: PDF, PNG, JPEG, WebP, MP4, glTF/GLB, JSON. Ένα αρχείο .pdf που δεν είναι PDF θα απορριφθεί.

Note

Πρέπει να διακρίνεται από τα έγγραφα DPP (Digital Product Passport): Αυτά είναι ειδικά για το DPP και συνδέονται με ένα Passport. Το Files API είναι γενικό και συνδέεται με έναν κώδικα ή με τίποτα.

Ρόλοι

Λειτουργία	Απαιτείται	Λαμβάνει 403
Όλα τα GET	οποιοσδήποτε ρόλος	—
POST /upload, PUT /:id	ρόλος εγγραφής	viewer
DELETE /:id	ρόλος διαγραφής	viewer, contributor

Ο ειδικός κανόνας είναι ο contributor: Αυτός ο ρόλος επιτρέπει τη δημιουργία και την τροποποίηση, αλλά όχι τη διαγραφή.

Caution

Ένα Publishable Key (qr3_pk_) είναι πάντα viewer ανεξάρτητα από τα scopes του — επομένως, τα κλειδιά που είναι ενσωματωμένα στην πλευρά του πελάτη (client-side) δεν μπορούν ποτέ να ανεβάσουν, να αντικαταστήσουν ή να διαγράψουν αρχεία. Οι μεταφορτώσεις (uploads) απαιτούν ένα Secret ή Test Key με scope εγγραφής.

Μεταφόρτωση αρχείου

POST /v1/files/upload

Αναμένει multipart/form-data.

Πεδίο	Υποχρεωτικό	Περιγραφή
file	Ναι	Το αρχείο
code_id	Όχι	Σύνδεση με έναν κώδικα (πρέπει να ανήκει στο Workspace)
visibility	Όχι	private (προεπιλογή) ή public

cURL

curl -X POST https://qr3.app/v1/files/upload \
  -H "Authorization: Bearer qr3_sk_..." \
  -F "[email protected]" \
  -F "code_id=qr_a1b2c3d4" \
  -F "visibility=public"

JavaScript

const form = new FormData();
form.append('file', fileInput.files[0]);
form.append('code_id', 'qr_a1b2c3d4');
form.append('visibility', 'public');

const res = await fetch('https://qr3.app/v1/files/upload', {
  method: 'POST',
  headers: { Authorization: 'Bearer qr3_sk_...' },
  body: form, // Content-Type NICHT selbst setzen — der Boundary fehlt sonst
});

Απάντηση (HTTP 201):

{
  "data": {
    "id": "file_a1b2c3d4",
    "code_id": "qr_a1b2c3d4",
    "filename": "datenblatt.pdf",
    "mime_type": "application/pdf",
    "size_bytes": 284913,
    "hash_sha256": "9f86d081884c7d65…",
    "visibility": "public",
    "status": "active",
    "created_at": "2026-03-14T12:00:00.000Z",
    "download_url": "https://qr3.app/v1/files/file_a1b2c3d4/download",
    "public_url": "https://qr3.app/f/file_a1b2c3d4"
  },
  "meta": { "request_id": "req_abc123" }
}

Το public_url ορίζεται μόνο με visibility: "public" και status: "active". Η διεύθυνση δεν απαιτεί σύνδεση και είναι κατάλληλη απευθείας ως URL προορισμού ενός κώδικα QR.

Λίστα αρχείων

GET /v1/files

Query: code_id και visibility, και τα δύο προαιρετικά. Επιστρέφει τα ενεργά αρχεία του Workspace, με τα νεότερα πρώτα.

curl "https://qr3.app/v1/files?code_id=qr_a1b2c3d4" \
  -H "Authorization: Bearer qr3_sk_..."

Απάντηση (HTTP 200):

{
  "data": [ { "id": "file_a1b2c3d4", "…": "…" } ],
  "meta": {
    "request_id": "req_abc123",
    "file_count": 3,
    "total_size_bytes": 812004
  }
}

Caution

Αυτό το endpoint αποκλίνει από τη βασική μορφή λίστας: Δεν διαθέτει σελιδοποίηση και δεν παρέχει το meta.pagination — επιστρέφονται πάντα όλα τα αποτελέσματα.

Τα file_count και total_size_bytes αναφέρονται στο φιλτραρισμένο σύνολο αποτελεσμάτων και όχι στο Workspace συνολικά. Με τη χρήση των ?code_id=… ή ?visibility=…, μετρούν μόνο τα φιλτραρισμένα αρχεία και επομένως δεν είναι κατάλληλα για τον έλεγχο του ορίου αποθήκευσης του πακέτου σας.

Ανάκτηση πληροφοριών αρχείου

GET /v1/files/:id

Επιστρέφει τα μεταδεδομένα, συμπεριλαμβανομένου του download_url (και του public_url για δημόσια αρχεία). Είναι αναγνώσιμο από όλους τους ρόλους.

Λήψη αρχείου

GET /v1/files/:id/download

Μεταδίδει το περιεχόμενο ως ροή (stream) με Content-Disposition: attachment και Cache-Control: private, no-store — επομένως, η απάντηση είναι πάντα η τρέχουσα κατάσταση, σε αντίθεση με την αποθηκευμένη στην κρυφή μνήμη (cached) δημόσια URL /f/:id.

Το σφάλμα 404 μπορεί να προκύψει με δύο τρόπους: Το αρχείο δεν υπάρχει στο Workspace (ή έχει διαγραφεί), ή υπάρχει αλλά λείπει το αποθηκευμένο αντικείμενο.

Αντικατάσταση αρχείου

PUT /v1/files/:id

Αντικαθιστά το περιεχόμενο και διατηρεί το id — και συνεπώς τη δημόσια διεύθυνση /f/:id και τη διεύθυνση download_url. Ένας ήδη εκτυπωμένος κώδικας QR παραμένει έγκυρος.

curl -X PUT https://qr3.app/v1/files/file_a1b2c3d4 \
  -H "Authorization: Bearer qr3_sk_..." \
  -F "[email protected]"

Τα visibility, code_id και created_at διατηρούνται. Τα filename, mime_type, size_bytes και hash_sha256 ενημερώνονται. Το όριο πακέτου ανά αρχείο ισχύει όπως και κατά τη μεταφόρτωση, ενώ το όριο αποθήκευσης του Workspace ελέγχεται με βάση τη διαφορά μεγέθους. Το όριο “Αρχεία ανά κώδικα” δεν εφαρμόζεται, καθώς δεν προστίθεται νέο αρχείο.

Note

Η δημόσια URL παρέχεται με Cache-Control: public, max-age=300. Επομένως, μετά από μια αντικατάσταση, μια αποθηκευμένη έκδοση στο CDN ή στο πρόγραμμα περιήγησης (browser) ενδέχεται να εμφανίζει το παλιό αρχείο για έως και 5 λεπτά. Η λήψη με πιστοποίηση (authenticated download) έχει οριστεί σε no-store και ενημερώνεται αμέσως.

Διαγραφή αρχείου

DELETE /v1/files/:id

Προσωρινή διαγραφή (Soft-Delete): Το αρχείο εξαφανίζεται αμέσως από τη λίστα, δεν είναι πλέον προσβάσιμο και — εάν είναι δημόσιο — δεν παρέχεται πλέον στη διεύθυνση /f/:id.

Απάντηση (HTTP 200):

{
  "data": { "id": "file_a1b2c3d4", "deleted": true },
  "meta": { "request_id": "req_abc123" }
}

Caution

Η διαγραφή δεν σημαίνει άμεση κατάργηση δημοσίευσης για κάποιον που έχει ήδη τον απευθείας σύνδεσμο: Η διεύθυνση /f/:id παρέχεται με max-age=300 και ενδέχεται να εμφανίζει το αρχείο για έως και 5 λεπτά ακόμη. Αντίθετα, η landing page δεν αποθηκεύεται στην κρυφή μνήμη και σταματά αμέσως να εμφανίζει το αρχείο.

Η κλήση δεν είναι idempotent — μια δεύτερη κλήση DELETE στο ίδιο αρχείο επιστρέφει 404.

Όρια

Πακέτο	Μέγιστο ανά αρχείο
Free	5 MB
Pro	25 MB
Business	100 MB
Agency	100 MB
Enterprise	250 MB

Επιπλέον, ανάλογα με το πακέτο, ισχύει ένας μέγιστος αριθμός αρχείων ανά κώδικα και ένας συνολικός χώρος αποθήκευσης ανά Workspace. Το όριο ρυθμού μεταφόρτωσης (upload rate limit) είναι 100 μεταφορτώσεις ανά ώρα και ανά Workspace.

Σφάλματα

Κατάσταση	Πότε
400	Άγνωστη ή μη συμβατή υπογραφή αρχείου, μη έγκυρο σώμα multipart
401	Μη έγκυρο ή ελλιπές API Key
403	Ο ρόλος δεν επιτρέπει την εγγραφή ή τη διαγραφή
404	Το code_id ή το αρχείο δεν βρίσκεται στο Workspace. Κατά τη λήψη επίσης: Το αντικείμενο λείπει από τον χώρο αποθήκευσης
413	Το αρχείο είναι μεγαλύτερο από το όριο του πακέτου
422	Το αρχείο λείπει, μη έγκυρη visibility, συμπλήρωση του ορίου “Αρχεία ανά κώδικα”, υπέρβαση του ορίου αποθήκευσης του Workspace
429	Όριο ρυθμού μεταφόρτωσης (100/ώρα/Workspace) ή γενικό όριο ρυθμού

Σχετικά

• Αρχεία & Φύλλα Δεδομένων — η διαδικασία μέσω του Dashboard
• Landing page ανά κώδικα