Orders

Como Software Service, seu sistema:

Consome eventos (polling ou webhook configurado pela Prefiro)
Consulta o pedido completo via GET (fonte de verdade do status)
Executa transições de lifecycle via POST quando aplicável

A Prefiro não expõe POST /orders para entrada de pedido — pedidos nascem na plataforma Prefiro.

Eventos

Mecanismo	Endpoint / formato
Polling	`GET /events:polling`
ACK	`POST /events/acknowledgment`
Webhook (opcional)	POST na URL que você configurar; headers `X-App-Id`, `X-App-MerchantId`, `X-App-Signature`

Reconcilie sempre o estado via GET /orders/{orderId} após receber um evento.

Retirada e consumo local

Pedidos de retirada e consumo no local usam fulfillment.orderType TAKEOUT. A conclusão do fluxo é feita com POST /orders/{orderId}/delivered — não há evento PICKED_UP nem operação pickedUp.

Consultar pedido

GET https://opendelivery.prefirodelivery.com/{HASH}/od/v2/orders/{orderId}

O payload inclui fulfillment.orderType (DELIVERY ou TAKEOUT), blocos timing, context, status, merchant, customer, items, etc.

Lifecycle (receiver)

Paths relativos à base /od/v2:

Operação	Método e path
Confirmar	`POST /orders/{orderId}/confirm`
Em preparo	`POST /orders/{orderId}/preparing`
Pronto para retirada	`POST /orders/{orderId}/ready-for-pickup`
Saiu para entrega	`POST /orders/{orderId}/dispatch` (somente `DELIVERY`)
Entregue / retirado	`POST /orders/{orderId}/delivered`
Solicitar cancelamento	`POST /orders/{orderId}/requestCancellation` (body: `reason`)
Validar código	`POST /orders/{orderId}/validateCode`

Respostas HTTP

Código	Significado
`202`	Transição aceita ou já aplicada (idempotente)
`409`	Transição inválida (`INVALID_ORDER_STATE_TRANSITION`)
`403`	App não autorizado para o estabelecimento do pedido
`404`	Pedido não encontrado

Cancelamento

Iniciado pelo seu sistema (SS → OA): fluxo handshake via requestCancellation → eventos CANCELLATION_REQUEST_* → status CANCELLED.

Iniciado pela Prefiro: evento/status CANCELLED sem handshake HTTP adicional.

Especificação: Orders — Open Delivery V2.