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

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 — et cette collection est l'enregistrement de chacune de celles qui ont été imprimées, avec le fichier imprimé lui-même attaché.

Collection	Portée	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 d'instantané : 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 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.

{
  "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 est un nom, pas une référence. C'est du texte, pas l'identifiant d'un fournisseur, 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.

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