Ciclo de vida do pedido

A máquina de estados do pedido, as transições permitidas, o retrocesso a partir de ACCEPTED e o cancelamento.

Todo pedido no MeuPedido está em exatamente um estado, chamado de situação. As ações da API movem o pedido entre situações e cada mudança gera um evento no feed da sua credencial. Esta página descreve a máquina de estados que as ações obedecem.

Passe o mouse ou foque um estado para ver as ações que saem dele, o estado de chegada e o evento emitido. Clique, Enter ou Espaço fixam a seleção; as setas do teclado andam entre os estados.

Todas as transições

De	Ação	Para	Evento
PENDING	POST /v1/orders/{orderId}/confirm	ACCEPTED	CONFIRMED
ACCEPTED	POST /v1/orders/{orderId}/startPreparation	PREPARING	PREPARING*
ACCEPTED	POST /v1/orders/{orderId}/readyForPickup	READY	READY_FOR_PICKUP
ACCEPTED	POST /v1/orders/{orderId}/dispatch	DELIVERY	DISPATCHED
ACCEPTED	POST /v1/orders/{orderId}/delivered	DONE	CONCLUDED
PREPARING	POST /v1/orders/{orderId}/readyForPickup	READY	READY_FOR_PICKUP
PREPARING	POST /v1/orders/{orderId}/dispatch	DELIVERY	DISPATCHED
PREPARING	POST /v1/orders/{orderId}/delivered	DONE	CONCLUDED
READY	POST /v1/orders/{orderId}/dispatch	DELIVERY	DISPATCHED
READY	POST /v1/orders/{orderId}/delivered	DONE	CONCLUDED
DELIVERY	POST /v1/orders/{orderId}/delivered	DONE	CONCLUDED
PENDING	POST /v1/orders/{orderId}/requestCancellation	CANCELLED	CANCELLED
ACCEPTED	POST /v1/orders/{orderId}/requestCancellation	CANCELLED	CANCELLED
PREPARING	POST /v1/orders/{orderId}/requestCancellation	CANCELLED	CANCELLED
READY	POST /v1/orders/{orderId}/requestCancellation	CANCELLED	CANCELLED
DELIVERY	POST /v1/orders/{orderId}/requestCancellation	CANCELLED	CANCELLED

* extensão MeuPedido. Retrocesso: a partir de ACCEPTED, a ação de qualquer estado anterior (confirm, startPreparation, readyForPickup, dispatch) leva o pedido de volta para ele sem emitir evento.

Transição para frente: ação da API e evento emitido
requestCancellation, de qualquer estado exceto DONE
Retrocesso a partir de ACCEPTED, sem evento (aparece ao focar um estado)
Passe o mouse, toque ou use Tab e as setas do teclado para explorar

As situações

Situação	Significado	Como o pedido chega aqui
`PENDING_PAYMENT`	Aguardando pagamento on-line (PIX). O pedido ainda não existe para a sua integração.	Criado com pagamento on-line pendente.
`PENDING`	Novo pedido, esperando a loja aceitar.	Criação do pedido, ou confirmação do PIX. Gera o evento `CREATED`.
`ACCEPTED`	A loja aceitou o pedido.	`POST /confirm`. Gera `CONFIRMED`.
`PREPARING`	A cozinha começou a preparar. Extensão MeuPedido.	`POST /startPreparation`. Gera `PREPARING`.
`READY`	Pronto para retirada ou para sair.	`POST /readyForPickup`. Gera `READY_FOR_PICKUP`.
`DELIVERY`	Saiu para entrega. Só faz sentido em pedido `DELIVERY`.	`POST /dispatch`. Gera `DISPATCHED`.
`DONE`	Entregue ou retirado. Encerrado.	`POST /delivered` ou `POST /pickedUp`. Gera `CONCLUDED`.
`CANCELLED`	Cancelado. Final.	`POST /requestCancellation`, ou cancelamento pelo painel ou pelo cliente. Gera `CANCELLED`.

PENDING_PAYMENT e PENDING não geram evento próprio: o pedido nasce para a sua integração no CREATED, que é emitido quando ele entra em PENDING. Um pedido de PIX que nunca é pago nunca aparece no seu feed.

Transições para frente

Cada seta abaixo é uma transição que a API aceita. Não é preciso passar por todas as situações: um pedido em ACCEPTED pode ir direto para DONE.

PENDING_PAYMENT -> PENDING
PENDING         -> ACCEPTED
ACCEPTED        -> PREPARING | READY | DELIVERY | DONE
PREPARING       -> READY | DELIVERY | DONE
READY           -> DELIVERY | DONE
DELIVERY        -> DONE
qualquer uma    -> CANCELLED   (exceto DONE)

Regras que valem para todas as transições:

Mesma situação responde 202 com status: "already_applied", e não erro. Um comando reenviado depois de um timeout não quebra o seu fluxo.
DELIVERY não vale para pedido INDOOR (mesa). Para TAKEOUT e INDOOR, use readyForPickup e depois pickedUp.
CANCELLED é final. Nenhuma ação tira um pedido cancelado dessa situação.
DONE não pode ser cancelado. requestCancellation em um pedido encerrado responde 422 invalid_transition.

Retrocesso

A partir de ACCEPTED, o pedido pode voltar para qualquer situação anterior. O caso típico é um operador que avançou o pedido por engano: um POST /confirm em um pedido PREPARING devolve o pedido para ACCEPTED.

O retrocesso não gera evento. O feed da sua credencial só recebe transições para frente e o cancelamento. Se você mantém uma cópia local do pedido e precisa refletir um retrocesso, busque o pedido em GET /v1/orders/{orderId} antes de aplicar a próxima ação.

Retrocesso não é desfazer

Voltar para ACCEPTED não reverte nada que aconteceu fora do estado: entregador atribuído, cupom impresso ou notificação enviada ao cliente continuam como estão. Use com cuidado e prefira avançar o pedido pelo caminho normal.

Cancelamento

POST /v1/orders/{orderId}/requestCancellation cancela o pedido imediatamente. Apesar do nome herdado do padrão, não existe uma etapa de aprovação: a resposta já vem com situation: "CANCELLED" e o evento CANCELLED é emitido na sequência, com metadata.reason e metadata.code.

O cancelamento é aceito em qualquer situação, exceto DONE. Detalhes do corpo opcional e do código de motivo estão em Ações e idempotência.

Um pedido de entrega, do início ao fim

CREATED          o pedido entrou em PENDING
CONFIRMED        você chamou /confirm             ACCEPTED
PREPARING        você chamou /startPreparation    PREPARING
READY_FOR_PICKUP você chamou /readyForPickup      READY
DISPATCHED       você chamou /dispatch            DELIVERY
CONCLUDED        você chamou /delivered           DONE

Para um pedido de retirada (TAKEOUT) ou de mesa (INDOOR), o caminho termina em readyForPickup seguido de pickedUp, e o DISPATCHED não existe.

Próximos passos

Ações e idempotência: as chamadas que movem o pedido e como repeti-las com segurança.
Catálogo de eventos: o que cada transição emite no seu feed.
Polling: como consumir os eventos.