Atualizar status

Depois que o pedido chega ao ERP, é a operação que informa o andamento. Cada atualização aparece para o cliente no acompanhamento do app e dispara notificação.

Esta página trata do PATCH disparado pelo seu ERP. Se a sua rede contratar os aplicativos de Picking ou Shipping da Grocers, parte dessas transições passa a ser feita por eles — e o seu ERP recebe a mudança pelo webhook em vez de emiti-la. Veja Ciclo de vida do pedido.

Enviar

PATCH /v1/Orders/{orderNumber}/status


curl -X PATCH $GROCERS_API/v1/Orders/104821/status \
  -H "Authorization: Basic $BASIC" \
  -H "x-contractAccountId: $TENANT" \
  -H "Content-Type: application/json" \
  -d '{ "status": "ORDER_BEING_PREPARED" }'

Use o nome do status, não o código numérico:


{ "status": "SHIPPED" }

Respostas

Código	Significado	O que fazer
`200`	aceito e enfileirado — vem com `operationId`	guarde o `operationId`
`204`	o pedido já está nesse status	nada; não é erro
`400`	nome de status desconhecido no corpo	corrija o nome; retentar não resolve
`500`	falha no processamento — inclui número de pedido inexistente	limite a retentativa

Sequência esperada

A sequência canônica está definida em Ciclo de vida do pedido. Aplicada ao seu PATCH:

Separar vem antes de faturar. Emitir a nota antes da conferência da separação produz nota com valor diferente do cobrado sempre que houver item pesável, falta ou substituição — e em supermercado isso acontece na maioria dos pedidos. Veja Faturamento.

A plataforma não valida a transição: ela grava o status que você mandar, em qualquer ordem. Não espere um 400 para descobrir que a sequência saiu errada — não vem.

Consultar o status atual

GET /v1/Orders/{orderNumber}/status


curl $GROCERS_API/v1/Orders/104821/status \
  -H "Authorization: Basic $BASIC" -H "x-contractAccountId: $TENANT"

A resposta é um objeto com um único campo, o código numérico do status:


{ "status": 300 }

Útil antes de retentar: se o status já é o desejado, não há o que enviar. A tabela de código → nome está em Ciclo de vida do pedido.

Repare na assimetria: você escreve o nome ("ORDER_BEING_PREPARED") e lê o código (400). A tradução é sua.

Conciliação por data

GET /v1/Orders/by-date?date=2026-07-29


curl "$GROCERS_API/v1/Orders/by-date?date=2026-07-29" \
  -H "Authorization: Basic $BASIC" -H "x-contractAccountId: $TENANT"

A resposta é um array simples de número e status:


[
  { "number": 104821, "status": 300 },
  { "number": 104822, "status": 700 },
  { "number": 104823, "status": 800 }
]

Item	Comportamento
Formato da data	`yyyy-MM-dd`. Data ausente devolve `400` com `A data é obrigatória e deve estar no formato válido (yyyy-MM-dd)`
Fuso	o dia é interpretado no horário de Brasília (UTC−3), não em UTC
Critério	pedidos do tenant que tiveram qualquer mudança de status naquele dia — não os criados naquele dia
Status devolvido	o status atual do pedido, não o do dia consultado
Paginação	não é paginada. Devolve o dia inteiro em uma resposta
Carrinhos	excluídos — `CART_CREATED` e `PaymentInProgress` não aparecem

Sem paginação, um dia de pico devolve tudo de uma vez. Em operação com dezenas de milhares de pedidos/dia, dimensione o timeout e a memória do job de conciliação — não existe page/pageSize para fatiar.

Lista os pedidos e status de um dia — a forma prática de conferir se algum pedido ficou parado no seu lado sem que ninguém percebesse.

Rode diariamente

Compare a lista da plataforma com os pedidos do ERP naquele dia.

Investigue os divergentes

Pedido que na plataforma está em PAYMENT_APPROVED mas no ERP não existe significa webhook não entregue ou não processado.

Corrija o status parado

Pedido entregue fisicamente mas ainda em SHIPPED na plataforma gera reclamação de cliente e trava a conciliação financeira.

Boas práticas

Não pule etapas. O cliente acompanha a sequência; saltar de ORDER_BEING_PREPARED direto para DELIVERED parece falha do app. A plataforma aceita o salto sem reclamar — a disciplina é sua.
Atualize no momento do fato, não em lote no fim do dia. O valor do status está em ser tempo real.
DELIVERED é definitivo. Depois dele, só cancelamento com estorno resolve. Não marque como entregue na saída do veículo.

Marcar DELIVERED na expedição em vez de na entrega efetiva quebra a conciliação quando há falha de entrega — o pedido consta como entregue e o estorno vira processo manual.