Files API

Prehľad

Files API hostuje súbory na qr3 a poskytuje pre ne stabilnú URL adresu. QR kód odkazuje na túto URL adresu — súbor za ňou môžete kedykoľvek vymeniť bez toho, aby ste museli kód znova tlačiť.

Základná URL: https://qr3.app/v1/files

Voliteľne môžete súbor prepojiť s kódom pomocou code_id. To je základ pre vstupnú stránku pre kód, ktorá zobrazuje zoznam všetkých verejných súborov daného kódu.

Podporované typy sa kontrolujú pomocou Magic-Byte, nie podľa prípony súboru: PDF, PNG, JPEG, WebP, MP4, glTF/GLB, JSON. Súbor .pdf, ktorý nie je skutočným PDF, bude odmietnutý.

Poznámka

Na odlíšenie od dokumentov DPP (Digital Product Passport): Tieto dokumenty sú špecifické pre DPP a sú viazané na Passport. Files API je generické rozhranie a je viazané na kód alebo na nič.

Roly

Operácia	Vyžaduje sa	Dostane 403
Všetky GET	akákoľvek rola	—
POST /upload, PUT /:id	rola na zápis	viewer
DELETE /:id	rola na mazanie	viewer, contributor

Špeciálnym pravidlom je contributor: táto rola môže vytvárať a meniť, ale nemôže nič odstraňovať.

Upozornenie

Publishable Key (qr3_pk_) je bez ohľadu na svoje scopes vždy v role viewer — kľúče vložené na strane klienta teda nikdy nemôžu nahrávať, nahrádzať ani mazať. Nahrávanie vyžaduje Secret alebo Test kľúč so scope na zápis.

Nahrať súbor

POST /v1/files/upload

Očakáva multipart/form-data.

Pole	Povinné	Popis
file	Áno	Súbor
code_id	Nie	Prepojenie s kódom (musí patriť do Workspace)
visibility	Nie	private (predvolené) alebo 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
});

Odozva (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 nastavená iba pri visibility: "public" a status: "active". Táto adresa nevyžaduje prihlásenie a je priamo vhodná ako cieľová URL adresa QR kódu.

Zoznam súborov

GET /v1/files

Query parametre: code_id a visibility, oba sú voliteľné. Vracia aktívne súbory daného Workspace, najnovšie ako prvé.

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

Odozva (HTTP 200):

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

Upozornenie

Tento endpoint sa líši od štandardného formátu zoznamu: nie je stránkovaný (paginated) a nevracia meta.pagination — vždy sa vrátia všetky nájdené výsledky.

file_count a total_size_bytes sa vzťahujú na filtrovanú množinu výsledkov, nie na Workspace ako celok. Pri použití ?code_id=… alebo ?visibility=… počítajú iba vyfiltrované súbory, a preto nie sú vhodné na zisťovanie celkového využitia úložiska pre limity programu (Plan).

Získať informácie o súbore

GET /v1/files/:id

Vracia metadáta vrátane download_url (a public_url pri verejných súboroch). Čitateľné pre všetky roly.

Stiahnuť súbor

GET /v1/files/:id/download

Streamuje obsah ako Content-Disposition: attachment s hlavičkou Cache-Control: private, no-store — odpoveď je teda vždy v aktuálnom stave, na rozdiel od cachovanej verejnej /f/:id URL adresy.

404 môže nastať v dvoch prípadoch: súbor vo Workspace neexistuje (alebo je vymazaný), alebo existuje, ale chýba uložený objekt.

Nahradiť súbor

PUT /v1/files/:id

Nahradí obsah a zachová id — a tým aj verejnú /f/:id a download_url adresu. Už vytlačený QR kód zostáva platný.

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

visibility, code_id a created_at zostávajú zachované; filename, mime_type, size_bytes a hash_sha256 sa aktualizujú. Limit programu (Plan) na súbor platí rovnako ako pri nahrávaní, limit úložiska Workspace sa kontroluje voči rozdielu veľkostí. Limit „súborov na kód“ neplatí, keďže nepribúda žiadny nový súbor.

Poznámka

Verejná URL adresa sa poskytuje s hlavičkou Cache-Control: public, max-age=300. Po výmene súboru preto môže nacachovaný stav na CDN alebo v prehliadači zobrazovať starý súbor až po dobu 5 minút. Autentifikované sťahovanie používa no-store a je okamžite aktuálne.

Vymazať súbor

DELETE /v1/files/:id

Soft-Delete: Súbor okamžite zmizne zo zoznamu, už nie je dostupný a — ak je verejný — prestane sa poskytovať na adrese /f/:id.

Odozva (HTTP 200):

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

Upozornenie

Vymazanie neznamená okamžité zrušenie zverejnenia pre niekoho, kto už má priamy odkaz: /f/:id sa poskytuje s max-age=300 a môže zobrazovať súbor ešte po dobu 5 minút. Naopak, vstupná stránka sa necachuje a súbor na nej okamžite prestane byť viditeľný.

Volanie nie je idempotentné — druhé DELETE na ten istý súbor vráti 404.

Limity

Program	Max. na súbor
Free	5 MB
Pro	25 MB
Business	100 MB
Agency	100 MB
Enterprise	250 MB

Okrem toho platí pre každý program maximálny počet súborov na kód a celkové úložisko pre Workspace. Rýchlostný limit (Rate limit) pre nahrávanie je 100 nahraní za hodinu na jeden Workspace.

Chyby

Status	Kedy
400	Neznámy alebo nezhodujúci sa podpis súboru, neplatné telo multipart
401	Chýbajúci alebo neplatný API kľúč
403	Rola nemá oprávnenie na zápis, resp. na mazanie
404	code_id alebo súbor sa nenachádza vo Workspace; pri sťahovaní tiež: objekt chýba v úložisku
413	Súbor je väčší ako limit programu
422	Súbor chýba, neplatná visibility, dosiahnutý limit „súborov na kód“, prekročený limit úložiska Workspace
429	Rýchlostný limit nahrávania (100/hodina/Workspace) oder allgemeines rýchlostný limit

Súvisiace

• Súbory a dátové hárky — cesta cez nástenku (Dashboard)
• Vstupná stránka pre kód