Files API

Pregled

Files API hosta datoteke na qr3 i pruža stabilan URL za njih. QR kod usmjerava na taj URL — datoteku iza njega možete zamijeniti u bilo kojem trenutku bez ponovnog tiskanja koda.

Bazni URL: https://qr3.app/v1/files

Opcionalno možete povezati datoteku s kodom putem parametra code_id. To je osnova za landing stranicu po kodu koja prikazuje sve javne datoteke nekog koda.

Podržani tipovi provjeravaju se putem magic byte-a, a ne prema nazivu datoteke: PDF, PNG, JPEG, WebP, MP4, glTF/GLB, JSON. Datoteka .pdf koja zapravo nije PDF bit će odbijena.

Note

Treba razlikovati od DPP dokumenata (Digital Product Passport): oni su specifični za DPP i vezani uz putovnicu (Passport). Files API je generički i vezan uz kod ili nije vezan ni uz što.

Uloge

Operacija	Potrebno	Dobiva 403
Svi GET	bilo koja uloga	—
POST /upload, PUT /:id	uloga s pravom pisanja	viewer
DELETE /:id	uloga s pravom brisanja	viewer, contributor

Posebno pravilo vrijedi za ulogu contributor: ova uloga može stvarati i mijenjati, ali ne može ništa uklanjati.

Caution

Jedan Publishable Key (qr3_pk_) je, neovisno o svojim opsezima (scopes), uvijek viewer — ključevi ugrađeni na klijentskoj strani stoga nikada ne mogu učitavati, zamjenjivati ili brisati. Za učitavanje je potreban Secret ili Test ključ s opsegom za pisanje.

Učitavanje datoteke

POST /v1/files/upload

Očekuje multipart/form-data.

Polje	Obvezno	Opis
file	Da	Datoteka
code_id	Ne	Povezivanje s kodom (mora pripadati radnom prostoru)
visibility	Ne	private (zadano) ili 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
});

Odgovor (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 je postavljen samo uz visibility: "public" i status: "active". Adresa ne zahtijeva prijavu i prikladna je izravno kao ciljni URL za QR kod.

Popis datoteka

GET /v1/files

Upit (Query): code_id i visibility, oba opcionalna. Vraća aktivne datoteke radnog prostora, najnovije prve.

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

Odgovor (HTTP 200):

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

Caution

Ova krajnja točka (endpoint) odstupa od standardnog formata popisa: nije paginirana i ne vraća meta.pagination — uvijek se vraćaju svi rezultati.

file_count i total_size_bytes odnose se na filtrirani skup rezultata, a ne na cijeli radni prostor. Uz ?code_id=… ili ?visibility=… oni broje samo filtrirane datoteke i stoga nisu prikladni kao pokazatelj iskorištenosti pohrane za ograničenje paketa.

Dohvaćanje informacija o datoteci

GET /v1/files/:id

Vraća metapodatke uključujući download_url (i public_url za javne datoteke). Čitljivo za sve uloge.

Preuzimanje datoteke

GET /v1/files/:id/download

Preuzima sadržaj kao strujanje (stream) s Content-Disposition: attachment i Cache-Control: private, no-store — odgovor je stoga uvijek trenutačno stanje, za razliku od predmemoriranog javnog /f/:id URL-a.

404 se može dogoditi u dva slučaja: datoteka ne postoji u radnom prostoru (ili je obrisana) ili postoji, ali nedostaje pohranjeni objekt.

Zamjena datoteke

PUT /v1/files/:id

Mijenja sadržaj i zadržava id — a time i javnu /f/:id te download_url adresu. Već otisnuti QR kod ostaje važeći.

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

visibility, code_id i created_at ostaju nepromijenjeni; filename, mime_type, size_bytes i hash_sha256 se ažuriraju. Ograničenje paketa po datoteci vrijedi isto kao i kod učitavanja, a ograničenje pohrane radnog prostora provjerava se u odnosu na razliku. Ograničenje “broj datoteka po kodu” ne vrijedi jer se ne dodaje nova datoteka.

Note

Javni URL isporučuje se s Cache-Control: public, max-age=300. Nakon zamjene, predmemorirano stanje na CDN-u ili u pregledniku može stoga prikazivati staru datoteku do 5 minuta. Autentificirano preuzimanje koristi no-store i odmah je ažurno.

Brisanje datoteke

DELETE /v1/files/:id

Meko brisanje (Soft-Delete): datoteka odmah nestaje s popisa, više se ne može dohvatiti i — ako je javna — više se ne isporučuje na /f/:id.

Odgovor (HTTP 200):

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

Caution

Brisanje nije trenutačno povlačenje iz javnosti za nekoga tko već ima izravnu poveznicu: /f/:id se isporučuje s max-age=300 i može prikazivati datoteku još do 5 minuta. S druge strane, landing stranica se ne predmemorira i odmah prestaje prikazivati datoteku.

Poziv nije idempotentan — drugo DELETE brisanje iste datoteke vraća 404.

Ograničenja

Paket	Maks. po datoteci
Free	5 MB
Pro	25 MB
Business	100 MB
Agency	100 MB
Enterprise	250 MB

Dodatno, ovisno o paketu, vrijedi maksimalan broj datoteka po kodu i ukupna pohrana po radnom prostoru. Ograničenje učitavanja (Upload-Ratelimit) iznosi 100 učitavanja po satu po radnom prostoru.

Pogreške

Status	Kada
400	Nepoznat ili neodgovarajući potpis datoteke, nevažeće multipart tijelo
401	Nema API ključa ili je nevažeći
403	Uloga nema pravo pisanja odnosno brisanja
404	code_id ili datoteka nije u radnom prostoru; kod preuzimanja također: objekt nedostaje u pohrani
413	Datoteka je veća od ograničenja paketa
422	Datoteka nedostaje, nevažeća visibility, dosegnuto ograničenje “broj datoteka po kodu”, prekoračeno ograničenje pohrane radnog prostora
429	Ograničenje učitavanja (100/sat/radni prostor) ili općenito ograničenje brzine (Rate-Limit)

Povezano

• Datoteke i tehnički listovi — put putem nadzorne ploče
• Landing stranica po kodu