Documents

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.

Elle partage l'enveloppe d'instantané : id, deleted, capturedAt, receivedAt, sequence et le reste entourent le data ci-dessous.

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

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.

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 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é.

Une pierre tombale emporte le fichier avec elle. 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 pour le comportement des pierres tombales.