# Documentos

> O arquivo de documentos do próprio restaurante (certificados, procedimentos, relatórios), cada registo um ficheiro arquivado com o seu tipo de conteúdo.

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

Todos os restaurantes guardam papel ao lado dos controlos: certificados de
fornecedores, procedimentos de limpeza, o último relatório de inspeção, um plano
assinado. A aplicação dá-lhes um sítio para o arquivar, e esta coleção é esse
arquivo: um registo por documento, cada um a apontar para o próprio ficheiro.

| Coleção | Scope | O que é um registo |
| --- | --- | --- |
| `drive-files` | `drive-files:read` | Um documento guardado no arquivo de documentos do restaurante. |

Partilha o [envelope de snapshot](https://developers.backresto.com/pt/docs/collections): `id`, `deleted`,
`capturedAt`, `receivedAt`, `sequence` e os restantes ficam à volta do `data`
abaixo.

## `drive-files`

| Campo | Tipo | Significado |
| --- | --- | --- |
| `s3Key` | string, **obrigatório** | Onde o documento está no arquivo. Uma chave, não um URL. Até 1024 caracteres. |
| `name` | string, **obrigatório** | O nome do ficheiro tal como o restaurante o vê. |
| `sizeBytes` | number, **obrigatório** | O tamanho do documento em bytes. |
| `contentType` | string \| null | O tipo de conteúdo que a aplicação registou. Pode faltar. |
| `asset` | object | O ficheiro. Leia a secção seguinte. |

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

Não há `timestamp` no `data`. Quando o documento foi arquivado é o `capturedAt`
do envelope, como em todas as outras coleções.

## O ficheiro é o essencial

Noutros sítios, o registo é a informação e o ficheiro é a prova. Aqui é ao
contrário: cinco campos descrevem um documento cujo conteúdo é toda a razão por
que alguém lê esta coleção. Por isso, quase sempre vai seguir do registo para os
bytes.

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

URL assinados válidos durante **quinze minutos**, cada um a levar a sua própria
autorização. [A página das coleções](https://developers.backresto.com/pt/docs/collections) tem as regras, e duas
delas contam mais aqui do que em qualquer outro lado:

- **O `sha256` permite-lhe saltar uma transferência.** É o resumo
  criptográfico dos bytes. Um certificado que não mudou desde o seu último
  percurso não precisa de voltar a ser transferido, e os documentos são as
  maiores coisas que esta API lhe vai dar.
- **Vá buscá-los agora, guarde os bytes, nunca a ligação.** Quinze minutos
  chegam para transferir e são curtos o suficiente para que um URL guardado na
  sua base de dados esteja morto na manhã seguinte.

**O `asset` descreve o ficheiro; só o endpoint o entrega.** Traz `objectKey`,
`status`, `contentType`, `byteLength` e `sha256` (o suficiente para decidir se
quer os bytes), e nenhum URL, porque um URL que nunca expirasse seria uma ligação
permanente e sem autenticação para a papelada de um restaurante.

`status` é o campo pelo qual deve decidir. É `uploaded` assim que os bytes
chegaram e foram verificados, e `pending` enquanto um dispositivo ainda os está
a enviar. Um `asset` a `pending` está ausente do endpoint dos ficheiros, o que
está correto e não avariado: volte a perguntar mais tarde em vez de o tratar
como um documento em falta. O `asset` é também o único campo aqui que pode
faltar por completo: um registo arquivado ainda sem ficheiro.

## Estes não são fotografias

Uma prova de limpeza é uma fotografia. Um documento é o que quer que o
restaurante tenha arquivado: um certificado em PDF, uma exportação de
temperaturas em Excel ou CSV, um procedimento em Word, uma digitalização que
alguém fez com o telemóvel. Tudo isso aparece aqui.

**Leia o `contentType` em vez de assumir um.** Admite `null` no registo (a
aplicação nem sempre o tem), por isso, quando for `null`, use antes o
`contentType` do `asset`; esse é o tipo de conteúdo do objeto que está
efetivamente armazenado, e é o que merece confiança quando os dois discordam.
Um cliente que apresente tudo como imagem, ou que guarde tudo como `.pdf`,
parte-se na primeira folha de cálculo.

**Também não deduza o tipo a partir de `name` ou de `s3Key`.** Uma extensão é
uma convenção, não uma garantia, e os dois campos são texto livre escrito por
uma pessoa a dar nome a um ficheiro num tablet.

## Arquivá-los do seu lado

**`s3Key` é uma chave, não um endereço.** Identifica o objeto no arquivo: não
tem esquema, não tem servidor e não tem barra inicial, e não o consegue ir
buscar. Cada byte que recebe vem do endpoint dos ficheiros.

**Indexe pelo `id` do envelope, não pelo `name`.** Nada impede que dois
documentos se chamem `Attestation 2026.pdf`, no mesmo restaurante, arquivados
com um ano de intervalo.

**Vale a pena ler o `sizeBytes` antes de transferir.** É a forma mais barata de
decidir se puxa uma digitalização de 40 MB numa ligação móvel. O `byteLength`
do próprio objeto armazenado, no `asset`, é o que faz fé.

**Um tombstone leva o ficheiro com ele.** `deleted: true` significa que o
documento foi removido na aplicação, e os seus ficheiros deixam de ser
listados. Se precisava daquele certificado, precisava dos bytes. Veja
[a página do envelope](https://developers.backresto.com/pt/docs/collections) para saber como se comportam os
tombstones.