Files API

Prezentare generală

API-ul Files găzduiește fișiere pe qr3 și oferă un URL stabil pentru acestea. Codul QR indică spre acest URL — poți înlocui oricând fișierul din spate, fără a reimprima codul.

URL de bază: https://qr3.app/v1/files

Opțional, poți asocia un fișier cu un cod prin intermediul code_id. Aceasta este baza pentru landing page-ul per cod, care listează toate fișierele publice ale unui cod.

Tipurile acceptate sunt verificate prin magic bytes, nu după extensia fișierului: PDF, PNG, JPEG, WebP, MP4, glTF/GLB, JSON. Un fișier .pdf care nu este de fapt un PDF va fi respins.

Mențiune

A se diferenția de documentele DPP (Digital Product Passport): acestea sunt specifice DPP și sunt legate de un pașaport. API-ul Files este generic și este legat de un cod sau de nimic.

Roluri

Operațiune	Necesar	Primește 403
Toate GET	orice rol	—
POST /upload, PUT /:id	rol de scriere	viewer
DELETE /:id	rol de ștergere	viewer, contributor

Regula specială este pentru contributor: acest rol poate crea și modifica, dar nu poate șterge nimic.

Atenție

O cheie publicabilă (qr3_pk_) are întotdeauna rolul de viewer, indiferent de scopurile (scopes) sale — prin urmare, cheile integrate pe partea de client nu pot niciodată să încarce, să înlocuiască sau să șteargă. Încărcările necesită o cheie secretă sau de testare cu scop de scriere.

Încărcare fișier

POST /v1/files/upload

Se așteaptă multipart/form-data.

Câmp	Obligatoriu	Descriere
file	Da	Fișierul
code_id	Nu	Asociere cu un cod (trebuie să aparțină de Workspace)
visibility	Nu	private (implicit) sau 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
});

Răspuns (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 este setat doar pentru visibility: "public" și status: "active". Adresa nu necesită autentificare și este potrivită direct ca URL de destinație al unui cod QR.

Listare fișiere

GET /v1/files

Query: code_id și visibility, ambele opționale. Returnează fișierele active din Workspace, cele mai recente primele.

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

Răspuns (HTTP 200):

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

Atenție

Acest endpoint deviază de la formatul standard de listă: nu este paginat și nu returnează meta.pagination — sunt returnate întotdeauna toate rezultatele.

file_count și total_size_bytes se referă la setul de rezultate filtrate, nu la întregul Workspace. Cu ?code_id=… sau ?visibility=…, acestea contorizează doar fișierele filtrate și, prin urmare, nu sunt potrivite pentru verificarea limitei de stocare a abonamentului.

Obținere informații fișier

GET /v1/files/:id

Returnează metadatele, inclusiv download_url (și public_url pentru fișierele publice). Poate fi citit de toate rolurile.

Descărcare fișier

GET /v1/files/:id/download

Transmite conținutul ca flux (stream) cu Content-Disposition: attachment și Cache-Control: private, no-store — prin urmare, răspunsul reprezintă întotdeauna starea actuală, spre deosebire de URL-ul public /f/:id care este stocat în cache.

Eroarea 404 poate apărea în două moduri: fișierul nu există în Workspace (sau este șters) sau acesta există, dar obiectul stocat lipsește.

Înlocuire fișier

PUT /v1/files/:id

Înlocuiește conținutul și păstrează id-ul — și, prin urmare, adresa publică /f/:id și adresa download_url. Un cod QR deja imprimat rămâne valabil.

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

visibility, code_id și created_at sunt păstrate; filename, mime_type, size_bytes și hash_sha256 sunt actualizate. Limita abonamentului per fișier se aplică la fel ca la încărcare, iar limita de stocare a Workspace-ului este verificată în raport cu diferența. Limita „fișiere per cod” nu se aplică, deoarece nu se adaugă niciun fișier nou.

Mențiune

URL-ul public este livrat cu Cache-Control: public, max-age=300. După o înlocuire, o versiune stocată în cache de CDN sau de browser poate afișa fișierul vechi timp de până la 5 minute. Descărcarea autentificată folosește no-store și este actualizată instantaneu.

Ștergere fișier

DELETE /v1/files/:id

Ștergere logică (soft delete): fișierul dispare imediat din listă, nu mai poate fi accesat și — dacă este public — nu mai este livrat la adresa /f/:id.

Răspuns (HTTP 200):

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

Atenție

O ștergere nu înseamnă o retragere imediată din publicare pentru cineva care are deja linkul direct: /f/:id este livrat cu max-age=300 și poate afișa în continuare fișierul timp de până la 5 minute. Pe de altă parte, landing page-ul nu este stocat în cache și nu mai afișează fișierul imediat.

Apelul nu este idempotent — un al doilea DELETE pentru același fișier returnează 404.

Limite

Abonament	Max. per fișier
Free	5 MB
Pro	25 MB
Business	100 MB
Agency	100 MB
Enterprise	250 MB

În plus, se aplică un număr maxim de fișiere per cod și un spațiu total de stocare per Workspace, în funcție de abonament. Limita de rată pentru încărcare este de 100 de încărcări pe oră per Workspace.

Erori

Status	Când
400	Semnătură de fișier necunoscută sau necorespunzătoare, corp multipart nevalid
401	Lipsă cheie API sau cheie API nevalidă
403	Rolul nu are permisiunea de a scrie sau de a șterge
404	code_id sau fișierul nu se află în Workspace; la descărcare și: obiectul lipsește din spațiul de stocare
413	Fișierul este mai mare decât limita abonamentului
422	Fișierul lipsește, visibility nevalidă, limita „fișiere per cod” a fost atinsă, limita de stocare a Workspace-ului a fost depășită
429	Limită de rată pentru încărcare (100/oră/Workspace) sau limită de rată generală

Subiecte conexe

• Fișiere și fișe tehnice — calea prin panoul de control (dashboard)
• Landing page per cod