Files API

Forbhreathnú

Óstálann an Files API comhaid ar qr3 agus soláthraíonn sé URL seasmhach dóibh. Pointeann an cód QR chuig an URL seo — is féidir leat an comhad taobh thiar de a mhalartú ag am ar bith gan an cód a athphriontáil.

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

Roghnach, is féidir leat comhad a nascadh le cód trí code_id. Is é seo an bunús don leathanach tulaigh in aghaidh an chóid, a liostaíonn gach comhad poiblí de chuid cóid.

Déantar cineálacha tacaithe a sheiceáil trí bhíthin “magic byte”, ní de réir ainm an chomhaid: PDF, PNG, JPEG, WebP, MP4, glTF/GLB, JSON. Diúltófar do .pdf nach PDF é.

Note

Le hidirdhealú a dhéanamh ó dhoiciméid DPP (Digital Product Passport): Tá siad seo sainiúil do DPP agus nasctha le Passport. Tá an Files API cineálach agus nasctha le cód nó gan a bheith nasctha le haon rud ar chor ar bith.

Róil

Oibríocht	Riachtanach	Faigheann 403
Gach GET	gach ról	—
POST /upload, PUT /:id	ról scríofa	viewer
DELETE /:id	ról scriosta	viewer, contributor

Is é an riail speisialta ná contributor: Tá cead ag an ról seo cruthú agus athrú, ach níl cead aige aon rud a bhaint.

Caution

Is viewer i gcónaí é Publishable Key (qr3_pk_), beag beann ar a scóip — mar sin ní féidir le heochracha atá leabaithe ar thaobh an chliaint uaslódáil, athsholáthar ná scriosadh a dhéanamh choíche. Teastaíonn Secret Key nó Test Key le scóip scríofa le haghaidh uaslódálacha.

Comhad a uaslódáil

POST /v1/files/upload

Ag súil le multipart/form-data.

Réimse	Riachtanach	Cur síos
file	Tá	An comhad
code_id	Níl	Nasc le cód (caithfidh sé a bheith mar chuid den Workspace)
visibility	Níl	private (Réamhshocrú) nó 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
});

Freagra (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" }
}

Ní shocraítear public_url ach amháin le haghaidh visibility: "public" agus status: "active". Ní gá logáil isteach don seoladh seo agus tá sé oiriúnach go díreach mar sprioc-URL do chód QR.

Comhaid a liostú

GET /v1/files

Iarratas (Query): code_id agus visibility, an dá cheann roghnach. Seolann sé comhaid ghníomhacha an Workspace ar ais, na cinn is nuaí ar dtús.

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

Freagra (HTTP 200):

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

Caution

Sraonann an críochphointe seo ón bhformáid chaighdeánach liosta: Níl sé leathanachaithe agus ní sholáthraíonn sé meta.pagination — seoltar gach meaitseáil ar ais i gcónaí.

Tagraíonn file_count agus total_size_bytes don tacar torthaí scagtha, ní don Workspace iomlán. Le ?code_id=… nó ?visibility=…, ní chomhaircann siad ach na comhaid scagtha agus mar sin níl siad oiriúnach mar stádas stórála don teorainn phlean.

Sonraí comhaid a fháil

GET /v1/files/:id

Soláthraíonn sé na meiteadata lena n-áirítear download_url (agus public_url i gcás comhad poiblí). Inléite ag gach ról.

Comhad a íoslódáil

GET /v1/files/:id/download

Sruthaíonn sé an t-ábhar mar Content-Disposition: attachment le Cache-Control: private, no-store — mar sin is é an freagra an stádas reatha i gcónaí, murab ionann agus an URL poiblí /f/:id atá i dtaisce.

Tagann 404 ar dhá bhealach: Níl an comhad ann sa Workspace (nó tá sé scriosta), nó tá sé ann ach tá an réad stóráilte ar iarraidh.

Comhad a athsholáthar

PUT /v1/files/:id

Malartaíonn sé an t-ábhar agus coinníonn sé an id — agus mar sin an seoladh poiblí /f/:id agus an seoladh download_url. Fanann cód QR atá clóite cheana féin bailí.

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

Coinnítear visibility, code_id agus created_at; déantar filename, mime_type, size_bytes agus hash_sha256 a nuashonrú. Tá feidhm ag teorainn an phlean in aghaidh an chomhaid mar a bheadh le linn uaslódála, déantar teorainn stórála an Workspace a sheiceáil i gcoinne an difríochta. Níl feidhm ag an teorainn “Comhaid in aghaidh an chóid”, mar nach bhfuil aon chomhad nua á chur leis.

Note

Soláthraítear an URL poiblí le Cache-Control: public, max-age=300. Tar éis athsholáthair, mar sin, is féidir le leagan CDN nó brabhsálaí atá i dtaisce an seanchomhad a thaispeáint ar feadh suas le 5 nóiméad. Tá an t-íoslódáil fíordheimhnithe socraithe mar no-store agus tá sé cothrom le dáta láithreach.

Comhad a scriosadh

DELETE /v1/files/:id

Soft-Delete: Imíonn an comhad as an liosta láithreach, ní féidir é a rochtain a thuilleadh agus — má tá sé poiblí — ní sholáthrófar é faoi /f/:id a thuilleadh.

Freagra (HTTP 200):

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

Caution

Ní hionann scriosadh agus dífhoilsiú láithreach do dhuine a bhfuil an nasc díreach aige cheana féin: soláthraítear /f/:id le max-age=300 agus is féidir leis an comhad a thaispeáint fós ar feadh suas le 5 nóiméad. Ar an láimh eile, ní chuirtear an leathanach tulaigh i dtaisce agus stopann sé de bheith ag taispeáint an chomhaid láithreach.

Níl an glao seo idimpotant — tabharfaidh dara DELETE ar an gcomhad céanna 404.

Teorainneacha

Plean	Max. in aghaidh an chomhaid
Free	5 MB
Pro	25 MB
Business	100 MB
Agency	100 MB
Enterprise	250 MB

Ina theannta sin, tá uaslíon comhad in aghaidh an chóid agus stóráil iomlán in aghaidh an Workspace i bhfeidhm do gach plean. Is é 100 uaslódáil in aghaidh na huaire in aghaidh an Workspace an teorainn ráta uaslódála.

Earráidí

Stádas	Cathain
400	Síniú comhaid anaithnid nó neamh-chomhoiriúnach, corp multipart neamhbhailí
401	Gan API-Key nó API-Key neamhbhailí
403	Níl cead ag an ról scríobh nó scriosadh
404	code_id nó comhad nach bhfuil sa Workspace; le linn íoslódála freisin: réad ar iarraidh sa stóráil
413	Comhad níos mó ná teorainn an phlean
422	Comhad ar iarraidh, visibility neamhbhailí, teorainn “Comhaid in aghaidh an chóid” bainte amach, teorainn stórála an Workspace sáraithe
429	Teorainn ráta uaslódála (100/uair/Workspace) nó teorainn ráta ghinearálta

Ábhar Gaolmhar

• Comhaid & Bileoga Sonraí — an bealach tríd an deais
• Leathanach tulaigh in aghaidh an chóid