Mudar o status do pedido
Move o pedido do seller de um status para outro (enviado, entregue, cancelado) e consulta os próximos status possíveis.
O status diz em que etapa o pedido está. Mudá-lo é a operação mais importante do atendimento: baixa ou devolve estoque, avisa o cliente por e-mail, grava uma linha no histórico e, no cancelamento de um pedido já pago, estorna o pagamento. O seller muda o status do próprio sub-pedido e só para os destinos que a plataforma lhe permite (veja a tabela na visão geral).
Os códigos de status guardados no banco são letras (P, S...), mas nesta rota o seller envia o nome por extenso (shipped). Para saber que nome mandar, use a rota de próximos status.
Mudar o status
/api/v1/vendor/orders/{id}/statusSellerMuda o status de um pedido do seller
Sem fluxo de status personalizado na loja, o seller pode definir:
status | Quando |
|---|---|
shipped | Despachar. |
delivered | Confirmar a entrega. |
cancelled | Cancelar um pedido ainda não enviado, entregue, concluído, cancelado ou reembolsado. |
pending, processing, on_hold | Só para reabrir um pedido cancelled. |
Com o módulo order-status-flow ligado e uma matriz salva, quem manda é a coluna "seller" da matriz da loja, e a lista fixa acima deixa de valer (a trava do cancelamento continua).
Parâmetros de caminho
iduuidobrigatórioCorpo da requisição
statusstringobrigatórioshipped, delivered, cancelled...). Mandar a letra (S) é recusado quando a loja não usa fluxo próprio.reasonstringpublic_notestringExemplo de requisição: mudar o status
curl -X PUT "$BASE_URL/api/v1/vendor/orders/e148b6aa-d495-4b89-92ab-f38b5979a43f/status" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "status": "shipped", "public_note": "Saiu hoje pelos Correios" }'Resposta: mudar o status
{
"id": "e148b6aa-d495-4b89-92ab-f38b5979a43f",
"order_number": "PEDIDO-20261011-0001-V1",
"vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
"total": 24000,
"status": "S",
"status_text": "shipped",
"payment_status": "captured",
"updated_at": "2026-10-11T15:20:00.120000Z"
}A resposta é o pedido inteiro (campos como em Consultar pedidos), já com o novo status em letra e status_text por extenso.
Consultar os próximos status
/api/v1/vendor/orders/{id}/allowed-transitionsSellerLista os próximos status possíveis de um pedido
Devolve para onde o pedido pode ir a partir do status atual. Use-a para montar a lista de ações da tela em vez de fixar a lista no seu código.
Parâmetros de caminho
iduuidobrigatórioResposta: próximos status
{
"transitions": [
{ "code": "O", "label_key": "pending" },
{ "code": "H", "label_key": "on_hold" },
{ "code": "A", "label_key": "paid" },
{ "code": "S", "label_key": "shipped" },
{ "code": "I", "label_key": "cancelled" },
{ "code": "R", "label_key": "refunded" },
{ "code": "Z", "label_key": "chargeback" }
]
}{
"flow_active": true,
"transitions": [{ "code": "S", "label_key": "shipped" }],
"targets": [
{
"code": "shipped",
"letter_code": "S",
"name": "Shipped",
"name_pt": "Enviado",
"color": "#8b5cf6",
"requires_reason": false
}
]
}Campos da resposta
transitionsarraycode (a letra) e label_key (o código por extenso, que é o que a rota PUT .../status espera).flow_activeboolean | omittedtrue quando a loja usa fluxo de status personalizado. Ausente caso contrário.targetsarray | omittedname, name_pt), color, letter_code e requires_reason (se a mudança exige justificativa em reason).Erros
| Status | Quando | Corpo de exemplo |
|---|---|---|
| 401 | Token ausente ou inválido. | {"error":"missing authorization header"} |
| 403 | O token não é de um usuário seller, ou ele não tem privilégio de pedidos. | {"error":"insufficient vendor privileges","privilege_required_any":["vendor_view_orders", "..."]} |
| 403 | O pedido é de outro seller, é o pedido pai, ou está fora da carteira do representante. | {"error":"you do not have access to this order"} |
| 403 | Status de destino que o seller não pode definir. A frase em detail vem em português. | {"error":"vendor_status_not_allowed","detail":"O lojista só pode marcar o pedido como enviado, entregue ou cancelado, ou reabrir um pedido cancelado."} |
| 403 | Reabrir (pending, processing, on_hold) um pedido que não está cancelado. | {"error":"vendor_reopen_requires_cancelled","detail":"Só um pedido cancelado pode voltar para pendente, em processamento ou em espera."} |
| 403 | Fluxo da loja: o seller não pode fazer essa mudança. | {"error":"transition_not_allowed_for_actor","detail":"..."} |
| 400 | Corpo que não é JSON, ou status ausente. | {"error":"status is required"} |
| 400 | Mudança inválida a partir do status atual, ou status que a loja não tem. | {"error":"failed to update order status","detail":"invalid_transition: from delivered to P (...)"} |
| 400 | Fluxo da loja não prevê a transição. | {"error":"transition_not_in_flow","detail":"..."} |
| 404 | O pedido não existe. | {"error":"order not found"} |
| 409 | Cancelar um pedido já enviado, entregue, concluído, cancelado ou reembolsado. | {"error":"vendor_cancel_not_allowed","detail":"Não é possível cancelar um pedido com status \"S\": ..."} |
| 422 | O fluxo exige justificativa e reason veio vazio; ou o status de destino foi aposentado. | {"error":"reason_required","detail":"..."} ou {"error":"status_retired","detail":"..."} |
| 500 | Falha ao ler o pedido. | {"error":"failed to get order","detail":"..."} |