# Étiquettes de traçabilité

> Les étiquettes secondaires que le personnel imprime et colle sur un contenant, avec le fichier imprimé attaché et un identifiant de groupe par impression.

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

Quand un contenant est ouvert ou qu'une préparation est faite, le personnel
imprime une étiquette et la colle dessus : ce que c'est, d'où ça vient, quand
ça a été ouvert, quand ça doit partir. Ce sont les étiquettes secondaires de
durée de vie, celles qu'un inspecteur retourne dans sa main. Cette
collection est l'enregistrement de chacune de celles qui ont été imprimées,
avec le fichier imprimé lui-même attaché.

| Collection | Scope | Ce qu'est un enregistrement |
| --- | --- | --- |
| `traceability-labels` | `traceability-labels:read` | Une étiquette qui a été imprimée, et le fichier qui a été imprimé. |

Elle partage l'[enveloppe de snapshot](https://developers.backresto.com/fr/docs/collections) : `id`, `deleted`,
`capturedAt`, `receivedAt`, `sequence` et le reste entourent le `data`
ci-dessous.

## `traceability-labels`

| Champ | Type | Signification |
| --- | --- | --- |
| `timestamp` | string, **obligatoire** | Quand l'étiquette a été imprimée, en millisecondes depuis l'epoch sous forme de chaîne de caractères. |
| `supplier` | string \| null | Qui a fourni ce sur quoi l'étiquette est collée. Texte libre. |
| `part` | number \| null | Non documenté. Un nombre décimal, pas un entier. Lisez la note ci-dessous avant de l'utiliser. |
| `commentary` | string \| null | Une note saisie au moment de l'impression. Texte libre. |
| `groupId` | string \| null | L'impression à laquelle cette étiquette appartient. |
| `userId` | string \| null | Le [membre du personnel](https://developers.backresto.com/fr/docs/facilities) qui l'a imprimée, quand l'application en a gardé un. |
| `asset` | object, **obligatoire** | Le fichier qui a été imprimé. Lisez la section suivante. |

```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` est un nom, pas une référence.** C'est du texte, pas l'identifiant
d'un [fournisseur](https://developers.backresto.com/fr/docs/catalogue), et rien ne maintient les deux en phase :
un fournisseur renommé dans le catalogue ne réécrit pas les étiquettes
imprimées le mois dernier. Faites la correspondance dessus s'il le faut, mais
traitez une correspondance comme une supposition et une absence de
correspondance comme normale.

## Le fichier

Chaque étiquette en porte un : `data.asset` dit qu'un fichier existe, et les
octets viennent de l'endpoint des fichiers.

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

Il répond par des URL signées valables **quinze minutes**, portant chacune sa
propre autorisation, si bien que le téléchargement ne demande aucun en-tête.
Les règles complètes (à quoi ressemble la réponse, pourquoi `sha256` vous
évite un téléchargement, pourquoi vous stockez les octets et pas le lien)
sont sur [la page des collections](https://developers.backresto.com/fr/docs/collections). Deux choses méritent
quand même d'être dites ici.

**`asset` décrit le fichier ; seul l'endpoint vous le remet.** Il porte
`objectKey`, `status`, `contentType`, `byteLength` et `sha256`, mais aucune URL.
Un lien qui n'expirerait jamais serait une porte d'entrée permanente et non
authentifiée dans les enregistrements d'un restaurant. Aiguillez sur `status` :
`uploaded` signifie que les octets sont arrivés et ont été vérifiés, `pending`
qu'un appareil est encore en train de les envoyer, et un `asset` en `pending`
est délibérément absent de l'endpoint des fichiers plutôt que cassé.

**Une étiquette imprimée n'est pas forcément une image.** Lisez le
`contentType` que l'endpoint des fichiers vous donne plutôt que de supposer une
photographie, et ne renommez pas tout en `.jpg` à l'entrée de votre propre
stockage.

## Les étiquettes imprimées ensemble

`groupId` est le champ qui retransforme un flux d'étiquettes en quelque chose
qu'une personne reconnaîtrait. Quand le personnel imprime un lot (plusieurs
étiquettes pour plusieurs contenants de la même préparation, d'un coup),
chaque étiquette de cette impression porte le même `groupId`. Groupez dessus
avant d'afficher quoi que ce soit : une impression est un seul événement dans
une chronologie, pas huit.

`part` est le champ dont nous ne pouvons pas encore vous dire le sens, et nous
préférons le dire plutôt que de vous laisser deviner de travers. C'est un
nombre **décimal**, pas un compteur, ce qui exclut la lecture évidente
d'"étiquette 3 sur 8" et suggère une portion ou une quantité, mais rien
dans le schéma ne l'affirme, et nous n'allons pas faire semblant. Transportez-le
tel quel, affichez-le brut s'il le faut, et [demandez-nous](https://developers.backresto.com/fr/docs/support) si
votre intégration en dépend : la réponse tient en une conversation avec les
personnes qui ont construit l'écran des étiquettes.

Les deux peuvent être `null`. Une étiquette imprimée seule peut arriver sans ni
l'un ni l'autre, et c'est une impression d'une seule étiquette plutôt qu'un
enregistrement cassé : repliez-vous sur l'`id` de l'enveloppe et affichez-la
seule.