Documentos

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.

Partilha o envelope de instantâneo: id, deleted, capturedAt, receivedAt, sequence e os restantes ficam à volta do data abaixo.

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

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.

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 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 é tempo suficiente para transferir e pouco suficiente para que um URL guardado na sua base de dados seja uma ligação morta pela manhã.

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

Uma marca de eliminação leva o ficheiro com ela. 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 para saber como se comportam as marcas de eliminação.