Entregas

Os controlos de receção e as fotografias tiradas na receção: duas coleções, cada campo, e o que significam no terreno.

Uma entrega é um controlo de receção: um funcionário a receber uma encomenda, a registar temperaturas e a decidir se a aceita. É o registo que um inspetor de segurança alimentar pede. As fotografias tiradas na receção são uma segunda coleção ao lado dela.

Coleção	Scope	O que é um registo
`deliveries`	`deliveries:read`	Um controlo de receção, com uma leitura de temperatura por produto.
`delivery-pictures`	`delivery-pictures:read`	Uma fotografia tirada durante uma entrega, que aponta para ela.

As duas são coleções comuns: o mesmo envelope de snapshot à volta de data, os mesmos endpoints, o mesmo cursor, a mesma regra dos 90 dias. Trazem o histórico de entregas que a aplicação ainda tinha quando foram abertas, e não só o que foi registado desde então.

`deliveries`

Campo	Tipo	Significado
`timestamp`	string, obrigatório	Quando o controlo aconteceu, em milissegundos desde a época Unix, em forma de cadeia de caracteres.
`isCompliant`	boolean, obrigatório	O veredito do funcionário sobre a entrega no seu conjunto.
`supplierDeliveriesId`	string \| null	O fornecedor de onde veio a mercadoria: o `id` de um registo de `suppliers`.
`temperatureRecords`	array \| null	Uma entrada por produto medido. Ver abaixo.
`nonComplianceReasons`	string[] \| null	Porque é que a entrega foi recusada ou aceite com reservas. Texto livre escolhido pelo funcionário; vazio quando está conforme.
`correctiveActions`	string[] \| null	O que foi feito a esse respeito. Vazio quando não foi preciso nada.
`commentary`	string \| null	Nota em texto livre. Muitas vezes `null`.
`userId`	string \| null	O funcionário que a recebeu, quando a aplicação o registou.

`temperatureRecords[]`

Campo	Tipo	Significado
`product`	string	O que foi medido, tal como o funcionário lhe chamou. Nunca vazio.
`lotNumber`	string \| null	O lote, quando foi registado.
`value`	number \| null	A leitura. `null` quando o produto foi registado sem medição.
`unit`	`"C"`	Sempre graus Celsius. Ver abaixo.

As temperaturas estão sempre em graus Celsius. Um restaurante cuja aplicação regista em Fahrenheit continua a enviar leituras em Fahrenheit, e estas são convertidas quando chegam, antes de serem guardadas. unit é "C" em todas as entradas, por isso quem consome nunca tem de converter nem de adivinhar.

{
  "id": "8f2c1b04-0d5a-4b7e-9f31-6ad2c0e77a51",
  "collection": "deliveries",
  "deleted": false,
  "capturedAt": "1787932805120",
  "receivedAt": "1787932911004",
  "sequence": "88",
  "data": {
    "timestamp": "1787932800000",
    "isCompliant": false,
    "supplierDeliveriesId": "supplier-7",
    "temperatureRecords": [
      { "product": "Poulet fermier", "lotNumber": "L2291", "value": 6.4, "unit": "C" },
      { "product": "Farine T55", "lotNumber": null, "value": null, "unit": "C" }
    ],
    "nonComplianceReasons": ["Température trop élevée"],
    "correctiveActions": ["Produit refusé", "Fournisseur prévenu"],
    "commentary": "Camion en retard, rupture de chaîne du froid probable",
    "userId": "2774953d-8d9b-4a68-8ec4-1209edd90777"
  }
}

`delivery-pictures`

Uma etiqueta, uma palete danificada, uma sonda encostada a um expositor: essas imagens são a prova por trás de isCompliant. Cada uma é um registo que aponta para a sua entrega, e traz um ficheiro, por isso os bytes vêm do endpoint assets.

Campo	Tipo	Significado
`timestamp`	string, obrigatório	Quando a fotografia foi tirada, em milissegundos desde a época Unix, em forma de cadeia de caracteres.
`deliveryId`	string \| null	O registo de `deliveries` a que pertence.
`part`	number \| null	Posição deste registo dentro de uma fotografia que a aplicação guardou em várias partes. Transmita-o tal como está, sem o interpretar.
`groupId`	string \| null	Liga essas partes entre si. Os registos que partilham um `groupId` são a mesma fotografia.
`asset`	object, obrigatório	Indica o ficheiro: `objectKey` e `status` sempre, mais `contentType`, `byteLength` e `sha256` depois de carregado.

{
  "id": "c61e0a7d-35b2-4f89-a1d4-7e90b2c45f18",
  "collection": "delivery-pictures",
  "deleted": false,
  "capturedAt": "1787932861240",
  "receivedAt": "1787932990517",
  "sequence": "143",
  "data": {
    "timestamp": "1787932860000",
    "deliveryId": "8f2c1b04-0d5a-4b7e-9f31-6ad2c0e77a51",
    "part": 4,
    "groupId": "b4d81f0a-c2e7-4a55-9d10-6f3e8a2b7c91",
    "asset": {
      "objectKey": "delivery-pictures/b4d81f0a/4.jpg",
      "status": "uploaded",
      "contentType": "image/jpeg",
      "byteLength": 902450,
      "sha256": "9f2a…"
    }
  }
}

Os bytes são uma segunda chamada, sobre o id do próprio registo:

GET /v1/restaurants/{restaurantId}/collections/delivery-pictures/records/{recordId}/assets

Responde com URL assinados válidos durante quinze minutos, exatamente como descrito na página das coleções. Peça sobre qualquer parte de uma fotografia e recebe o mesmo ficheiro: a API resolve o grupo por si, por isso não é preciso descobrir que parte o contém.

Para mostrar as fotografias de uma entrega, percorra delivery-pictures e guarde os registos cujo deliveryId é o id dessa entrega, um por groupId.

Ler isto corretamente

isCompliant é o registo, não um cálculo. É o que a pessoa que recebeu a entrega decidiu, e pode divergir do que você concluiria só a partir das temperaturas: uma leitura tirada com uma sonda de superfície, um produto com um limiar próprio, um juízo de valor. Apresente-o como o veredito dessa pessoa. Se quiser o seu, calcule-o ao lado do dela e identifique-o como sendo seu.

Os campos de texto livre são texto livre. nonComplianceReasons, correctiveActions e product são escritos pelo pessoal durante o serviço, na língua do restaurante, com a ortografia de uma terça-feira atarefada. Não construa uma enumeração a partir deles, não faça uma junção com base neles, e não assuma que estão em francês.

value pode ser null. Um produto registado sem leitura é normal: muitas vezes é um produto seco. Trate null como "não medido", nunca como 0.

As marcas temporais são cadeias de caracteres. timestamp é uma cadeia decimal de milissegundos desde a época Unix, porque toda a plataforma BackResto guarda as marcas temporais dessa maneira. Number(timestamp) é seguro hoje e pelas próximas centenas de milhares de anos, mas não deixe um parser de JSON convertê-lo em silêncio e voltar a escrevê-lo depois com perda de precisão.

Uma fotografia pode chegar depois da sua entrega. Um telemóvel carrega as fotografias quando pode, às vezes minutos depois do próprio controlo. Uma entrega ainda sem fotografia pode simplesmente ter uma a caminho; volte a percorrer mais tarde antes de concluir que não tem nenhuma.