Documenti

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.

Condivide l'involucro di istantanea: id, deleted, capturedAt, receivedAt, sequence e gli altri stanno attorno al data qui sotto.

drive-files

{
  "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": "9f2a7c41e8b0d5364a1f8e29b7c30d5e6f14a8b29c7d0e3f5a6b1c8d9e0f2a3b"
    }
  }
}

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.

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 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 diramare. È 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 rende 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 per il comportamento dei tombstone.