Files API

Ülevaade

Files API majutab faile qr3-s ja pakub selleks stabiilset URL-i. QR-kood viitab sellele URL-ile — selle taga olevat faili saad igal ajal asendada ilma koodi uuesti trükkimata.

Baas-URL: https://qr3.app/v1/files

Soovi korral saad faili siduda koodiga parameetri code_id abil. See on aluseks maandumislehele koodi kohta, mis loetleb kõik koodi avalikud failid.

Toetatud tüüpe kontrollitakse maagiliste baitide (magic bytes), mitte failinime järgi: PDF, PNG, JPEG, WebP, MP4, glTF/GLB, JSON. Fail .pdf, mis ei ole tegelikult PDF, lükatakse tagasi.

Note

Eristada tuleb DPP-dokumentidest (Digital Product Passport): need on DPP-spetsiifilised ja seotud passiga (Passport). Files API on geneeriline ja seotud koodiga või mitte millegagi.

Rollid

Operatsioon	Nõutav	Saab vastuseks 403
Kõik GET	mis tahes roll	—
POST /upload, PUT /:id	kirjutamisroll	viewer
DELETE /:id	kustutamisroll	viewer, contributor

Erandreegel kehtib rollile contributor: see roll tohib luua ja muuta, kuid mitte midagi eemaldada.

Caution

Publishable Key (qr3_pk_) on sõltumata oma skoobist (scopes) alati viewer — seega ei saa kliendipoolselt integreeritud võtmed kunagi faile üles laadida, asendada ega kustutada. Üleslaadimiseks on vaja Secret- või Test-võtit koos kirjutamisandmete skoobiga (write scope).

Faili üleslaadimine

POST /v1/files/upload

Ootab päringut tüübiga multipart/form-data.

Väli	Kohustuslik	Kirjeldus
file	Jah	Fail
code_id	Ei	Sidumine koodiga (peab kuuluma Workspace’i)
visibility	Ei	private (vaikimisi) või 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
});

Vastus (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 on määratud ainult siis, kui visibility: "public" ja status: "active". Aadress ei nõua sisselogimist ja sobib otse QR-koodi siht-URL-iks.

Failide loetlemine

GET /v1/files

Päringuparameetrid (Query): code_id ja visibility, mõlemad valikulised. Tagastab Workspace’i aktiivsed failid, uusimad eespool.

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

Vastus (HTTP 200):

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

Caution

See lõpp-punkt (endpoint) erineb tavapärasest loendivormingust: see ei kasuta lehekülgi (pagination) ega tagasta objekti meta.pagination — alati tagastatakse kõik tulemused.

file_count ja total_size_bytes viitavad filtreeritud tulemuste hulgale, mitte kogu Workspace’ile. Kasutades parameetreid ?code_id=… või ?visibility=…, loendavad need ainult filtreeritud faile ega sobi seetõttu paketi mahupiirangu (Plan-Limit) kontrollimiseks.

Faili andmete pärimine

GET /v1/files/:id

Tagastab metaandmed, sealhulgas download_url (ja avalike failide puhul public_url). Loetav kõikidele rollidele.

Faili allalaadimine

GET /v1/files/:id/download

Edastab sisu voona (stream) päisega Content-Disposition: attachment ja Cache-Control: private, no-store — seega on vastus alati uusim versioon, erinevalt vahemällu salvestatud avalikust /f/:id URL-ist.

404 tagastatakse kahel juhul: faili ei eksisteeri Workspace’is (või see on kustutatud) või fail on olemas, kuid salvestatud objekt puudub.

Faili asendamine

PUT /v1/files/:id

Asendab sisu ja säilitab id — ning seega ka avaliku /f/:id ja download_url aadressi. Juba trükitud QR-kood jääb kehtima.

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

visibility, code_id ja created_at säilivad; filename, mime_type, size_bytes ja hash_sha256 uuendatakse. Failipõhine paketi piirang (Plan-Limit) kehtib samamoodi nagu üleslaadimisel, Workspace’i mahupiirangut kontrollitakse vahe (differentsi) suhtes. Piirang “faile koodi kohta” ei kehti, kuna uusi faile juurde ei teki.

Note

Avalik URL väljastatakse päisega Cache-Control: public, max-age=300. Pärast asendamist võib vahemällu salvestatud CDN-i või brauseri versioon seetõttu kuni 5 minutit vana faili kuvada. Autenditud allalaadimine kasutab reeglit no-store ja on koheselt ajakohane.

Faili kustutamine

DELETE /v1/files/:id

Pehme kustutamine (Soft-Delete): fail kaob koheselt loendist, ei ole enam kättesaadav ja seda ei väljastata — kui see oli avalik — enam aadressil /f/:id.

Vastus (HTTP 200):

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

Caution

Kustutamine ei tähenda kohest avaldamise tühistamist kellegi jaoks, kellel on juba otsene link: /f/:id väljastatakse päisega max-age=300 ja see võib faili veel kuni 5 minutit kuvada. Seevastu maandumislehte vahemällu ei salvestata ja see lõpetab faili kuvamise koheselt.

Päring ei ole idempotentne — teine DELETE päring samale failile tagastab vastuseks 404.

Piirangud

Pakett	Max faili kohta
Free	5 MB
Pro	25 MB
Business	100 MB
Agency	100 MB
Enterprise	250 MB

Lisaks kehtib iga paketi puhul maksimaalne failide arv koodi kohta ja kogumaht Workspace’i kohta. Üleslaadimise sageduspiirang (Ratelimit) on 100 üleslaadimist tunnis Workspace’i kohta.

Tõrked

Staatus	Millal
400	Tundmatu või mittesobiv failiallkiri (signature), vigane multipart-päringu sisu (body)
401	API-võti puudub või on vigane
403	Rollil puudub kirjutamis- või kustutamisõigus
404	code_id või fail ei ole Workspace’is; allalaadimisel ka: objekt puudub salvestusruumist
413	Fail on suurem kui paketi piirang
422	Fail puudub, vigane visibility, piirang “faile koodi kohta” on saavutatud, Workspace’i mahupiirang on ületatud
429	Üleslaadimise sageduspiirang (100/tunnis/Workspace) või üldine sageduspiirang (Rate-Limit)

Seotud teemad

• Failid ja andmelehed — juhtpaneeli (Dashboard) kaudu
• Maandumisleht koodi kohta