Fotografias das entregas

As imagens tiradas na receção, servidas como URL assinados que expiram ao fim de quinze minutos.

O pessoal fotografa o que recebe — uma etiqueta, uma palete danificada, uma sonda encostada a um expositor. Essas imagens são a prova por trás de isCompliant, e é este endpoint que lhas entrega.

Precisa dos dois âmbitos, deliveries:read e delivery-images:read, no restaurante indicado no caminho. Uma chave que só tenha o primeiro responde 403 aqui, enquanto a própria entrega responde normalmente.

Listar as fotografias de uma entrega

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

{
  "data": [
    {
      "id": "b4d81f0ac2e7",
      "contentType": "image/jpeg",
      "byteLength": 902450,
      "uploadedAt": "1787932860000",
      "url": "https://…/restaurants/restaurant-1/deliveries/8f2c…/b4d81f0ac2e7.jpg?X-Amz-Signature=…",
      "urlExpiresAt": "1787933760000"
    }
  ]
}

Não há paginação: uma entrega tem no máximo vinte fotografias, e vêm todas numa só resposta.

Campo	Tipo	Significado
`id`	string	Identificador estável da imagem dentro da entrega.
`contentType`	string	`image/jpeg`, `image/png` ou `image/webp`. Mais nada chega a esta API.
`byteLength`	integer	Tamanho exato do objeto, até 10 MB.
`uploadedAt`	string	Quando a imagem acabou de ser carregada, em milissegundos desde a época Unix, em forma de cadeia de caracteres.
`url`	string	Um URL assinado e direto para os bytes.
`urlExpiresAt`	string	Quando esse URL deixa de funcionar, em milissegundos desde a época Unix, em forma de cadeia de caracteres.

Os URL são de curta duração de propósito

url é uma ligação pré-assinada válida durante quinze minutos, e todos os URL de uma mesma resposta partilham a mesma expiração, para que possa tratar a página como um bloco. Leva a sua própria autorização, por isso ir buscar os bytes não precisa de qualquer cabeçalho Authorization — o que também significa que a ligação é, ela própria, uma credencial ao portador.

Isso condiciona a forma como a deve usar:

Vá buscá-los agora, ou volte a buscá-los mais tarde. Descarregue os bytes enquanto a resposta está fresca; não guarde o URL para o seguir amanhã. Volte a chamar o endpoint para obter ligações novas — é barato, e volta a verificar a concessão, que é o que interessa.
Nunca ponha o URL num sítio onde sobreviva ao seu propósito. Nem num email, nem num pedido de suporte, nem numa cache do lado do cliente com um TTL longo. Durante quinze minutos, qualquer pessoa que o tenha consegue ver aquela imagem.
Guarde os bytes, não a ligação, se precisar da imagem no seu próprio produto. Guarde o id ao lado para saber se já a tem.

Só aparecem as imagens já carregadas

Uma fotografia é registada quando o dispositivo começa o carregamento e só se torna visível aqui depois de os bytes terem efetivamente chegado e sido verificados. Uma imagem ainda a caminho — um telemóvel que saiu do edifício a meio do carregamento — está ausente, não avariada.

É por isso que o imageCount da entrega pode, por breves momentos, ser superior ao que este endpoint devolve. Confie neste endpoint para saber o que existe agora, e volte a ler a entrega mais tarde se a contagem for importante para si.

Ir buscá-las

curl "https://api.backresto.com/v1/restaurants/$RESTAURANT_ID/deliveries/$DELIVERY_ID/images" \
  -H "Authorization: Bearer $BACKRESTO_PARTNER_API_KEY" \
  | jq -r '.data[] | "\(.id) \(.url)"' \
  | while read -r id url; do
      curl -sS "$url" -o "$id.jpg"
    done

O cabeçalho Authorization na primeira chamada, e nenhum na segunda: é a assinatura no URL que autoriza a transferência.