Files API

Áttekintés

A Files API fájlokat hosztol a qr3-nál, és ehhez egy stabil URL-t biztosít. A QR-kód erre az URL-re mutat — a mögötte lévő fájlt bármikor kicserélheted anélkül, hogy a kódot újra ki kellene nyomtatnod.

Bázis URL: https://qr3.app/v1/files

Opcionálisan egy fájlt a code_id segítségével egy kódhoz társíthatsz. Ez az alapja a kódonkénti landing page-nek, amely felsorolja egy kód összes nyilvános fájlját.

A támogatott típusokat mágikus bájtok (magic bytes) alapján ellenőrizzük, nem a fájlnév alapján: PDF, PNG, JPEG, WebP, MP4, glTF/GLB, JSON. Egy olyan .pdf fájl, amely valójában nem PDF, elutasításra kerül.

Note

Megkülönböztetendő a DPP-dokumentumoktól (Digital Product Passport): azok DPP-specifikusak és egy Passport-hoz vannak kötve. A Files API generikus, és egy kódhoz vagy egyáltalán semmihez sincs kötve.

Szerepkörök

Művelet	Szükséges	403-at kap
Összes GET	bármely szerepkör	—
POST /upload, PUT /:id	írási szerepkör	viewer
DELETE /:id	törlési szerepkör	viewer, contributor

A contributor egy speciális szabály: ez a szerepkör létrehozhat és módosíthat, de nem törölhet semmit.

Caution

Egy Publishable Key (qr3_pk_) a hatóköreitől (scopes) függetlenül mindig viewer — a kliensoldalon beágyazott kulcsok tehát soha nem tudnak feltölteni, kicserélni vagy törölni. A feltöltésekhez egy írási hatókörrel rendelkező Secret- vagy Test-Key szükséges.

Fájl feltöltése

POST /v1/files/upload

multipart/form-data formátumot vár.

Mező	Kötelező	Leírás
file	Igen	A fájl
code_id	Nem	Kódhoz való társítás (a Workspace-hez kell tartoznia)
visibility	Nem	private (alapértelmezett) vagy 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
});

Válasz (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" }
}

A public_url csak visibility: "public" és status: "active" esetén van beállítva. A cím nem igényel bejelentkezést, és közvetlenül használható egy QR-kód cél-URL-jeként.

Fájlok listázása

GET /v1/files

Query paraméterek: code_id és visibility, mindkettő opcionális. A Workspace aktív fájljait adja vissza, a legújabbal kezdve.

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

Válasz (HTTP 200):

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

Caution

Ez a végpont eltér a standard listázási formátumtól: nem lapozható (nem paginált), és nem ad vissza meta.pagination mezőt — mindig az összes találat érkezik vissza.

A file_count és a total_size_bytes a szűrt találati halmazra vonatkozik, nem a teljes Workspace-re. A ?code_id=… vagy ?visibility=… paraméterekkel csak a szűrt fájlokat számolják, így nem alkalmasak a csomaglimit (Plan-Limit) tárhely-kihasználtságának ellenőrzésére.

Fájlinformációk lekérése

GET /v1/files/:id

Visszaadja a metaadatokat, beleértve a download_url-t (és nyilvános fájlok esetén a public_url-t). Minden szerepkör számára olvasható.

Fájl letöltése

GET /v1/files/:id/download

A tartalmat Content-Disposition: attachment fejléccel és Cache-Control: private, no-store beállítással streameli — a válasz tehát mindig az aktuális állapotot tükrözi, ellentétben a gyorsítótárazott nyilvános /f/:id URL-lel.

A 404 hiba kétféleképpen fordulhat elő: a fájl nem létezik a Workspace-ben (vagy törölve lett), vagy létezik ugyan, de a tárolt objektum hiányzik.

Fájl kicserélése

PUT /v1/files/:id

Kicseréli a tartalmat, de megtartja az id-t — és ezáltal a nyilvános /f/:id és a download_url címet is. A már kinyomtatott QR-kód érvényes marad.

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

A visibility, code_id és created_at megmaradnak; a filename, mime_type, size_bytes és hash_sha256 frissülnek. A fájlonkénti csomaglimit (Plan-Limit) ugyanúgy érvényes, mint a feltöltésnél, a Workspace tárhelylimitjét pedig a különbözet alapján ellenőrizzük. A „kódonkénti fájlok száma” korlát nem érvényes, hiszen nem adódik hozzá új fájl.

Note

A nyilvános URL Cache-Control: public, max-age=300 fejléccel kerül kiszolgálásra. A csere után a gyorsítótárazott CDN- vagy böngészőállapot miatt akár 5 percig is a régi fájl jelenhet meg. A hitelesített letöltés no-store fejlécű, így az azonnal a legfrissebb verziót adja.

Fájl törlése

DELETE /v1/files/:id

Szoftveres törlés (Soft-Delete): A fájl azonnal eltűnik a listából, többé nem érhető el, és — ha nyilvános volt — nem kerül kiszolgálásra a /f/:id címen.

Válasz (HTTP 200):

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

Caution

A törlés nem jelenti a publikálás azonnali visszavonását azok számára, akik már rendelkeznek a közvetlen linkkel: a /f/:id cím max-age=300 értékkel kerül kiszolgálásra, így akár 5 percig is mutathatja a fájlt. Ezzel szemben a landing page nincs gyorsítótárazva, így ott a fájl azonnal eltűnik.

A hívás nem idempotens — egy második DELETE ugyanarra a fájlra 404 hibát ad vissza.

Limitek

Csomag	Max. fájlonként
Free	5 MB
Pro	25 MB
Business	100 MB
Agency	100 MB
Enterprise	250 MB

Ezenkívül csomagonként érvényes egy maximális kódonkénti fájlszám és egy teljes Workspace-tárhelykorlát is. A feltöltési sebességkorlát (rate limit) Workspace-enként óránként 100 feltöltés.

Hibák

Státusz	Mikor
400	Ismeretlen vagy nem egyező fájlaláírás, érvénytelen multipart törzs
401	Hiányzó vagy érvénytelen API-kulcs
403	A szerepkör nem jogosult írásra vagy törlésre
404	A code_id vagy a fájl nem található a Workspace-ben; letöltésnél: az objektum hiányzik a tárolóból
413	A fájl mérete meghaladja a csomaglimitet
422	Hiányzó fájl, érvénytelen visibility, a „kódonkénti fájlok száma” korlát elérve, a Workspace tárhelylimitje túllépve
429	Feltöltési sebességkorlát (100/óra/Workspace) vagy általános sebességkorlát

Kapcsolódó témakörök

• Fájlok és adatlapok — az elérés a vezérlőpulton (Dashboard) keresztül
• Kódonkénti landing page