# Documenti

> L'archivio documenti del ristorante (certificati, procedure, report), dove ogni record è un file archiviato con il proprio tipo di media.

Source: https://developers.backresto.com/it/docs/drive-files

Ogni ristorante tiene della carta accanto ai controlli: certificati dei
fornitori, procedure di pulizia, l'ultimo verbale di ispezione, un piano
firmato. L'app dà loro un posto dove archiviarla, e questa collezione è quello
schedario: un record per documento, ciascuno che punta al file stesso.

| Collezione | Scope | Che cos'è un record |
| --- | --- | --- |
| `drive-files` | `drive-files:read` | Un documento archiviato nell'archivio documenti del ristorante. |

Condivide l'[involucro di snapshot](https://developers.backresto.com/it/docs/collections): `id`, `deleted`,
`capturedAt`, `receivedAt`, `sequence` e gli altri stanno attorno al `data` qui
sotto.

## `drive-files`

| Campo | Tipo | Significato |
| --- | --- | --- |
| `s3Key` | string, **obbligatorio** | Dove si trova il documento nell'archivio. Una chiave, non un URL. Fino a 1024 caratteri. |
| `name` | string, **obbligatorio** | Il nome del file come lo vede il ristorante. |
| `sizeBytes` | number, **obbligatorio** | Dimensione del documento in byte. |
| `contentType` | string \| null | Il tipo di media che l'app ha registrato. Può mancare. |
| `asset` | object | Il file. Legga la sezione successiva. |

```json
{
  "id": "a94c7e51-3f60-4b2d-8e17-05c9d3a6f482",
  "collection": "drive-files",
  "deleted": false,
  "capturedAt": "1789743015220",
  "receivedAt": "1789743098644",
  "sequence": "97",
  "data": {
    "s3Key": "drive/fournisseurs/attestation-metro-2026.pdf",
    "name": "Attestation Metro 2026.pdf",
    "sizeBytes": 184320,
    "contentType": "application/pdf",
    "asset": {
      "objectKey": "restaurants/36eaa3fa/drive/a17c93be4f02",
      "status": "uploaded",
      "contentType": "application/pdf",
      "byteLength": 184320,
      "sha256": "9f2a…"
    }
  }
}
```

In `data` non c'è alcun `timestamp`. Quando il documento è stato archiviato è
`capturedAt` sull'involucro, come in ogni altra collezione.

## Il file è il punto

Altrove il record è l'informazione e il file è la prova. Qui è il contrario:
cinque campi descrivono un documento il cui contenuto è l'intera ragione per cui
qualcuno legge questa collezione. Quindi quasi sempre seguirà il record fino ai
byte.

```http
GET /v1/restaurants/{restaurantId}/collections/drive-files/records/{recordId}/assets
```

URL firmati validi per **quindici minuti**, ciascuno con la propria
autorizzazione. [La pagina sulle collezioni](https://developers.backresto.com/it/docs/collections) contiene le
regole, e due di esse contano qui più che altrove:

- **`sha256` le permette di saltare un download.** È il digest dei byte. Un
  certificato che non è cambiato dal suo ultimo percorso non ha bisogno di
  essere scaricato di nuovo, e i documenti sono le cose più grandi che questa
  API le consegnerà.
- **Scarichi adesso, conservi i byte, mai il collegamento.** Quindici minuti
  sono abbastanza lunghi per scaricare e abbastanza brevi perché un URL nel suo
  database sia un collegamento morto la mattina dopo.

**`asset` descrive il file; solo l'endpoint glielo consegna.** Porta
`objectKey`, `status`, `contentType`, `byteLength` e `sha256`: abbastanza per
decidere se vuole i byte, e nessun URL, perché un URL che non scadesse mai
sarebbe un collegamento permanente e non autenticato ai documenti di un
ristorante.

`status` è il campo su cui basare la logica. È `uploaded` una volta che i byte
sono arrivati e sono stati verificati, ed è `pending` finché un dispositivo li
sta ancora inviando. Un asset `pending` è assente dall'endpoint degli asset, il
che è corretto anziché rotto: richieda di nuovo più tardi anziché trattarlo come
un documento mancante. `asset` è anche l'unico campo qui che può mancare del
tutto: un record archiviato senza ancora un file.

## Queste non sono immagini

Una prova di pulizia è una fotografia. Un documento è qualunque cosa il
ristorante abbia archiviato: un certificato PDF, un export di temperature in
Excel o CSV, una procedura Word, una scansione fatta con il telefono. Qui
arriva di tutto.

**Legga `contentType` anziché darne per scontato uno.** Nel record ammette null
(l'app non sempre ce l'ha), quindi quando è null prenda invece il
`contentType` dall'asset; quello è il tipo di media dell'oggetto effettivamente
archiviato, ed è quello di cui fidarsi quando i due non concordano. Un client
che visualizza tutto come un'immagine, o salva tutto come `.pdf`, si rompe al
primo foglio di calcolo.

**E non deduca il tipo nemmeno da `name` o da `s3Key`.** Un'estensione è una
convenzione, non una garanzia, ed entrambi i campi sono testo libero scritto da
una persona che nomina un file su un tablet.

## Archiviarli dalla sua parte

**`s3Key` è una chiave, non un indirizzo.** Identifica l'oggetto
nell'archivio: non ha schema, non ha host e non ha uno slash iniziale, e non
può scaricarlo. Ogni byte che ottiene arriva dall'endpoint degli asset.

**Usi come chiave l'`id` dell'involucro, non `name`.** Niente impedisce che due
documenti si chiamino `Attestation 2026.pdf`, nello stesso ristorante,
archiviati a un anno di distanza.

**Vale la pena leggere `sizeBytes` prima di scaricare.** È il modo più economico
per decidere se scaricare una scansione da 40 MB su una connessione mobile. Il
`byteLength` dell'oggetto archiviato, sull'asset, è quello che fa fede.

**Un tombstone si porta via il file.** `deleted: true` significa che il
documento è stato rimosso nell'app, e i suoi asset smettono di essere elencati.
Se le serviva quel certificato, le servivano i byte. Veda
[la pagina sull'involucro](https://developers.backresto.com/it/docs/collections) per il comportamento dei
tombstone.