Files API

Ħarsa ġenerali

Il-Files API tospita fajls fuq qr3 u tipprovdi URL stabbli għalihom. Il-QR code jipponta lejn din il-URL — tista’ tbiddel il-fajl warajha fi kwalunkwe ħin mingħajr ma terġa’ tipprintja l-code.

URL Bażika: https://qr3.app/v1/files

B’mod mhux obbligatorju, tista’ tikkoppla fajl ma’ code permezz ta’ code_id. Din hija l-bażi għal- landing page għal kull code, li telenka l-fajls pubbliċi kollha ta’ code.

It-tipi appoġġjati jiġu vverifikati permezz ta’ magic byte, mhux mill-isem tal-fajl: PDF, PNG, JPEG, WebP, MP4, glTF/GLB, JSON. Fajl .pdf li mhuwiex PDF jiġi rrifjutat.

Note

Għandu jiġi distint mid-dokumenti tad-DPP (Digital Product Passport): Dawn huma speċifiċi għad-DPP u marbuta ma’ Passport. Il-Files API hija ġenerika u marbuta ma’ code jew ma’ xejn affattu.

Rwoli

Operazzjoni	Meħtieġ	Jirċievi 403
Il-GET kollha	kwalunkwe rwol	—
POST /upload, PUT /:id	rwol ta’ kitba	viewer
DELETE /:id	rwol ta’ tħassir	viewer, contributor

Ir-regola speċjali hija contributor: Dan ir-rwol jista’ joħloq u jimmodifika, iżda ma jista’ jneħħi xejn.

Caution

Publishable Key (qr3_pk_) huwa dejjem viewer irrispettivament mill-iscopes tiegħu — għalhekk keys inkorporati fuq in-naħa tal-klijent qatt ma jistgħu jtellgħu, jissostitwixxu jew iħassru. L-uploads jeħtieġu Secret Key jew Test Key bi scope ta’ kitba.

Tella’ fajl

POST /v1/files/upload

Jistenna multipart/form-data.

Kamp	Obbligatorju	Deskrizzjoni
file	Iva	Il-fajl
code_id	Le	Ikkoppla ma’ code (għandu jappartjeni għall-workspace)
visibility	Le	private (default) jew 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
});

Response (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 hija ssettjata biss f’każ ta’ visibility: "public" u status: "active". L-indirizz m’għandux bżonn login u huwa adattat direttament bħala l-URL tad-destinazzjoni ta’ QR code.

Elenka l-fajls

GET /v1/files

Query: code_id u visibility, it-tnejn mhux obbligatorji. Jirritorna l-fajls attivi tal-workspace, bl-aktar wieħed reċenti l-ewwel.

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

Response (HTTP 200):

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

Caution

Dan l-endpoint ivarja mill-format standard tal-lista: Mhuwiex pajinat u ma jipprovdix meta.pagination — dejjem jiġu rritornati r-riżultati kollha.

file_count u total_size_bytes jirreferu għas-sett ta’ riżultati ffiltrati, mhux għall-workspace kollu kemm hu. B’ ?code_id=… jew ?visibility=… huma jgħoddu biss il-fajls iffiltrati u għalhekk ma jservux bħala indikatur tal-użu tal-ħażna għal-limitu tal-pjan.

Ikseb informazzjoni dwar il-fajl

GET /v1/files/:id

Jirritorna l-metadata inkluż download_url (u public_url f’każ ta’ fajls pubbliċi). Jista’ jinqara mir-rwoli kollha.

Niżżel il-fajl

GET /v1/files/:id/download

Jittrażmetti l-kontenut bħala stream b’ Content-Disposition: attachment u Cache-Control: private, no-store — għalhekk ir-rispons huwa dejjem l-aktar stat reċenti, b’differenza mill-URL pubblika /f/:id li tkun cached.

404 jiġri f’żewġ każijiet: Il-fajl ma jeżistix fil-workspace (jew huwa mħassar), jew jeżisti iżda l-oġġett maħżun huwa nieqes.

Ibdel il-fajl

PUT /v1/files/:id

Ibdel il-kontenut u żomm l-id — u b’hekk l-indirizz pubbliku /f/:id u d-download_url jibqgħu l-istess. QR code li diġà ġie stampat jibqa’ validu.

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

visibility, code_id u created_at jinżammu; filename, mime_type, size_bytes u hash_sha256 jiġu aġġornati. Il-limitu tal-pjan għal kull fajl japplika bħal fl-upload, u l-limitu tal-ħażna tal-workspace jiġi vverifikat kontra d-differenza. Il-limitu ta’ “fajls għal kull code” ma japplikax, peress li ma qed jiżdied l-ebda fajl ġdid.

Note

Il-URL pubblika tiġi pprovduta b’ Cache-Control: public, max-age=300. Wara sostituzzjoni, verżjoni cached fuq CDN jew fil-browser tista’ għalhekk turi l-fajl il-qadim sa 5 minuti. Id-download awtentikat huwa no-store u jiġi aġġornat immedjatament.

Ħassar il-fajl

DELETE /v1/files/:id

Soft-Delete: Il-fajl jisparixxi immedjatament mil-lista, ma jibqax aċċessibbli u — jekk ikun pubbliku — ma jibqax ipprovdut taħt /f/:id.

Response (HTTP 200):

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

Caution

It-tħassir mhuwiex depubblikazzjoni immedjata għal xi ħadd li diġà għandu l-link diretta: /f/:id tiġi pprovduta b’ max-age=300 u tista’ tkompli turi l-fajl sa 5 minuti. Min-naħa l-oħra, il-landing page mhijiex cached u tieqaf turi l-fajl immedjatament.

Is-sejħa mhijiex idempotenti — it-tieni DELETE fuq l-istess fajl tirritorna 404.

Limiti

Pjan	Max. għal kull fajl
Free	5 MB
Pro	25 MB
Business	100 MB
Agency	100 MB
Enterprise	250 MB

Barra minn hekk, japplikaw numru massimu ta’ fajls għal kull code u ħażna totali għal kull workspace skont il-pjan. Il-limitu tar-rata tal-uploads huwa ta’ 100 upload fis-siegħa għal kull workspace.

Żbalji

Status	Meta
400	Firma tal-fajl mhux magħrufa jew mhux xierqa, multipart body invalidu
401	API key nieqsa jew invalida
403	Ir-rwol m’għandux permess jikteb jew iħassar
404	code_id jew fajl mhux fil-workspace; waqt id-download ukoll: l-oġġett huwa nieqes mill-ħażna
413	Il-fajl huwa akbar mil-limitu tal-pjan
422	Fajl nieqes, visibility invalida, intlaħaq il-limitu ta’ “fajls għal kull code”, inqabeż il-limitu tal-ħażna tal-workspace
429	Limitu tar-rata tal-uploads (100/siegħa/workspace) jew limitu tar-rata ġenerali

Relatati

• Fajls u Skedi ta’ Data — il-metodu permezz tad-dashboard
• Landing page għal kull code