Files API

Yleiskatsaus

Files-API isännöi tiedostoja qr3-palvelussa ja tarjoaa niille pysyvän URL-osoitteen. QR-koodi osoittaa tähän URL-osoitteeseen – voit vaihtaa sen takana olevan tiedoston milloin tahansa ilman, että koodia tarvitsee tulostaa uudelleen.

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

Voit valinnaisesti linkittää tiedoston koodiin käyttämällä code_id-tunnusta. Tämä on perusta koodikohtaiselle laskeutumissivulle, joka listaa kaikki koodin julkiset tiedostot.

Tuetut tyypit tarkistetaan magic byte -tunnisteen, ei tiedostopäätteen perusteella: PDF, PNG, JPEG, WebP, MP4, glTF/GLB, JSON. Tiedosto .pdf, joka ei ole oikeasti PDF-tiedosto, hylätään.

Note

Erotuksena DPP-asiakirjoista (Digital Product Passport): Ne ovat DPP-kohtaisia ja sidottu passiporttiin (Passport). Files-API on yleiskäyttöinen ja se voidaan sitoa koodiin tai olla sitomatta mihinkään.

Roolit

Toiminto	Vaadittu rooli	Saa virheen 403
Kaikki GET-pyynnöt	mikä tahansa rooli	—
POST /upload, PUT /:id	kirjoitusrooli	viewer
DELETE /:id	poistorooli	viewer, contributor

Erikoissääntö koskee roolia contributor: tämä rooli saa luoda ja muokata, mutta ei poistaa mitään.

Caution

Publishable Key (qr3_pk_) on sen skoopeista (scopes) riippumatta aina viewer – asiakaspuolelle (client-side) upotetut avaimet eivät siis voi koskaan ladata, korvata tai poistaa tiedostoja. Lataukset (uploads) vaativat Secret- tai Test-avaimen, jolla on kirjoitusskooppi (write scope).

Tiedoston lataaminen palveluun (Upload)

POST /v1/files/upload

Odottaa muotoa multipart/form-data.

Kenttä	Pakollinen	Kuvaus
file	Kyllä	Tiedosto
code_id	Ei	Linkitys koodiin (täytyy kuulua työtilaan / Workspaceen)
visibility	Ei	private (oletus) tai 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
});

Vastaus (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 asetettu vain, kun visibility: "public" ja status: "active". Osoite ei vaadi kirjautumista ja se soveltuu suoraan QR-koodin kohde-URL-osoitteeksi.

Tiedostojen listaaminen

GET /v1/files

Kyselyparametrit (query): code_id ja visibility, molemmat valinnaisia. Palauttaa työtilan (Workspace) aktiiviset tiedostot, uusimmat ensin.

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

Vastaus (HTTP 200):

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

Caution

Tämä päätepiste (endpoint) poikkeaa standardista listamuodosta: se ei ole sivutettu (paginated) eikä se palauta kenttää meta.pagination – kaikki tulokset palautetaan aina kerralla.

file_count ja total_size_bytes viittaavat suodatettuun tulosjoukkoon, eivät koko työtilaan (Workspace). Parametreilla ?code_id=… tai ?visibility=… ne laskevat vain suodatetut tiedostot, eivätkä ne siten sovellu tilauksen (Plan) tallennustilan käytön tarkistamiseen.

Tiedoston tietojen haku

GET /v1/files/:id

Palauttaa metatiedot mukaan lukien download_url (ja public_url julkisille tiedostoille). Luettavissa kaikilla rooleilla.

Tiedoston lataaminen laitteelle (Download)

GET /v1/files/:id/download

Striimaa sisällön muodossa Content-Disposition: attachment otsikolla Cache-Control: private, no-store – vastaus on siis aina ajantasainen versio, toisin kuin välimuistiin tallennettu julkinen /f/:id-URL.

Virhekoodi 404 voi johtua kahdesta syystä: tiedostoa ei ole työtilassa (tai se on poistettu) tai se on olemassa, mutta tallennettu objekti puuttuu.

Tiedoston korvaaminen

PUT /v1/files/:id

Korvaa sisällön ja säilyttää tunnuksen id – ja siten myös julkisen /f/:id- ja download_url-osoitteen. Jo tulostettu QR-koodi pysyy voimassa.

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äilyvät ennallaan; filename, mime_type, size_bytes ja hash_sha256 päivitetään. Tiedostokohtainen tilausraja (Plan-limit) pätee kuten latauksessa, ja työtilan tallennustilarajaa vasten tarkistetaan erotus. Rajoitus ”tiedostoja per koodi” ei päde, koska uusia tiedostoja ei lisätä.

Note

Julkinen URL toimitetaan otsikolla Cache-Control: public, max-age=300. Korvaamisen jälkeen välimuistiin tallennettu CDN- tai selainversio saattaa siksi näyttää vanhan tiedoston jopa 5 minuutin ajan. Tunnistautunut lataus käyttää arvoa no-store ja on heti ajantasainen.

Tiedoston poistaminen

DELETE /v1/files/:id

Pehmeä poisto (Soft-Delete): Tiedosto katoaa välittömästi listalta, sitä ei voi enää hakea, eikä sitä – jos se on julkinen – enää tarjota osoitteessa /f/:id.

Vastaus (HTTP 200):

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

Caution

Poistaminen ei poista julkaisua välittömästi sellaiselta käyttäjältä, jolla on jo suora linkki: /f/:id toimitetaan arvolla max-age=300 ja se voi näyttää tiedoston vielä jopa 5 minuutin ajan. Laskeutumissivua taas ei tallenneta välimuistiin, ja se lakkaa näyttämästä tiedostoa välittömästi.

Kutsu ei ole idempotentti – toinen DELETE-pyyntö samalle tiedostolle palauttaa virheen 404.

Rajoitukset

Tilaus (Plan)	Enintään per tiedosto
Free	5 MB
Pro	25 MB
Business	100 MB
Agency	100 MB
Enterprise	250 MB

Lisäksi kussakin tilauksessa (Plan) on koodikohtainen tiedostojen enimmäismäärä ja työtilakohtainen (Workspace) kokonaistallennustila. Latausten (Upload) siirtonopeusrajoitus on 100 latausta tunnissa työtilaa kohden.

Virheet

Tila	Milloin
400	Tuntematon tai virheellinen tiedoston allekirjoitus (signature), virheellinen multipart-runko
401	API-avain puuttuu tai on virheellinen
403	Roolilla ei ole kirjoitus- tai poisto-oikeutta
404	code_id tai tiedosto ei ole työtilassa; latauksen yhteydessä myös: objekti puuttuu tallennustilasta
413	Tiedosto on suurempi kuin tilauksen (Plan) raja
422	Tiedosto puuttuu, virheellinen visibility, ”tiedostoja per koodi” -raja saavutettu, työtilan tallennustilaraja ylittynyt
429	Latausrajoitus (100/tunti/työtila) tai yleinen pyyntörajoitus (Rate-Limit)

Aiheeseen liittyvää

• Tiedostot & tuoteselosteet — hallintapaneelin (Dashboard) kautta
• Koodikohtainen laskeutumissivu