Files API

Apžvalga

Files API priglobia failus qr3 platformoje ir pateikia stabilią URL nuorodą. QR kodas nukreipia į šį URL adresą – jame esantį failą galite bet kada pakeisti iš naujo nespausdindami kodo.

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

Pasirinktinai galite susieti failą su kodu naudodami code_id. Tai yra pagrindas kiekvieno kodo nukreipimo puslapiui, kuriame pateikiami visi vieši kodo failai.

Palaikomi tipai tikrinami pagal magiškuosius baitus (magic bytes), o ne pagal failo plėtinį: PDF, PNG, JPEG, WebP, MP4, glTF/GLB, JSON. Failas .pdf, kuris nėra PDF, bus atmestas.

Note

Reikia atskirti nuo DPP dokumentų (Digital Product Passport): jie yra specifiniai DPP ir susieti su pasu (Passport). Files API yra bendro pobūdžio ir gali būti susieta su kodu arba visiškai nesusieta.

Rolės

Operacija	Reikalaujama	Gauna 403
Visi GET	bet kuri rolė	—
POST /upload, PUT /:id	rašymo rolė	viewer
DELETE /:id	trynimo rolė	viewer, contributor

Išskirtinė taisyklė taikoma contributor: ši rolė gali kurti ir keisti, bet negali nieko šalinti.

Caution

Publishable Key (qr3_pk_), nepriklausomai nuo jo taikymo sričių (scopes), visada yra viewer – todėl kliento pusėje įterpti raktai niekada negali įkelti, pakeisti ar ištrinti failų. Įkėlimui reikalingas Secret arba Test raktas su rašymo sritimi (write scope).

Failo įkėlimas

POST /v1/files/upload

Tikimasi multipart/form-data.

Laukas	Privalomas	Aprašymas
file	Taip	Failas
code_id	Ne	Susieti su kodu (turi priklausyti Workspace)
visibility	Ne	private (numatytasis) arba 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
});

Atsakymas (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 yra nustatomas tik esant visibility: "public" ir status: "active". Šiam adresui nereikia prisijungimo ir jis tiesiogiai tinka kaip QR kodo tikslinis URL.

Failų sąrašas

GET /v1/files

Užklausa (Query): code_id ir visibility, abu pasirinktiniai. Grąžina aktyvius Workspace failus, naujausius rodant pirmiausia.

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

Atsakymas (HTTP 200):

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

Caution

Ši pabaigos vieta (endpoint) skiriasi nuo standartinio sąrašo formato: ji nėra puslapiuojama (not paginated) ir negrąžina meta.pagination – visada grąžinami visi rezultatai.

file_count ir total_size_bytes nurodo atfiltruotų rezultatų rinkinį, o ne visą Workspace bendrai. Naudojant ?code_id=… arba ?visibility=…, jie skaičiuoja tik atfiltruotus failus, todėl netinka plano limito saugyklos būsenai tikrinti.

Failo informacijos gavimas

GET /v1/files/:id

Grąžina metaduomenis, įskaitant download_url (ir public_url viešų failų atveju). Prieinama skaityti visoms rolėms.

Failo atsisiuntimas

GET /v1/files/:id/download

Turinys perduodamas srautu (stream) kaip Content-Disposition: attachment su Cache-Control: private, no-store – todėl atsakymas visada yra naujausios būsenos, kitaip nei talpykloje (cache) išsaugotas viešas /f/:id URL.

404 klaida grąžinama dviem atvejais: failas neegzistuoja Workspace (arba yra ištrintas) arba jis egzistuoja, bet trūksta išsaugoto objekto.

Failo pakeitimas

PUT /v1/files/:id

Pakeičia turinį ir išlaiko tą patį id – o kartu ir viešąjį /f/:id bei download_url adresą. Jau atspausdintas QR kodas lieka galioti.

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

visibility, code_id ir created_at išlieka nepakitę; filename, mime_type, size_bytes ir hash_sha256 yra atnaujinami. Plano limitas vienam failui taikomas taip pat, kaip ir įkeliant, o Workspace saugyklos limitas tikrinamas pagal skirtumą. Apribojimas „failų skaičius vienam kodui“ netaikomas, nes naujas failas nėra pridedamas.

Note

Viešasis URL pateikiamas su Cache-Control: public, max-age=300. Todėl po pakeitimo talpykloje (CDN arba naršyklėje) išsaugota versija iki 5 minučių gali rodyti senąjį failą. Autentifikuotas atsisiuntimas naudoja no-store ir yra iškart atnaujintas.

Failo trynimas

DELETE /v1/files/:id

Švelnus trynimas (Soft-Delete): failas iškart dingsta iš sąrašo, tampa nepasiekiamas ir – jei yra viešas – nebeplatinamas adresu /f/:id.

Atsakymas (HTTP 200):

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

Caution

Ištrynimas nėra momentinis viešumo panaikinimas asmeniui, kuris jau turi tiesioginę nuorodą: /f/:id pateikiamas su max-age=300 ir gali rodyti failą dar iki 5 minučių. Priešingai, nukreipimo puslapis nėra talpinamas talpykloje ir iškart nebelygiuoja šio failo.

Užklausa nėra idempotentinė – antrasis DELETE tam pačiam failui grąžins 404.

Limitai

Planas	Maks. vienam failui
Free	5 MB
Pro	25 MB
Business	100 MB
Agency	100 MB
Enterprise	250 MB

Be to, kiekvienam planui taikomas maksimalus failų skaičius vienam kodui ir bendra Workspace saugyklos talpa. Įkėlimo dažnio limitas (rate limit) yra 100 įkėlimų per valandą vienam Workspace.

Klaidos

Statusas	Kada
400	Nežinomas arba netinkamas failo parašas, negaliojantis multipart turinys (body)
401	Nėra arba netinkamas API raktas
403	Rolė neturi teisės rašyti arba trinti
404	code_id arba failo nėra Workspace; atsisiunčiant taip pat: objekto nėra saugykloje
413	Failas didesnis nei plano limitas
422	Trūksta failo, netinkama visibility, pasiektas „failų skaičiaus vienam kodui“ limitas, viršytas Workspace saugyklos limitas
429	Įkėlimo dažnio limitas (100/valandai/Workspace) arba bendras dažnio limitas (rate limit)

Susiję

• Failai ir duomenų lapai — kelias per valdymo skydelį (dashboard)
• Kiekvieno kodo nukreipimo puslapis