# Documents

> L'espace documentaire du restaurant (attestations, procédures, rapports), chaque enregistrement étant un fichier classé, avec son propre type de média.

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

Chaque restaurant garde du papier à côté des contrôles : attestations de
fournisseurs, procédures de nettoyage, le dernier rapport d'inspection, un plan
signé. L'application leur donne un endroit où le classer, et cette collection
est ce classeur : un enregistrement par document, chacun pointant vers le
fichier lui-même.

| Collection | Scope | Ce qu'est un enregistrement |
| --- | --- | --- |
| `drive-files` | `drive-files:read` | Un document classé dans l'espace documentaire du restaurant. |

Elle partage l'[enveloppe de snapshot](https://developers.backresto.com/fr/docs/collections) : `id`, `deleted`,
`capturedAt`, `receivedAt`, `sequence` et le reste entourent le `data`
ci-dessous.

## `drive-files`

| Champ | Type | Signification |
| --- | --- | --- |
| `s3Key` | string, **obligatoire** | Où le document se trouve dans le stockage. Une clé, pas une URL. Jusqu'à 1024 caractères. |
| `name` | string, **obligatoire** | Le nom du fichier tel que le restaurant le voit. |
| `sizeBytes` | number, **obligatoire** | La taille du document, en octets. |
| `contentType` | string \| null | Le type de média que l'application a enregistré. Peut manquer. |
| `asset` | object | Le fichier. Lisez la section suivante. |

```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…"
    }
  }
}
```

Il n'y a pas de `timestamp` dans `data`. La date de classement du document,
c'est `capturedAt` sur l'enveloppe, comme dans toutes les autres collections.

## Le fichier est l'essentiel

Ailleurs, l'enregistrement est l'information et le fichier est la preuve. Ici,
c'est l'inverse : cinq champs décrivent un document dont le contenu est toute
la raison pour laquelle on lit cette collection. Vous suivrez donc presque
toujours l'enregistrement jusqu'aux octets.

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

Des URL signées valables **quinze minutes**, portant chacune sa propre
autorisation. [La page des collections](https://developers.backresto.com/fr/docs/collections) en donne les règles,
et deux d'entre elles comptent plus ici qu'ailleurs :

- **`sha256` vous évite un téléchargement.** C'est l'empreinte des octets. Une
  attestation qui n'a pas changé depuis votre dernier parcours n'a pas besoin
  d'être récupérée à nouveau, et les documents sont les plus gros objets que
  cette API vous rendra.
- **Récupérez maintenant, stockez les octets, jamais le lien.** Quinze minutes,
  c'est assez long pour télécharger et assez court pour qu'une URL dans votre
  base de données soit un lien mort au matin.

**`asset` décrit le fichier ; seul l'endpoint vous le remet.** Il porte
`objectKey`, `status`, `contentType`, `byteLength` et `sha256` (de quoi
décider si vous voulez les octets), et aucune URL, parce qu'une URL qui
n'expirerait jamais serait un lien permanent et non authentifié vers les
papiers d'un restaurant.

`status` est le champ sur lequel aiguiller. Il vaut `uploaded` une fois que les
octets sont arrivés et ont été vérifiés, et `pending` tant qu'un appareil est
encore en train de les envoyer. Un `asset` en `pending` est absent de
l'endpoint des fichiers, ce qui est correct plutôt que cassé : redemandez plus
tard au lieu d'y voir un document manquant. `asset` est aussi le seul champ ici
qui puisse être absent purement et simplement : un enregistrement classé sans
fichier pour l'instant.

## Ce ne sont pas des photographies

Une preuve de nettoyage est une photographie. Un document, c'est ce que le
restaurant a classé : une attestation en PDF, un export de températures en
Excel ou en CSV, une procédure en Word, un scan pris au téléphone. Tout cela se
retrouve ici.

**Lisez `contentType` plutôt que d'en supposer un.** Il peut être `null` dans
l'enregistrement (l'application ne l'a pas toujours), alors quand il l'est,
prenez plutôt le `contentType` du fichier ; celui-là est le type de média de
l'objet réellement stocké, et c'est lui qu'il faut croire quand les deux
divergent. Un client qui affiche tout comme une image, ou qui enregistre tout
en `.pdf`, casse au premier tableur.

**Ne déduisez pas non plus le type de `name` ni de `s3Key`.** Une extension est
une convention, pas une garantie, et les deux champs sont du texte libre écrit
par une personne qui nomme un fichier sur une tablette.

## Les classer de votre côté

**`s3Key` est une clé, pas une adresse.** Elle identifie l'objet dans le
stockage : elle n'a ni schéma, ni hôte, ni barre oblique initiale, et vous ne
pouvez pas la récupérer. Chaque octet que vous obtenez vient de l'endpoint des
fichiers.

**Indexez sur l'`id` de l'enveloppe, pas sur `name`.** Rien n'empêche deux
documents de s'appeler `Attestation 2026.pdf`, dans le même restaurant, classés
à un an d'intervalle.

**`sizeBytes` mérite d'être lu avant de télécharger.** C'est le moyen le moins
coûteux de décider s'il faut tirer un scan de 40 Mo sur une connexion mobile.
C'est le `byteLength` de l'objet stocké, porté par le fichier, qui fait
autorité.

**Un tombstone emporte le fichier avec lui.** `deleted: true` signifie
que le document a été supprimé dans l'application, et ses fichiers cessent
d'être listés. S'il vous fallait cette attestation, il vous fallait les
octets. Voyez [la page de l'enveloppe](https://developers.backresto.com/fr/docs/collections) pour le comportement
des tombstones.