Documentação de Status de Pedido

Visão Geral

Este módulo trata do cadastro de status de pedido da loja em /orders/status — ou seja, dos estados que a própria loja define para representar a evolução de um pedido, como “em separação”, “enviado” ou “cancelado”.

Aqui você pode listar, criar, editar e remover esses status, que funcionam como um catálogo reutilizável ao longo do fluxo dos pedidos.

As operações de consulta (GET) utilizam o escopo ORDER_READ. Já ações que alteram esse cadastro (POST, PUT, DELETE) exigem ORDER_WRITE.

> Importante: este módulo não altera o status de pedidos específicos. Ele apenas gerencia os tipos de status disponíveis.

Para mudar o status de um pedido (individualmente ou em lote), utilize as rotas do módulo de Pedidos.

Entidades Envolvidas

• Status de pedido (order status): entidade configurável, identificada por orderStatusId nas rotas de atualização e exclusão.
• Pedido: consome os status cadastrados nas transições de ciclo de vida; a regra de qual status se aplica em cada momento está na lógica de negócio do pedido, não neste CRUD isolado.

Notas e Considerações

• Antes de remover um status, verifique dependências na loja (pedidos em andamento, regras de automação); a API pode retornar erro de negócio se o status estiver em uso.
• Use a listagem para obter identificadores e códigos antes de atualizar ou excluir.

Listagem de Status de Pedidos

Descrição

Este endpoint fornece a árvore completa de status que podem ser aplicados aos pedidos. O acesso exige o escopo de permissão ORDER_READ.

A estrutura é retornada de forma hierárquica, permitindo organizar o fluxo operacional com status principais e sub-status. Isso facilita a gestão de fluxos complexos como faturamento e entrega.

Cada registro contém o nome descritivo, um código único identificador e o ícone associado para exibição nas interfaces administrativas da loja.

Parâmetros

Headers Obrigatórios

Exemplo de Requisição

1curl --request GET \
2  --url {{MAIN_URL}}/orders/status \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

1[
2  {
3    "id": 1,
4    "orderStatusParentId": 0,
5    "code": "new",
6    "name": "Novo",
7    "icon": "plus",
8    "children": [
9      {
10        "id": 10,
11        "orderStatusParentId": 1,
12        "code": "awaiting-payment",
13        "name": "Aguardando Pagamento",
14        "icon": "clock"
15      }
16    ]
17  }
18]

Cadastro de Status de Pedido

Descrição

Este endpoint permite a criação de novos status personalizados para o fluxo de pedidos. O acesso exige o escopo de permissão ORDER_WRITE.

O campo code deve ser único entre os status de pedido da loja, pois é utilizado como identificador textual fixo para mapeamento de regras de negócio e integrações automáticas.

Parâmetros

Headers Obrigatórios

Parâmetros de Corpo

Exemplo de Requisição

1curl --request POST \
2  --url {{MAIN_URL}}/orders/status \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "orderStatusParentId": 1,
7    "name": "Aguardando Retirada",
8    "code": "awaiting-pickup",
9    "icon": "package"
10  }'

✅ Resposta de Sucesso

1{
2  "id": 100,
3  "orderStatusParentId": 1,
4  "code": "awaiting-pickup",
5  "name": "Aguardando Retirada",
6  "icon": "package",
7	"children": []
8}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Atualização de Status de Pedido

Descrição

Este endpoint permite a modificação dos atributos de um status de pedido já existente. O acesso exige o escopo de permissão ORDER_WRITE.

É possível alterar o nome descritivo, o código textual e o ícone. A validade do código é verificada para garantir que não existam duplicidades no sistema.

Status fundamentais para o funcionamento automático da plataforma podem possuir restrições de edição para preservar a integridade dos processos de faturamento e estoque.

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Parâmetros de Corpo

Exemplo de Requisição

1curl --request PUT \
2  --url {{MAIN_URL}}/orders/status/100 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI" \
4  --header "Content-Type: application/json" \
5  --data '{
6    "name": "Pronto para Retirada",
7    "code": "ready-for-pickup",
8    "icon": "box"
9  }'

✅ Resposta de Sucesso

1{
2  "id": 100,
3  "orderStatusParentId": 1,
4  "code": "ready-for-pickup",
5  "name": "Pronto para Retirada",
6  "icon": "box",
7	"children": []
8}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.

Exclusão de Status de Pedido

Descrição

Este endpoint permite a remoção definitiva de um status do sistema. O acesso exige o escopo de permissão ORDER_WRITE.

A exclusão é uma operação sensível e está sujeita a validações de integridade: não é possível remover status vinculados a pedidos existentes ou status nativos e protegidos da plataforma.

Caso o status possua filhos (sub-status), estes devem ser removidos ou transferidos antes da exclusão do status pai, garantindo a consistência da árvore de status.

Parâmetros

Headers Obrigatórios

Parâmetros da URL

Exemplo de Requisição

1curl --request DELETE \
2  --url {{MAIN_URL}}/orders/status/100 \
3  --header "Authorization: Bearer SEU_TOKEN_AQUI"

✅ Resposta de Sucesso

1{
2  "status": true
3}

⚠️ Possíveis erros:

Atenção: a seguir estão destacados os principais erros que podem ocorrer neste endpoint.

Os cenários descritos representam os erros mais relevantes do contexto atual, servindo como referência para entendimento e tratamento das falhas.