# Etiquetas de rastreabilidade

> As etiquetas secundárias que o pessoal imprime e cola num recipiente, com o ficheiro impresso anexado e um identificador de grupo por tiragem.

Source: https://developers.backresto.com/pt/docs/traceability-labels

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. Esta coleção é o registo de cada uma que foi impressa, com o
próprio ficheiro impresso anexado.

| Coleção | Scope | O que é um registo |
| --- | --- | --- |
| `traceability-labels` | `traceability-labels:read` | Uma etiqueta que foi impressa, e o ficheiro que foi impresso. |

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.

## `traceability-labels`

| Campo | Tipo | Significado |
| --- | --- | --- |
| `timestamp` | string, **obrigatório** | Quando a etiqueta foi impressa, em milissegundos desde a época Unix, em forma de cadeia de caracteres. |
| `supplier` | string \| null | Quem forneceu aquilo em que a etiqueta está colada. Texto livre. |
| `part` | number \| null | Não documentado. Um número decimal, não um inteiro. Leia a nota abaixo antes de o usar. |
| `commentary` | string \| null | Uma nota escrita no momento da impressão. Texto livre. |
| `groupId` | string \| null | A tiragem a que esta etiqueta pertence. |
| `userId` | string \| null | O [funcionário](https://developers.backresto.com/pt/docs/facilities) que a imprimiu, quando a aplicação guardou um. |
| `asset` | object, **obrigatório** | O ficheiro que foi impresso. Leia a secção seguinte. |

```json
{
  "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": "3c9e…"
    }
  }
}
```

**`supplier` é um nome, não uma referência.** É texto, não o identificador de um
[fornecedor](https://developers.backresto.com/pt/docs/catalogue), 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.

```http
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](https://developers.backresto.com/pt/docs/collections). 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](https://developers.backresto.com/pt/docs/support) 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.