Files API

Přehled

Files API hostuje soubory na qr3 a poskytuje pro ně stabilní URL. QR kód ukazuje na tuto URL — soubor za ní můžete kdykoli vyměnit, aniž byste museli kód znovu tisknout.

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

Volitelně můžete soubor propojit s kódem pomocí code_id. To je základ pro landing page pro každý kód, která zobrazuje všechny veřejné soubory daného kódu.

Podporované typy jsou kontrolovány pomocí magic bytes, nikoli podle přípony souboru: PDF, PNG, JPEG, WebP, MP4, glTF/GLB, JSON. Soubor .pdf, který není skutečným PDF, bude odmítnut.

Poznámka

Je třeba je odlišit od dokumentů DPP (Digital Product Passport): Ty jsou specifické pro DPP a jsou vázány na Passport. Files API je generické a je vázáno na kód, nebo na nic.

Role

Operace	Vyžadováno	Obdrží 403
Všechny GET	jakákoli role	—
POST /upload, PUT /:id	role pro zápis	viewer
DELETE /:id	role pro mazání	viewer, contributor

Zvláštním pravidlem je contributor: Tato role může vytvářet a měnit, ale nemůže nic mazat.

Upozornění

Publishable Key (qr3_pk_) je bez ohledu na své scopes vždy v roli viewer — klíče vložené na straně klienta tedy nikdy nemohou nahrávat, nahrazovat ani mazat. Nahrávání vyžaduje Secret Key nebo Test Key s oprávněním pro zápis (write scope).

Nahrání souboru

POST /v1/files/upload

Očekává multipart/form-data.

Pole	Povinné	Popis
file	Ano	Soubor
code_id	Ne	Propojení s kódem (musí patřit do stejného Workspace)
visibility	Ne	private (výchozí) nebo 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
});

Odpověď (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 nastavena pouze při visibility: "public" a status: "active". Tato adresa nevyžaduje přihlášení a je přímo vhodná jako cílová URL QR kódu.

Seznam souborů

GET /v1/files

Query parametry: code_id a visibility, oba volitelné. Vrací aktivní soubory ve Workspace, nejnovější jako první.

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

Odpověď (HTTP 200):

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

Upozornění

Tento koncový bod (endpoint) se liší od standardního formátu seznamu: Není stránkovaný (paginated) a nevrací meta.pagination — vždy se vrátí všechny nalezené výsledky.

file_count a total_size_bytes se vztahují na filtrovanou množinu výsledků, nikoli na Workspace jako celek. S parametry ?code_id=… oder ?visibility=… počítají pouze filtrované soubory a nelze je tedy použít pro zjištění celkového využití limitu vašeho tarifu (Plan).

Získání informací o souboru

GET /v1/files/:id

Vrací metadata včetně download_url (a public_url u veřejných souborů). Čitelné pro všechny role.

Stažení souboru

GET /v1/files/:id/download

Streamuje obsah jako Content-Disposition: attachment s hlavičkou Cache-Control: private, no-store — odpověď je tedy vždy v aktuálním stavu, na rozdíl od cachované veřejné URL /f/:id.

Chyba 404 může nastat ve dvou případech: Soubor ve Workspace neexistuje (nebo je smazán), nebo existuje, ale chybí uložený objekt.

Nahrazení souboru

PUT /v1/files/:id

Nahradí obsah a zachová id — a tím i veřejnou adresu /f/:id a download_url. Již vytištěný QR kód zůstává 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 zůstávají zachovány; filename, mime_type, size_bytes a hash_sha256 se aktualizují. Limit tarifu (Plan) na soubor platí stejně jako při nahrávání, limit úložiště Workspace se ověřuje vůči rozdílu velikostí. Limit „počet souborů na kód“ neplatí, protože žádný nový soubor nepřibývá.

Poznámka

Veřejná URL je poskytována s hlavičkou Cache-Control: public, max-age=300. Po výměně souboru tak může cachovaná verze na CDN nebo v prohlížeči zobrazovat starý soubor až po dobu 5 minut. Autentizované stažení používá no-store a je okamžitě aktuální.

Smazání souboru

DELETE /v1/files/:id

Soft-delete: Soubor okamžitě zmizí ze seznamu, již není dostupný a — pokud je veřejný — přestane se pod /f/:id poskytovat.

Odpověď (HTTP 200):

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

Upozornění

Smazání neznamená okamžité zneveřejnění pro někoho, kdo již má přímý odkaz: /f/:id se doručuje s max-age=300 a může soubor zobrazovat ještě po dobu 5 minut. Naproti tomu landing page se necachuje a soubor na ní přestane být viditelný okamžitě.

Volání není idempotentní — druhý požadavek DELETE na stejný soubor vrátí 404.

Limity

Tarif (Plan)	Max. na soubor
Free	5 MB
Pro	25 MB
Business	100 MB
Agency	100 MB
Enterprise	250 MB

Kromě toho platí pro každý tarif maximální počet souborů na kód a celková kapacita úložiště pro Workspace. Rychlostní limit (rate limit) pro nahrávání je 100 nahrání za hodinu na jeden Workspace.

Chyby

Stav	Kdy
400	Neznámý nebo neodpovídající podpis souboru (file signature), neplatné tělo multipart
401	Chybějící nebo neplatný API klíč
403	Role nemá oprávnění k zápisu, resp. k mazání
404	code_id nebo soubor neexistuje ve Workspace; při stahování také: objekt chybí v úložišti
413	Soubor je větší než limit tarifu
422	Soubor chybí, neplatná visibility, byl dosažen limit „počet souborů na kód“ nebo byl překročen limit úložiště Workspace
429	Rychlostní limit nahrávání (100/hodinu/Workspace) nebo obecný rate limit

Související

• Soubory a datové listy — cesta přes administraci (dashboard)
• Landing page pro každý kód