Etiquetas de rastreabilidade

Quando um recipiente é aberto ou uma preparação é feita, o pessoal imprime uma etiqueta e cola-a: o que é, de onde veio, quando foi aberto, quando tem de sair. São as etiquetas secundárias de prazo de validade, aquelas que um inspetor vira e revira na mão — e esta coleção é o registo de cada uma que foi impressa, com o próprio ficheiro impresso anexado.

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

traceability-labels

{
  "id": "0c6a4f2b-9e17-4d50-8b3c-1f7d5a2e9046",
  "collection": "traceability-labels",
  "deleted": false,
  "capturedAt": "1789786412903",
  "receivedAt": "1789786500117",
  "sequence": "2048",
  "data": {
    "timestamp": "1789786380000",
    "supplier": "Metro",
    "part": 1.5,
    "commentary": "Bac 3, ouvert ce matin",
    "groupId": "5e8b1c47-2a90-4f63-b1d8-6c04e7a3f215",
    "userId": "b3f7c1a0-5d42-4e88-9a16-7c0e2d4b9f31",
    "asset": {
      "objectKey": "restaurants/36eaa3fa/labels/c58d10b7e4a9",
      "status": "uploaded",
      "contentType": "image/jpeg",
      "byteLength": 48210,
      "sha256": "3c9e0b7a41d85f2e06b93c8a7d140e5b29f6a83c1d07e4b5a9c26f80d3e17b4a"
    }
  }
}

supplier é um nome, não uma referência. É texto, não o identificador de um fornecedor, e nada mantém os dois a par: um fornecedor renomeado no catálogo não reescreve as etiquetas impressas no mês passado. Faça a correspondência se for preciso, mas trate um acerto como um palpite e uma falha como normal.

O ficheiro

Todas as etiquetas trazem um: data.asset diz que existe um ficheiro, e os bytes vêm do endpoint dos ficheiros.

GET /v1/restaurants/{restaurantId}/collections/traceability-labels/records/{recordId}/assets

Responde com URL assinados válidos durante quinze minutos, cada um a levar a sua própria autorização, por isso a transferência não precisa de qualquer cabeçalho. As regras completas — o aspeto da resposta, porque é que o sha256 lhe permite saltar uma transferência, porque é que guarda os bytes e não a ligação — estão na página das coleções. Mesmo assim, há duas coisas que vale a pena dizer aqui.

O asset descreve o ficheiro; só o endpoint o entrega. Traz objectKey, status, contentType, byteLength e sha256, mas nenhum URL — uma ligação que nunca expirasse seria uma via permanente e sem autenticação para os registos de um restaurante. Decida pelo status: uploaded significa que os bytes chegaram e foram verificados, pending significa que um dispositivo ainda os está a enviar, e um asset a pending está deliberadamente ausente do endpoint dos ficheiros, e não avariado.

Uma etiqueta impressa não é necessariamente uma imagem. Leia o contentType que o endpoint dos ficheiros lhe dá em vez de assumir que é uma fotografia, e não chame .jpg a tudo à entrada do seu próprio armazenamento.

Etiquetas impressas em conjunto

groupId é o campo que volta a transformar um fluxo de etiquetas em algo que uma pessoa reconheceria. Quando o pessoal imprime um lote — várias etiquetas para vários recipientes da mesma preparação, de uma só vez — todas as etiquetas dessa tiragem trazem o mesmo groupId. Agrupe por ele antes de mostrar seja o que for: uma tiragem é um acontecimento numa linha temporal, não oito.

part é o campo cujo significado ainda não lhe conseguimos dizer, e preferimos dizê-lo a deixá-lo adivinhar mal. É um número decimal, não um contador, o que exclui a leitura óbvia de «etiqueta 3 de 8» e sugere uma porção ou uma quantidade — mas nada no esquema o afirma, por isso não vamos fingir. Leve-o consigo intacto, mostre-o em bruto se for preciso, e pergunte-nos se a sua integração depender dele: a resposta é uma conversa com as pessoas que construíram o ecrã das etiquetas.

Ambos admitem null. Uma etiqueta impressa sozinha pode chegar sem nenhum dos dois, e isso é uma tiragem de uma só etiqueta e não um registo avariado: recorra ao id do envelope e mostre-a sozinha.