Entregas

O registo de receção de mercadorias — cada campo, o seu tipo, e o que significa 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.

Ambos os endpoints precisam do âmbito deliveries:read no restaurante indicado no caminho.

As entregas são o único recurso moldado à mão por aqui: um objeto desenhado, imutável assim que registado, listado por intervalo de tempo. Tudo o resto que a aplicação regista — temperaturas de confeção e de arrefecimento, limpeza, etiquetas — chega através das coleções, que em vez disso partilham um único envelope genérico.

Listar entregas

GET /v1/restaurants/{restaurantId}/deliveries?from=…&to=…&limit=…&cursor=…

Devolve { "data": Delivery[], "nextCursor": string | null }, do mais recente para o mais antigo. Veja Paginação para as regras do intervalo e para o cursor.

Obter uma entrega

GET /v1/restaurants/{restaurantId}/deliveries/{deliveryId}

Devolve uma única Delivery, ou 404 se o identificador for desconhecido ou a chave não tiver concessão para esse restaurante.

O objeto de entrega

Campo	Tipo	Significado
`id`	string	Identificador estável da entrega, único dentro do restaurante.
`restaurantId`	string	O restaurante a que o registo pertence. Repete o caminho.
`occurredAt`	string	Quando o controlo aconteceu, em milissegundos desde a época Unix, em forma de cadeia de caracteres.
`isCompliant`	boolean	O veredito do funcionário sobre a entrega no seu conjunto.
`supplier`	object \| null	`{ "id": string, "name": string }`, ou `null` quando a entrega foi registada sem fornecedor.
`temperatureRecords`	array	Uma entrada por produto medido. Ver abaixo.
`nonComplianceReasons`	string[]	Porque é que a entrega foi recusada ou aceite com reservas. Texto livre escolhido pelo funcionário; vazio quando está conforme.
`correctiveActions`	string[]	O que foi feito a esse respeito. Vazio quando não foi preciso nada.
`commentary`	string \| null	Nota em texto livre. Muitas vezes `null`.
`imageCount`	integer	Quantas fotografias estão associadas. `0` significa que o endpoint das imagens não tem nada para devolver.

`temperatureRecords[]`

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

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 datas e horas são cadeias de caracteres. occurredAt é uma cadeia decimal de milissegundos desde a época Unix, porque toda a plataforma BackResto guarda as datas e horas dessa maneira. Number(occurredAt) é 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.

Exemplo

{
  "id": "8f2c1b04-0d5a-4b7e-9f31-6ad2c0e77a51",
  "restaurantId": "restaurant-1",
  "occurredAt": "1787932800000",
  "isCompliant": false,
  "supplier": { "id": "supplier-7", "name": "Metro Nord" },
  "temperatureRecords": [
    { "product": "Poulet fermier", "lotNumber": "L2291", "unit": "C", "value": 6.4 },
    { "product": "Farine T55", "lotNumber": null, "unit": "C", "value": null }
  ],
  "nonComplianceReasons": ["Température trop élevée"],
  "correctiveActions": ["Produit refusé", "Fournisseur prévenu"],
  "commentary": "Camion en retard, rupture de chaîne du froid probable",
  "imageCount": 2
}