# Documentos

> El almacén de documentos del propio restaurante (certificados, procedimientos, informes), cada registro un archivo guardado con su propio tipo de medio.

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

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.

| Colección | Scope | Qué es un registro |
| --- | --- | --- |
| `drive-files` | `drive-files:read` | Un documento archivado en el almacén de documentos del restaurante. |

Comparte el [sobre de snapshot](https://developers.backresto.com/es/docs/collections): `id`, `deleted`,
`capturedAt`, `receivedAt`, `sequence` y los demás campos rodean al `data` de
abajo.

## `drive-files`

| Campo | Tipo | Significado |
| --- | --- | --- |
| `s3Key` | string, **obligatorio** | Dónde está el documento en el almacén. Una clave, no una URL. Hasta 1024 caracteres. |
| `name` | string, **obligatorio** | El nombre del archivo tal como lo ve el restaurante. |
| `sizeBytes` | number, **obligatorio** | Tamaño del documento en bytes. |
| `contentType` | string \| null | El tipo de medio que registró la aplicación. Puede faltar. |
| `asset` | object | El archivo. Lea la sección siguiente. |

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

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.

```http
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](https://developers.backresto.com/es/docs/collections) 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 sobre el que decidir. 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.

**Un tombstone 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](https://developers.backresto.com/es/docs/collections) para saber cómo se comportan los
tombstones.