Status de pedido

Lista, consulta, cria, altera e remove o cadastro de status que um pedido pode ter, e lê os alfabetos de pagamento, seller e usuário.

Todo pedido tem um status, e o status é uma letra (O, P, S, C, I...). O cadastro de status da loja diz que letras existem, como cada uma se chama, a cor no painel e quem é avisado quando um pedido entra nela. Use estas rotas para montar o seletor de status de uma tela, para traduzir a letra que vem em Listar pedidos em um nome legível, ou para criar um status novo antes de usá-lo em Alterar o status.

Todas exigem um usuário administrador. As rotas também respondem sem o prefixo de versão (/api/statuses).

GET/api/v1.0/statusesAdmin

Listar os status

Devolve todos os status do tipo pedido, ou o alfabeto de outro tipo quando você manda type. A lista não é paginada.

Parâmetros de consulta

typestringpadrão: O

OPVU

Qual alfabeto devolver: O pedidos (cadastro da loja), P pagamento, V seller (lojista), U usuário. Aceita minúscula. Qualquer outro valor devolve os status de pedido.

GET/api/v1.0/statuses/{id}Admin

Consultar um status de pedido

Devolve um status de pedido pelo código. Só consulta o cadastro de pedidos: para os alfabetos de pagamento, seller e usuário use a lista com type.

Parâmetros de caminho

idstringobrigatório

Código do status (pending, shipped...).

POST/api/v1.0/statusesAdmin

Criar um status de pedido

Cria um status. Responde 201 com o código criado. O novo status nasce com a letra automática descrita acima.

Corpo da requisição

descriptionstringobrigatório

Nome que aparece para as pessoas (até 255 caracteres; HTML é removido).

statusstring

Código do status. Só letras, números, _ e -, até 32 caracteres, sem espaço. A plataforma grava em minúscula. Se faltar, o código sai do nome, em minúscula e com _ no lugar dos espaços.

typestring

Grupo do status: por exemplo initial, processing, shipped, complete, cancelled ou general.

colorstring

Cor no painel, em hexadecimal (#3b82f6).

positioninteger

Posição na ordenação. Padrão 0.

notify_customerboolean

Avisar o cliente quando o pedido entrar nesse status. Padrão false.

notify_vendorboolean

Avisar o seller. Padrão false.

notify_adminboolean

Avisar o administrador. Padrão false.

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

Alterar um status de pedido

Altera só o que você enviar. A letra e o código não mudam. Um campo com valor vazio ("") ou 0 é tratado como "não enviado", então esta rota não serve para zerar a posição.

Parâmetros de caminho

idstringobrigatório

Código do status.

Corpo da requisição

descriptionstring

Novo nome.

typestring

Novo grupo.

colorstring

Nova cor.

positioninteger

Nova posição (só vale acima de 0).

notify_customerboolean

Avisar o cliente.

notify_vendorboolean

Avisar o seller.

notify_adminboolean

Avisar o administrador.

DELETE/api/v1.0/statuses/{id}Admin

Remover um status de pedido

Remove o status do cadastro e responde 204 sem corpo. A plataforma recusa a remoção enquanto existir pedido nesse status, ou quando o status aparece no histórico ou nas transições configuradas. Nesses casos aposente o status em vez de apagar.

Parâmetros de caminho

idstringobrigatório

Código do status.

Exemplo de requisição

bash

# Lista os status de pedido
curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/v1.0/statuses"

# Cria um status
curl -u "$EMAIL:$API_KEY" -X POST "$BASE_URL/api/v1.0/statuses" \
  -H "Content-Type: application/json" \
  -d '{"description":"Aguardando retirada","status":"awaiting_pickup","type":"general","color":"#f59e0b","position":55,"notify_customer":true}'

Resposta

200Lista de status de pedido

json

{
  "statuses": [
    {
      "status_id": "pending",
      "description": "Pendente",
      "status": "O",
      "type": "initial",
      "color": "#f59e0b",
      "position": 20,
      "params": { "notify_customer": false, "notify_vendor": false, "notify_admin": false }
    },
    {
      "status_id": "shipped",
      "description": "Enviado",
      "status": "S",
      "type": "shipped",
      "color": "#8b5cf6",
      "position": 50,
      "params": { "notify_customer": true, "notify_vendor": true, "notify_admin": false }
    }
  ],
  "params": { "total_items": 2, "type": "O" }
}

201Status criado

json

{ "status_id": "awaiting_pickup" }

Campos da resposta

statusesarray

Os status. Para type=P, V e U os alfabetos são fixos.

statuses[].status_idstring

Código do status (id da rota).

statuses[].descriptionstring

Nome legível.

statuses[].statusstring

Letra, a que o pedido guarda.

statuses[].typestring

Grupo do status. Nos alfabetos fixos devolve a própria letra do tipo (P, V ou U).

statuses[].colorstring

Cor em hexadecimal; pode vir vazia.

statuses[].positioninteger

Ordem de exibição.

statuses[].paramsobject

Quem é avisado: notify_customer, notify_vendor e notify_admin, todos booleanos. Nos alfabetos fixos são sempre false.

params.total_itemsinteger

Quantidade de status devolvidos.

params.typestring

Tipo devolvido (O, P, V ou U).

Alfabetos fixos devolvidos por type:

Tipo	Letras
`P` pagamento	`O` aberto, `N` pendente, `A` autorizado, `P` pago, `F` falhou, `R` reembolsado, `Z` chargeback
`V` seller	`A` ativo, `P` pendente, `D` desativado, `R` rejeitado
`U` usuário	`A` ativo, `P` pendente, `D` desativado

Erros

Status	Quando	Corpo
400	Falta `description` na criação	`{"message":"description is required","status":400}`
400	Código com caractere inválido	`{"message":"code may only contain letters, digits, underscore, or hyphen (no spaces)","status":400}`
400	Remoção de status em uso por pedidos	`{"message":"status_in_use: 3 orders reference status pending","status":400}`
401	Sem credenciais	`{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}`
403	Usuário que não é administrador	`{"message":"Forbidden: admin scope required","status":403}`
404	Código que não existe (consulta e remoção)	`{"message":"status not found","status":404}`

Veja também

Status de pedido

Lista, consulta, cria, altera e remove o cadastro de status que um pedido pode ter, e lê os alfabetos de pagamento, seller e usuário.

Todas exigem um usuário administrador. As rotas também respondem sem o prefixo de versão (/api/statuses).

GET/api/v1.0/statusesAdmin

Listar os status

Devolve todos os status do tipo pedido, ou o alfabeto de outro tipo quando você manda type. A lista não é paginada.

Parâmetros de consulta

typestringpadrão: O

OPVU

Qual alfabeto devolver: O pedidos (cadastro da loja), P pagamento, V seller (lojista), U usuário. Aceita minúscula. Qualquer outro valor devolve os status de pedido.

GET/api/v1.0/statuses/{id}Admin

Consultar um status de pedido

Devolve um status de pedido pelo código. Só consulta o cadastro de pedidos: para os alfabetos de pagamento, seller e usuário use a lista com type.

Parâmetros de caminho

idstringobrigatório

Código do status (pending, shipped...).

POST/api/v1.0/statusesAdmin

Criar um status de pedido

Cria um status. Responde 201 com o código criado. O novo status nasce com a letra automática descrita acima.

Corpo da requisição

descriptionstringobrigatório

Nome que aparece para as pessoas (até 255 caracteres; HTML é removido).

statusstring

Código do status. Só letras, números, _ e -, até 32 caracteres, sem espaço. A plataforma grava em minúscula. Se faltar, o código sai do nome, em minúscula e com _ no lugar dos espaços.

typestring

Grupo do status: por exemplo initial, processing, shipped, complete, cancelled ou general.

colorstring

Cor no painel, em hexadecimal (#3b82f6).

positioninteger

Posição na ordenação. Padrão 0.

notify_customerboolean

Avisar o cliente quando o pedido entrar nesse status. Padrão false.

notify_vendorboolean

Avisar o seller. Padrão false.

notify_adminboolean

Avisar o administrador. Padrão false.

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

Alterar um status de pedido

Altera só o que você enviar. A letra e o código não mudam. Um campo com valor vazio ("") ou 0 é tratado como "não enviado", então esta rota não serve para zerar a posição.

Parâmetros de caminho

idstringobrigatório

Código do status.

Corpo da requisição

descriptionstring

Novo nome.

typestring

Novo grupo.

colorstring

Nova cor.

positioninteger

Nova posição (só vale acima de 0).

notify_customerboolean

Avisar o cliente.

notify_vendorboolean

Avisar o seller.

notify_adminboolean

Avisar o administrador.

DELETE/api/v1.0/statuses/{id}Admin

Remover um status de pedido

Parâmetros de caminho

idstringobrigatório

Código do status.

Exemplo de requisição

bash

# Lista os status de pedido
curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/v1.0/statuses"

# Cria um status
curl -u "$EMAIL:$API_KEY" -X POST "$BASE_URL/api/v1.0/statuses" \
  -H "Content-Type: application/json" \
  -d '{"description":"Aguardando retirada","status":"awaiting_pickup","type":"general","color":"#f59e0b","position":55,"notify_customer":true}'

Resposta

200Lista de status de pedido

json

{
  "statuses": [
    {
      "status_id": "pending",
      "description": "Pendente",
      "status": "O",
      "type": "initial",
      "color": "#f59e0b",
      "position": 20,
      "params": { "notify_customer": false, "notify_vendor": false, "notify_admin": false }
    },
    {
      "status_id": "shipped",
      "description": "Enviado",
      "status": "S",
      "type": "shipped",
      "color": "#8b5cf6",
      "position": 50,
      "params": { "notify_customer": true, "notify_vendor": true, "notify_admin": false }
    }
  ],
  "params": { "total_items": 2, "type": "O" }
}

201Status criado

json

{ "status_id": "awaiting_pickup" }

Campos da resposta

statusesarray

Os status. Para type=P, V e U os alfabetos são fixos.

statuses[].status_idstring

Código do status (id da rota).

statuses[].descriptionstring

Nome legível.

statuses[].statusstring

Letra, a que o pedido guarda.

statuses[].typestring

Grupo do status. Nos alfabetos fixos devolve a própria letra do tipo (P, V ou U).

statuses[].colorstring

Cor em hexadecimal; pode vir vazia.

statuses[].positioninteger

Ordem de exibição.

statuses[].paramsobject

Quem é avisado: notify_customer, notify_vendor e notify_admin, todos booleanos. Nos alfabetos fixos são sempre false.

params.total_itemsinteger

Quantidade de status devolvidos.

params.typestring

Tipo devolvido (O, P, V ou U).

Alfabetos fixos devolvidos por type:

Tipo	Letras
`P` pagamento	`O` aberto, `N` pendente, `A` autorizado, `P` pago, `F` falhou, `R` reembolsado, `Z` chargeback
`V` seller	`A` ativo, `P` pendente, `D` desativado, `R` rejeitado
`U` usuário	`A` ativo, `P` pendente, `D` desativado

Erros

Status	Quando	Corpo
400	Falta `description` na criação	`{"message":"description is required","status":400}`
400	Código com caractere inválido	`{"message":"code may only contain letters, digits, underscore, or hyphen (no spaces)","status":400}`
400	Remoção de status em uso por pedidos	`{"message":"status_in_use: 3 orders reference status pending","status":400}`
401	Sem credenciais	`{"message":"Authentication required. Use HTTP Basic with email:api_key or Bearer <jwt>.","status":401}`
403	Usuário que não é administrador	`{"message":"Forbidden: admin scope required","status":403}`
404	Código que não existe (consulta e remoção)	`{"message":"status not found","status":404}`