Alterar o status

Move o pedido de um status para outro (processando, enviado, entregue, cancelado...) enviando a letra do novo status.

O status diz em que etapa o pedido está. Mudá-lo é a operação mais importante do ciclo de vida: ela baixa ou devolve estoque, dispara e-mails ao cliente, atualiza os relatórios e grava uma linha no histórico. Esta página descreve a rota que muda o status.

A lista de status existentes, com a letra e o significado de cada um, está na home da seção. Cada loja tem o seu cadastro de status: antes de integrar, peça ao administrador da loja o cadastro com as letras.

PUT/api/v1.0/orders/{id}Admin

Mudar o status de um pedido

É a mesma rota de Alterar pedido. Ela vira "mudança de status" quando o corpo tem somente estas chaves: status, notify_user, notify_department, notify_vendor.

O comportamento é o da Venddor 1.0:

A letra é gravada como veio (maiúscula ou minúscula). Ela precisa existir no cadastro de status da loja; senão a resposta é 400.
Não há matriz de transição: pode ir de qualquer letra para qualquer letra, em qualquer ordem.
Se o pedido já está nesse status, a resposta é 200 e nada muda (a chamada é idempotente).
A mudança não estorna o pagamento no gateway, mesmo para cancelado ou reembolsado. Cancelar o pedido não devolve o dinheiro do cliente; o estorno é uma operação separada (veja Reembolsos).
Estoque, e-mails de status, comissões e demais reações do status continuam acontecendo.

Parâmetros de caminho

idstringobrigatório

Id do pedido (UUID; decimal em string em /api/orders/{id}).

Corpo da requisição

statusstringobrigatório

Letra do novo status (P, S, C, I...). Use sempre a letra. Um nome com mais de um caractere passa por uma tabela antiga (pending, processing, completed, refunded, failed, cancelled, on_hold) e qualquer nome fora dela vira pending sem erro: {"status":"shipped"} devolve o pedido para pendente.

notify_userstring

YNtruefalse10

Pedido para avisar o cliente. Fica registrado nas observações do histórico (notify_user=Y). O e-mail só sai se o status de destino estiver configurado para notificar o cliente.

notify_departmentstring

Aceito por compatibilidade, sem efeito.

notify_vendorstring

Aceito por compatibilidade, sem efeito.

Exemplo de requisição

bash

# Marcar como enviado, pela letra
curl -X PUT "$BASE_URL/api/v1.0/orders/$ORDER_ID" \
  -u "$EMAIL:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"S","notify_user":"Y"}'

Resposta

200API 1.0: status alterado

json

{ "order_id": "0932405c-a8c1-49b3-a7db-61aab4c4d666" }

Campos da resposta

order_idstring

Id do pedido. A resposta não traz o status novo; consulte o pedido se precisar confirmar.

Efeitos da mudança de status

Ao entrar em...	O que acontece
cancelado, reembolsado, falho	O estoque dos itens é devolvido. O pagamento não é estornado.
enviado	A data de envio é preenchida; o cliente pode receber o e-mail de envio.
entregue	A data de entrega é preenchida.
qualquer status	Uma linha entra no histórico de status (letra de origem, letra de destino, observações) e as reações configuradas (e-mails, comissões, integrações) acontecem.

Erros

Status	Quando	Corpo
400	Falta `status`	`{"message":"status is required","status":400}`
400	A letra não existe no cadastro de status da loja	`{"message":"invalid_transition: from pending to Q (unknown status)","status":400}`
401	Sem credenciais ou chave de API inválida	`{"message":"Invalid credentials","status":401}`
403	Usuário que não é administrador	`{"message":"Forbidden: admin scope required","status":403}`
500	Pedido inexistente em alguns caminhos; falha interna	`{"error":"failed to update order status","detail":"..."}`

Veja também

Alterar o status

Move o pedido de um status para outro (processando, enviado, entregue, cancelado...) enviando a letra do novo status.

PUT/api/v1.0/orders/{id}Admin

Mudar o status de um pedido

É a mesma rota de Alterar pedido. Ela vira "mudança de status" quando o corpo tem somente estas chaves: status, notify_user, notify_department, notify_vendor.

O comportamento é o da Venddor 1.0:

A letra é gravada como veio (maiúscula ou minúscula). Ela precisa existir no cadastro de status da loja; senão a resposta é 400.
Não há matriz de transição: pode ir de qualquer letra para qualquer letra, em qualquer ordem.
Se o pedido já está nesse status, a resposta é 200 e nada muda (a chamada é idempotente).
A mudança não estorna o pagamento no gateway, mesmo para cancelado ou reembolsado. Cancelar o pedido não devolve o dinheiro do cliente; o estorno é uma operação separada (veja Reembolsos).
Estoque, e-mails de status, comissões e demais reações do status continuam acontecendo.

Parâmetros de caminho

idstringobrigatório

Id do pedido (UUID; decimal em string em /api/orders/{id}).

Corpo da requisição

statusstringobrigatório

notify_userstring

YNtruefalse10

Pedido para avisar o cliente. Fica registrado nas observações do histórico (notify_user=Y). O e-mail só sai se o status de destino estiver configurado para notificar o cliente.

notify_departmentstring

Aceito por compatibilidade, sem efeito.

notify_vendorstring

Aceito por compatibilidade, sem efeito.

Exemplo de requisição

bash

# Marcar como enviado, pela letra
curl -X PUT "$BASE_URL/api/v1.0/orders/$ORDER_ID" \
  -u "$EMAIL:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"S","notify_user":"Y"}'

Resposta

200API 1.0: status alterado

json

{ "order_id": "0932405c-a8c1-49b3-a7db-61aab4c4d666" }

Campos da resposta

order_idstring

Id do pedido. A resposta não traz o status novo; consulte o pedido se precisar confirmar.

Efeitos da mudança de status

Ao entrar em...	O que acontece
cancelado, reembolsado, falho	O estoque dos itens é devolvido. O pagamento não é estornado.
enviado	A data de envio é preenchida; o cliente pode receber o e-mail de envio.
entregue	A data de entrega é preenchida.
qualquer status	Uma linha entra no histórico de status (letra de origem, letra de destino, observações) e as reações configuradas (e-mails, comissões, integrações) acontecem.

Erros

Status	Quando	Corpo
400	Falta `status`	`{"message":"status is required","status":400}`
400	A letra não existe no cadastro de status da loja	`{"message":"invalid_transition: from pending to Q (unknown status)","status":400}`
401	Sem credenciais ou chave de API inválida	`{"message":"Invalid credentials","status":401}`
403	Usuário que não é administrador	`{"message":"Forbidden: admin scope required","status":403}`
500	Pedido inexistente em alguns caminhos; falha interna	`{"error":"failed to update order status","detail":"..."}`