Ciclo de vida do pedido

Os status

Cada status tem um nome (usado na API) e um código numérico (que aparece em relatórios e logs). Os dois se referem ao mesmo estado.

Status	Código	Quem move	Significado
`CART_CREATED`	1	plataforma	carrinho aberto, ainda não é pedido
`ORDER_CREATED`	100	plataforma	cliente fechou o pedido
`PAYMENT_PENDING`	200	plataforma	aguardando confirmação do pagamento
`PAYMENT_ERROR`	250	plataforma	pagamento recusado
`PAYMENT_APPROVED`	300	plataforma	pagamento aprovado — o pedido chega ao ERP aqui
`ORDER_BEING_PREPARED`	400	ERP ou app Grocers	em separação
`ORDER_INVOICED`	350	ERP ou app Grocers	nota fiscal emitida
`READY_FOR_PICKUP_OR_DELIVERY`	500	ERP ou app Grocers	pronto para sair ou para retirada
`SHIPPED`	600	ERP ou app Grocers	saiu para entrega
`DELIVERED`	700	ERP ou app Grocers	entregue
`ORDER_CANCELLATION_ANALYSIS`	750	ambos	cancelamento em análise
`ORDER_CANCELLED`	800	ambos	cancelado
`DELIVERY_FAILED`	900	ERP ou app Grocers	tentativa de entrega frustrada
`ORDER_RETURNED`	1000	ERP ou app Grocers	devolvido
`REFUND_IN_PROGRESS`	1100	plataforma	estorno em processamento
`REFUND_COMPLETED`	1200	plataforma	estorno concluído

A sequência canônica

Esta é a ordem oficial, e ela vale para toda a documentação. Separar vem antes de faturar.

O diagrama abaixo responde: por quais estados passa um pedido que dá certo, e a partir de qual deles a responsabilidade é sua?

Tudo acima de PAYMENT_APPROVED é da plataforma e acontece sem você. Daí em diante, quem move o status é a operação — na ordem em que ela executar.

A operação nem sempre é o seu ERP. Além do PATCH que você dispara, a Grocers tem aplicativos de Picking e Shipping que movem os mesmos status. Se a sua rede contratar um deles, parte da sequência passa a ser avançada por esses apps, e o seu ERP recebe essas mudanças em vez de emiti-las.

Isso não muda a integração, mas muda uma premissa: não presuma que todo Order_Updated com status acima de 300 é eco de um PATCH seu. Trate a notificação como fonte legítima de mudança e reconcilie pelo par data.number + data.status. Combine na ativação quais etapas ficam com cada lado — dois sistemas avançando o mesmo pedido sem divisão acordada é a receita para status pulando para trás.

A fronteira que importa

PAYMENT_APPROVED é a fronteira. Antes dele, o pedido é da plataforma: carrinho, checkout, autorização de pagamento. Ao atingir esse status, o pedido é enviado ao seu ERP pelo webhook e a responsabilidade pela operação deixa de ser da plataforma.

Fronteira de responsabilidade, não de tráfego: notificações sobre pedidos que nunca chegam a 300 saem mesmo assim, e o seu endpoint precisa reconhecê-las e descartá-las.

Isso tem três consequências práticas:

Só em PAYMENT_APPROVED nasce um pedido no seu ERP. Carrinho abandonado nunca gera integração. Mas notificação você recebe antes: o limiar de publicação é PAYMENT_ERROR (250), não PAYMENT_APPROVED (300). Recusa de pagamento (250) e cancelamento pelo app (750/800) chegam ao seu endpoint como Order_Updated — e nenhum deles autoriza criar pedido ou reservar estoque. A lista fechada de valores está em Receber pedidos (webhook).
Depois dessa fronteira, quem dita o status é a operação, não a plataforma. O core não avança sozinho de ORDER_INVOICED para SHIPPED — ele espera ser informado, pelo seu PATCH ou pelos apps de Picking e Shipping, se a sua rede os contratar. Veja Atualizar status.
O PATCH que você faz volta como notificação para você. Toda mudança de status para um código maior ou igual a 250 reentra no seu webhook como Order_Updated, com o novo data.status — e com um operationId diferente do que o PATCH devolveu. Trate o próprio eco de forma idempotente, por data.number + data.status — a mesma regra vale para as mudanças feitas pelos apps de Picking e Shipping. Veja Atualizar status.

Estados que os dois lados movem

Cancelamento e estorno são bidirecionais: o cliente pode pedir cancelamento pelo app (gerando ORDER_CANCELLATION_ANALYSIS) e a operação pode cancelar por falta de produto na separação.

Este segundo diagrama responde a outra pergunta: para onde o pedido vai quando a sequência canônica não se completa?

Repare que POST /v1/Orders/{orderNumber}/cancel não leva direto a ORDER_CANCELLED: ele passa por ORDER_CANCELLATION_ANALYSIS, e a esteira de estorno (ORDER_CANCELLED → REFUND_IN_PROGRESS → REFUND_COMPLETED) corre por conta da plataforma. DELIVERY_FAILED e ORDER_RETURNED, ao contrário, só existem se a operação os enviar — pelo seu ERP ou pelo app de Shipping. Os detalhes de cada caminho estão em Cancelamento.