Etiquetas de trazabilidad

Cuando se abre un recipiente o se hace una elaboración, el personal imprime una etiqueta y la pega: qué es, de dónde viene, cuándo se abrió, cuándo hay que tirarlo. Son las etiquetas secundarias de vida útil, las que un inspector le da la vuelta en la mano, y esta colección es el registro de cada una que se imprimió, con el propio archivo impreso adjunto.

Comparte el sobre de instantánea: id, deleted, capturedAt, receivedAt, sequence y los demás campos rodean al data de abajo.

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 es un nombre, no una referencia. Es texto, no el id de un proveedor, y nada mantiene los dos sincronizados: un proveedor renombrado en el catálogo no reescribe las etiquetas impresas el mes pasado. Compárelos si no le queda más remedio, pero trate una coincidencia como una suposición y una no coincidencia como algo normal.

El archivo

Toda etiqueta lleva uno: data.asset dice que existe un archivo, y los bytes salen del endpoint de archivos adjuntos.

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

Responde con URL firmadas válidas durante quince minutos, cada una con su propia autorización, de modo que la descarga no necesita cabecera. Las reglas completas —qué aspecto tiene la respuesta, por qué sha256 le ahorra una descarga, por qué guarda los bytes y no el enlace— están en la página de colecciones. Aun así, dos cosas merecen decirse aquí.

asset describe el archivo; solo el endpoint se lo entrega. Lleva objectKey, status, contentType, byteLength y sha256, pero ninguna URL: un enlace que nunca caducara sería una vía permanente y sin autenticar hacia los registros de un restaurante. Ramifique según status: uploaded significa que los bytes llegaron y se verificaron, pending significa que un dispositivo todavía los está enviando, y un archivo pending está ausente del endpoint de archivos adjuntos a propósito, no porque esté roto.

Una etiqueta impresa no es necesariamente una imagen. Lea el contentType que le da el endpoint de archivos adjuntos en lugar de suponer una fotografía, y no renombre todo a .jpg al entrar en su propio almacén.

Etiquetas impresas juntas

groupId es el campo que devuelve un flujo de etiquetas a algo que una persona reconocería. Cuando el personal imprime un lote —varias etiquetas para varios recipientes de la misma elaboración, de una vez—, todas las etiquetas de esa tirada llevan el mismo groupId. Agrupe por él antes de mostrar nada: una tirada es un evento en una línea de tiempo, no ocho.

part es el campo cuyo significado todavía no podemos decirle, y preferimos decirlo a que usted lo adivine mal. Es un número decimal, no un contador, lo que descarta la lectura obvia de «etiqueta 3 de 8» y apunta a una porción o una cantidad; pero nada en el esquema lo afirma, así que no vamos a fingir. Arrástrelo intacto, muéstrelo en bruto si hace falta y pregúntenos si su integración depende de él: la respuesta es una conversación con las personas que construyeron la pantalla de etiquetas.

Los dos admiten null. Una etiqueta impresa por su cuenta puede llegar sin ninguno de los dos, y eso es una tirada de una sola etiqueta, no un registro roto: recurra al id del sobre y muéstrela sola.