Documentos

Todo restaurante guarda papeles junto a los controles: certificados de proveedor, procedimientos de limpieza, el último informe de inspección, un plan firmado. La aplicación les da un sitio donde archivarlos, y esta colección es ese archivador: un registro por documento, cada uno apuntando al propio archivo.

Comparte el sobre de instantánea: id, deleted, capturedAt, receivedAt, sequence y los demás campos rodean al data de abajo.

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

No hay ningún timestamp en data. Cuándo se archivó el documento es el capturedAt del sobre, como en todas las demás colecciones.

El archivo es lo que importa

En otras partes el registro es la información y el archivo es la prueba. Aquí es al revés: cinco campos describen un documento cuyo contenido es toda la razón por la que alguien lee esta colección. Así que casi siempre seguirá el registro hasta los bytes.

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

URL firmadas válidas durante quince minutos, cada una con su propia autorización. La página de colecciones tiene las reglas, y dos de ellas importan aquí más que en ningún otro sitio:

• sha256 le ahorra una descarga. Es el resumen criptográfico de los bytes. Un certificado que no ha cambiado desde su último recorrido no hace falta volver a descargarlo, y los documentos son lo más grande que le va a entregar esta API.
• Descargue ahora, guarde los bytes, nunca el enlace. Quince minutos son tiempo de sobra para descargar y lo bastante poco como para que una URL en su base de datos sea un enlace muerto por la mañana.

asset describe el archivo; solo el endpoint se lo entrega. Lleva objectKey, status, contentType, byteLength y sha256 —lo justo para decidir si quiere los bytes— y ninguna URL, porque una URL que nunca caducara sería un enlace permanente y sin autenticar a los papeles de un restaurante.

status es el campo por el que ramificar. Es uploaded en cuanto los bytes han llegado y se han verificado, y pending mientras un dispositivo todavía los está enviando. Un archivo pending está ausente del endpoint de archivos adjuntos, lo cual es correcto y no un fallo: vuelva a preguntar más tarde en lugar de tomarlo por un documento que falta. asset es además el único campo de aquí que puede faltar por completo: un registro archivado que todavía no tiene archivo.

Esto no son fotografías

Una prueba de limpieza es una fotografía. Un documento es lo que sea que el restaurante haya archivado: un certificado en PDF, una exportación de temperaturas en Excel o CSV, un procedimiento en Word, un escaneo que alguien hizo con el móvil. Todos aparecen aquí.

Lea contentType en lugar de suponer uno. Admite null en el registro —la aplicación no siempre lo tiene—, así que cuando sea null, tome en su lugar el contentType del archivo adjunto; ese es el tipo de medio del objeto que está realmente almacenado, y es el que hay que creer cuando los dos no coinciden. Un cliente que lo muestre todo como una imagen, o que lo guarde todo como .pdf, se rompe con la primera hoja de cálculo.

Tampoco deduzca el tipo de name ni de s3Key. Una extensión es una convención, no una garantía, y los dos campos son texto libre de una persona que nombra un archivo en una tableta.

Archivarlos por su parte

s3Key es una clave, no una dirección. Identifica el objeto en el almacén: no tiene esquema, ni host, ni barra inicial, y no puede descargarlo. Cada byte que obtenga sale del endpoint de archivos adjuntos.

Indexe por el id del sobre, no por name. Nada impide que dos documentos se llamen Attestation 2026.pdf, en el mismo restaurante, archivados con un año de diferencia.

Conviene leer sizeBytes antes de descargar. Es la manera más barata de decidir si bajar un escaneo de 40 MB por una conexión móvil. El byteLength del propio objeto almacenado, en el archivo adjunto, es el que manda.

Una lápida se lleva el archivo consigo. deleted: true significa que el documento se borró en la aplicación, y sus archivos adjuntos dejan de listarse: si necesitaba ese certificado, necesitaba los bytes. Consulte la página del sobre para saber cómo se comportan las lápidas.