Files API

Pregled

Files API gosti datoteke na qr3 in za njih zagotavlja stabilen URL. Koda QR kaže na ta URL — datoteko v ozadju lahko kadar koli zamenjate, ne da bi morali kodo ponovno natisniti.

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

Izbirno lahko datoteko prek code_id povežete s kodo. To je osnova za pristajalno stran za posamezno kodo, ki navaja vse javne datoteke določene kode.

Podprte vrste se preverjajo prek čarobnih bajtov (magic bytes) in ne po končnici datoteke: PDF, PNG, JPEG, WebP, MP4, glTF/GLB, JSON. Datoteka .pdf, ki ni dejansko PDF, bo zavrnjena.

Note

Razlikovati jih je treba od dokumentov DPP (Digital Product Passport): Ti so specifični za DPP in vezani na potni list (Passport). Files API pa je generičen in vezan na kodo ali pa sploh na nič.

Vloge

Operacija	Zahtevano	Prejme 403
Vsi GET	katera koli vloga	—
POST /upload, PUT /:id	vloga za pisanje	viewer
DELETE /:id	vloga za brisanje	viewer, contributor

Posebno pravilo velja za contributor: ta vloga lahko ustvarja in spreminja, ne more pa ničesar odstraniti.

Caution

Publishable Key (qr3_pk_) je neodvisno od svojih obsegov (scopes) vedno viewer — ključi, vgrajeni na strani odjemalca (client-side), torej nikoli ne morejo nalagati, zamenjati ali brisati datotek. Za prenose (uploads) potrebujete Secret ali Test ključ z obsegom za pisanje (write scope).

Nalaganje datoteke

POST /v1/files/upload

Pričakuje multipart/form-data.

Polje	Obvezno	Opis
file	Da	Datoteka
code_id	Ne	Povezava s kodo (morata pripadati istemu delovnemu prostoru Workspace)
visibility	Ne	private (privzeto) ali 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 nastavljen le pri visibility: "public" in status: "active". Naslov ne zahteva prijave in je neposredno primeren kot ciljni URL kode QR.

Seznam datotek

GET /v1/files

Poizvedba (Query): code_id in visibility, oboje neobvezno. Vrne aktivne datoteke delovnega prostora Workspace, najnovejše najprej.

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

Ta končna točka (endpoint) odstopa od standardne oblike seznama: ni paginirana in ne vrača meta.pagination — vedno se vrnejo vsi rezultati.

file_count in total_size_bytes se nanašata na filtrirano množico rezultatov in ne na celoten delovni prostor Workspace. S ?code_id=… ali ?visibility=… preštejeta le filtrirane datoteke in zato nista primerna za preverjanje zasedenosti prostora glede na omejitve paketa (Plan).

Pridobivanje informacij o datoteki

GET /v1/files/:id

Vrne metapodatke, vključno z download_url (in public_url pri javnih datotekah). Berljivo za vse vloge.

Prenos datoteke

GET /v1/files/:id/download

Vsebino prenaša kot tok (stream) s Content-Disposition: attachment in Cache-Control: private, no-store — odgovor je torej vedno trenutno stanje, za razliko od predpomnjenega javnega URL-ja /f/:id.

Napaka 404 se lahko pojavi v dveh primerih: datoteka ne obstaja v delovnem prostoru Workspace (ali pa je izbrisana) ali pa obstaja, vendar manjka shranjeni objekt.

Zamenjava datoteke

PUT /v1/files/:id

Zamenja vsebino in ohrani id — s tem pa tudi javni naslov /f/:id in naslov download_url. Že natisnjena koda QR ostane veljavna.

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

visibility, code_id in created_at se ohranijo; filename, mime_type, size_bytes in hash_sha256 se posodobijo. Omejitev paketa (Plan) na datoteko velja enako kot pri nalaganju, omejitev pomnilnika delovnega prostora Workspace pa se preveri glede na razliko v velikosti. Omejitev “število datotek na kodo” ne velja, saj se ne doda nova datoteka.

Note

Javni URL se dostavi s Cache-Control: public, max-age=300. Po zamenjavi lahko predpomnjena različica na omrežju CDN ali v brskalniku še do 5 minut prikazuje staro datoteko. Avtenticiran prenos uporablja no-store in je takoj posodobljen.

Brisanje datoteke

DELETE /v1/files/:id

Mehki izbris (Soft-Delete): Datoteka takoj izgine s seznama, ni več dostopna in se — če je javna — ne ponuja več na naslovu /f/:id.

Odgovor (HTTP 200):

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

Caution

Brisanje ne pomeni takojšnjega umika objave za nekoga, ki že ima neposredno povezavo: /f/:id se dostavi z max-age=300 in lahko datoteko prikazuje še do 5 minut. Nasprotno pa se pristajalna stran ne predpomni in datoteke takoj ne prikazuje več.

Klic ni idempotenten — ponovni DELETE za isto datoteko vrne 404.

Omejitve

Paket (Plan)	Največ na datoteko
Free	5 MB
Pro	25 MB
Business	100 MB
Agency	100 MB
Enterprise	250 MB

Poleg tega za vsak paket veljata največje število datotek na kodo in skupni pomnilnik na delovni prostor Workspace. Omejitev pogostosti nalaganja (Upload-Ratelimit) je 100 prenosov na uro na delovni prostor Workspace.

Napake

Status	Kdaj
400	Neznan ali neustrezen podpis datoteke, neveljavno večdelno telo (multipart-body)
401	Ni ključa API ali pa je neveljaven
403	Vloga nima pravic za pisanje oziroma brisanje
404	code_id ali datoteka ni v delovnem prostoru Workspace; pri prenosu tudi: objekt manjka v pomnilniku
413	Datoteka je večja od omejitve paketa (Plan)
422	Datoteka manjka, neveljavna visibility, dosežena omejitev “število datotek na kodo”, presežena omejitev pomnilnika delovnega prostora Workspace
429	Omejitev pogostosti nalaganja (100/uro/Workspace) ali splošna omejitev pogostosti (Rate-Limit)

Povezano

• Datoteke in podatkovni listi — pot prek nadzorne plošče (Dashboard)
• Pristajalna stran za posamezno kodo