API Files

Panoramica

L’API Files ospita file su qr3 e fornisce un URL stabile. Il codice QR punta a questo URL: puoi sostituire il file sottostante in qualsiasi momento senza dover ristampare il codice.

URL di base: https://qr3.app/v1/files

Facoltativamente, puoi collegare un file a un codice tramite code_id. Questa è la base per la landing page per codice, che elenca tutti i file pubblici di un codice.

I tipi supportati vengono verificati tramite magic byte, non dall’estensione del file: PDF, PNG, JPEG, WebP, MP4, glTF/GLB, JSON. Un file .pdf che non è un vero PDF verrà rifiutato.

Nota

Da distinguere dai documenti DPP (Digital Product Passport): questi ultimi sono specifici per il DPP e legati a un passaporto. L’API Files è generica e può essere legata a un codice o a nulla.

Ruoli

Operazione	Richiesto	Riceve 403
Tutti i GET	qualsiasi ruolo	—
POST /upload, PUT /:id	ruolo di scrittura	viewer
DELETE /:id	ruolo di eliminazione	viewer, contributor

La regola speciale si applica a contributor: questo ruolo può creare e modificare, ma non eliminare nulla.

Attenzione

Una Publishable Key (qr3_pk_) è sempre viewer indipendentemente dai suoi scope; pertanto, le chiavi incorporate lato client non possono mai caricare, sostituire o eliminare file. I caricamenti richiedono una Secret Key o Test Key con scope di scrittura.

Caricare un file

POST /v1/files/upload

Richiede multipart/form-data.

Campo	Obbligatorio	Descrizione
file	Sì	Il file
code_id	No	Collega a un codice (deve appartenere al Workspace)
visibility	No	private (predefinito) o 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
});

Risposta (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 è impostato solo con visibility: "public" e status: "active". L’indirizzo non richiede autenticazione ed è adatto direttamente come URL di destinazione di un codice QR.

Elencare i file

GET /v1/files

Query: code_id e visibility, entrambi opzionali. Restituisce i file attivi del Workspace, a partire dal più recente.

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

Risposta (HTTP 200):

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

Attenzione

Questo endpoint differisce dal formato di elenco standard: non è paginato e non fornisce meta.pagination — vengono sempre restituiti tutti i risultati.

file_count e total_size_bytes si riferiscono all’insieme dei risultati filtrati, non al Workspace nel suo complesso. Con ?code_id=… o ?visibility=…, conteggiano solo i file filtrati e quindi non sono indicativi per verificare il limite di archiviazione del piano.

Recuperare informazioni sul file

GET /v1/files/:id

Restituisce i metadati inclusi download_url (e public_url per i file pubblici). Leggibile da tutti i ruoli.

Scaricare un file

GET /v1/files/:id/download

Invia il contenuto in streaming come Content-Disposition: attachment con Cache-Control: private, no-store — la risposta rappresenta quindi sempre lo stato più recente, a differenza dell’URL pubblico /f/:id memorizzato nella cache.

L’errore 404 può verificarsi in due casi: il file non esiste nel Workspace (or è stato eliminato), oppure esiste ma l’oggetto memorizzato non è presente.

Sostituire un file

PUT /v1/files/:id

Sostituisce il contenuto e mantiene l’ id — e di conseguenza l’indirizzo pubblico /f/:id e il download_url. Un codice QR già stampato rimane valido.

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

visibility, code_id e created_at rimangono invariati; filename, mime_type, size_bytes e hash_sha256 vengono aggiornati. Il limite del piano per file si applica come per il caricamento, mentre il limite di archiviazione del Workspace viene verificato rispetto alla differenza. Il limite “file per codice” non si applica, poiché non viene aggiunto alcun nuovo file.

Nota

L’URL pubblico viene servito con Cache-Control: public, max-age=300. Dopo una sostituzione, una versione memorizzata nella cache della CDN o del browser potrebbe quindi mostrare il vecchio file per un massimo di 5 minuti. Il download autenticato è no-store e immediatamente aggiornato.

Eliminare un file

DELETE /v1/files/:id

Soft-delete: il file scompare immediatamente dall’elenco, non è più accessibile e — se pubblico — non viene più servito all’indirizzo /f/:id.

Risposta (HTTP 200):

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

Attenzione

L’eliminazione non comporta una rimozione pubblica immediata per chi possiede già il link directo: /f/:id viene servito con max-age=300 e potrebbe mostrare il file ancora per un massimo di 5 minuti. La landing page, invece, non viene memorizzata nella cache e smette immediatamente di mostrare il file.

La chiamata non è idempotente — una seconda richiesta DELETE sullo stesso file restituirà 404.

Limiti

Piano	Max per file
Free	5 MB
Pro	25 MB
Business	100 MB
Agency	100 MB
Enterprise	250 MB

Inoltre, a seconda del piano, si applicano un numero massimo di file per codice e uno spazio di archiviazione totale per Workspace. Il limite di frequenza per i caricamenti è di 100 caricamenti all’ora per Workspace.

Errori

Stato	Quando
400	Firma del file sconosciuta o non corrispondente, corpo multipart non valido
401	Chiave API mancante o non valida
403	Il ruolo non ha i permessi di scrittura o di eliminazione
404	code_id o file non presente nel Workspace; per il download anche: oggetto mancante nell’archiviazione
413	File più grande del limite del piano
422	File mancante, visibility non valida, limite “file per codice” raggiunto, limite di archiviazione del Workspace superato
429	Limite di frequenza di caricamento (100/ora/Workspace) o limite di frequenza generale

Correlati

• File e schede tecniche — la procedura tramite la dashboard
• Landing page per codice