Fluxo de status personalizado

Define quais mudanças de status cada papel (administrador, seller, sistema) pode fazer na loja, valida o desenho e aplica um modelo pronto.

Por padrão, a plataforma aceita as transições de status descritas em Alterar o status. Lojas com um processo próprio (por exemplo, B2B com cinco etapas: pedido recebido, aprovado, faturado, enviado, entregue) podem ativar o recurso de fluxo de status e desenhar a própria matriz de transições: de qual status para qual, quem pode fazer a mudança e se ela exige uma justificativa.

Com o fluxo ativo:

Só as transições da matriz são aceitas. A matriz pode apenas restringir o que a plataforma já permite; nunca libera o que as regras da plataforma proíbem (por exemplo, sair de reembolsado).
Cada transição diz se vale para o administrador, para o seller e para o sistema (integrações, gateways).
Uma transição pode exigir justificativa; sem ela, a mudança responde 422 reason_required.
O administrador com o privilégio force_order_transition pode forçar uma mudança fora da matriz, com motivo (Alterar o status).
O acompanhamento ao cliente (Rastreio) usa as etapas marcadas como main.

GET/api/v1/admin/order-status-flowAdmin

Consulta o fluxo de status

Devolve a matriz salva, os status com seus campos de fluxo e quantos pedidos há em cada status. Exige manage_order_workflows ou manage_order_statuses.

PUT/api/v1/admin/order-status-flowAdmin

Salva o fluxo de status

Substitui a matriz inteira em uma transação, e só se ela for válida. Uma lista de transições vazia devolve a loja às regras da plataforma. Também permite, no mesmo envio, editar campos de fluxo de status existentes e criar status novos. Exige manage_order_workflows; editar ou criar status exige também manage_order_statuses.

Corpo da requisição

transitionsarrayobrigatório

Todas as transições permitidas.

from_codestringobrigatório

Código do status de origem.

to_codestringobrigatório

Código do status de destino.

allow_adminboolean

Administradores podem fazer esta mudança.

allow_vendorboolean

Sellers podem fazer esta mudança.

allow_systemboolean

Integrações e gateways podem fazer esta mudança.

requires_reasonboolean

A mudança exige justificativa (notes ou reason).

positionsobject

Posições dos quadros no editor visual: mapa código para {"x":0,"y":0}. Omitido, mantém as posições salvas; {} apaga todas.

status_changesarray

Edições em status existentes.

codestringobrigatório

Status a editar.

flow_stagestring

maintechnicalexception

Etapa do fluxo.

is_activeboolean

Ativo ou aposentado.

visible_to_customerboolean

Visível ao cliente.

visible_to_vendorboolean

Visível ao seller.

new_statusesarray

Status criados junto com o fluxo.

codestringobrigatório

Código novo (único).

namestringobrigatório

Nome.

colorstring

Cor hexadecimal.

flow_stagestring

maintechnicalexception

Etapa do fluxo.

is_activeboolean

Ativo (padrão sim).

visible_to_customerboolean

Visível ao cliente (padrão sim).

visible_to_vendorboolean

Visível ao seller (padrão sim).

POST/api/v1/admin/order-status-flow/validateAdmin

Valida um rascunho de fluxo de status

Confere um rascunho sem gravar nada e responde o que o PUT diria. Use antes de salvar. Mesmo corpo do PUT. Exige manage_order_workflows.

POST/api/v1/admin/order-status-flow/templates/{key}Admin

Apply a ready-made flow template

Aplica um modelo pronto de fluxo: cria os status que faltam e grava a matriz do modelo. O único modelo disponível é b2b-five-steps (cinco etapas B2B). Exige manage_order_workflows.

Path parameters

keystringobrigatório

Chave do modelo: b2b-five-steps. Outra chave responde 404 template_not_found.

Corpo da requisição (opcional)

rename_labelsbooleanpadrão: false

true renomeia os status existentes para os nomes do modelo.

GET/api/v1/admin/order-status-blockAdmin

Status-change blocking settings (compatibility)

Devolve a configuração de bloqueio de mudança de status herdada do painel da plataforma antiga. Hoje é uma resposta fixa (bloqueio desligado), mantida por compatibilidade com telas migradas; não use para decidir nada.

Exemplo de requisição

bash

# Valida o rascunho antes de salvar
curl -X POST "$BASE_URL/api/v1/admin/order-status-flow/validate" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "transitions": [
      { "from_code": "pending", "to_code": "processing", "allow_admin": true, "allow_system": true },
      { "from_code": "processing", "to_code": "shipped", "allow_admin": true, "allow_vendor": true },
      { "from_code": "shipped", "to_code": "delivered", "allow_admin": true, "allow_vendor": true, "allow_system": true },
      { "from_code": "processing", "to_code": "pending", "allow_admin": true, "requires_reason": true }
    ]
  }'

Resposta

200Rascunho validado

json

{
  "valid": true,
  "issues": [
    {
      "severity": "warning",
      "code": "unreachable_status",
      "status": "on_hold",
      "message": "status \"on_hold\" is only reached outside this flow (payment, integration or existing orders)"
    }
  ]
}

200Fluxo lido

json

{
  "enabled": true,
  "active": true,
  "can_manage_statuses": true,
  "updated_at": "2026-10-11T22:00:00Z",
  "order_counts": { "pending": 12, "processing": 4, "shipped": 30 },
  "positions": {},
  "transitions": [
    { "from_code": "pending", "to_code": "processing", "allow_admin": true, "allow_vendor": false, "allow_system": true, "requires_reason": false }
  ],
  "statuses": [
    { "code": "pending", "letter_code": "O", "name": "Pendente", "flow_stage": "main", "is_active": true }
  ]
}

422Matriz inválida (PUT)

json

{
  "error": "validation_failed",
  "issues": [
    { "severity": "error", "code": "self_transition", "from_code": "pending", "to_code": "pending", "message": "a status cannot transition to itself" }
  ]
}

200order-status-block

json

{
  "enabled": false,
  "blocking_cancelled_statuses": [],
  "customer_auto_block_threshold": null
}

Campos da resposta

enabledboolean

O recurso está ligado na loja.

activeboolean

Há uma matriz salva. Só com enabled e active as transições são consultadas.

transitionsarray

A matriz salva.

statusesarray

Os status da loja (formato de Status de pedido).

order_countsobject

Pedidos em cada status, para você medir o efeito de uma mudança.

positionsobject

Posições dos quadros no editor.

can_manage_statusesboolean

O usuário também tem manage_order_statuses.

validboolean

(validate) false se há algum problema com severity: "error".

issuesarray

Problemas achados. severity é error (bloqueia o salvamento) ou warning. code é estável e legível por máquina; message é um texto em inglês de apoio.

flowobject

(PUT/modelo) O fluxo depois de salvo.

created_statusesarray

(PUT/modelo) Códigos dos status criados.

renamed_statusesarray

(modelo) Códigos dos status renomeados.

Problemas que a validação aponta

`code`	`severity`	Significado
`missing_code`	error	Uma transição sem origem ou destino.
`self_transition`	error	Origem igual ao destino.
`duplicate_transition`	error	O mesmo par origem/destino repetido.
`unknown_status`	error	Status que não existe no cadastro.
`no_actor`	error	Transição que nenhum papel (administrador, seller, sistema) pode fazer.
`retired_target`	error	Destino aposentado (`is_active: false`).
`platform_forbidden`	error	A plataforma proíbe esta mudança (por exemplo, sair de reembolsado).
`backward_without_reason`	error	Voltar para uma etapa anterior sem exigir justificativa.
`no_initial_exit`	error	O status inicial (`pending`) não tem nenhuma saída.
`no_final_state`	error	Nenhum status final alcançável.
`unreachable_main_stage`	error	Etapa principal que não pode ser alcançada a partir de `pending`.
`main_stage_missing`	error	Etapa principal sem nenhuma transição.
`unreachable_status`	warning	Status que só é alcançado fora deste fluxo (pagamento, integração ou pedidos que já estavam nele).
`orders_without_exit`	warning	Há pedidos num status que a matriz não deixa sair.
`invalid_flow_stage`	error	`flow_stage` fora de `main`, `technical`, `exception`.
`new_status_name_required`, `new_status_code_invalid`, `new_status_code_taken`	error	Problemas em `new_statuses`.
`template_status_missing`	warning	O modelo cita um status que a loja não tem.

Erros

Status	Quando	Corpo
400	Corpo inválido	`{"error":"invalid request body"}`
401	Sem token ou token expirado	`{"error":"invalid or expired token"}`
403	Recurso desligado; sem `manage_order_workflows`; ou editar status sem `manage_order_statuses`	`{"error":"module_disabled","module":"order-status-flow"}` ou `{"error":"forbidden","detail":"manage_order_statuses is required to create or edit statuses"}`
404	Modelo inexistente	`{"error":"template_not_found"}`
422	A matriz tem erros	`{"error":"validation_failed","issues":[...]}`
503	Banco da loja ainda sem as tabelas do recurso	`{"error":"status_flow_unavailable"}`

Veja também

Fluxo de status personalizado

Define quais mudanças de status cada papel (administrador, seller, sistema) pode fazer na loja, valida o desenho e aplica um modelo pronto.

Com o fluxo ativo:

Só as transições da matriz são aceitas. A matriz pode apenas restringir o que a plataforma já permite; nunca libera o que as regras da plataforma proíbem (por exemplo, sair de reembolsado).
Cada transição diz se vale para o administrador, para o seller e para o sistema (integrações, gateways).
Uma transição pode exigir justificativa; sem ela, a mudança responde 422 reason_required.
O administrador com o privilégio force_order_transition pode forçar uma mudança fora da matriz, com motivo (Alterar o status).
O acompanhamento ao cliente (Rastreio) usa as etapas marcadas como main.

GET/api/v1/admin/order-status-flowAdmin

Consulta o fluxo de status

Devolve a matriz salva, os status com seus campos de fluxo e quantos pedidos há em cada status. Exige manage_order_workflows ou manage_order_statuses.

PUT/api/v1/admin/order-status-flowAdmin

Salva o fluxo de status

Corpo da requisição

transitionsarrayobrigatório

Todas as transições permitidas.

from_codestringobrigatório

Código do status de origem.

to_codestringobrigatório

Código do status de destino.

allow_adminboolean

Administradores podem fazer esta mudança.

allow_vendorboolean

Sellers podem fazer esta mudança.

allow_systemboolean

Integrações e gateways podem fazer esta mudança.

requires_reasonboolean

A mudança exige justificativa (notes ou reason).

positionsobject

Posições dos quadros no editor visual: mapa código para {"x":0,"y":0}. Omitido, mantém as posições salvas; {} apaga todas.

status_changesarray

Edições em status existentes.

codestringobrigatório

Status a editar.

flow_stagestring

maintechnicalexception

Etapa do fluxo.

is_activeboolean

Ativo ou aposentado.

visible_to_customerboolean

Visível ao cliente.

visible_to_vendorboolean

Visível ao seller.

new_statusesarray

Status criados junto com o fluxo.

codestringobrigatório

Código novo (único).

namestringobrigatório

Nome.

colorstring

Cor hexadecimal.

flow_stagestring

maintechnicalexception

Etapa do fluxo.

is_activeboolean

Ativo (padrão sim).

visible_to_customerboolean

Visível ao cliente (padrão sim).

visible_to_vendorboolean

Visível ao seller (padrão sim).

POST/api/v1/admin/order-status-flow/validateAdmin

Valida um rascunho de fluxo de status

Confere um rascunho sem gravar nada e responde o que o PUT diria. Use antes de salvar. Mesmo corpo do PUT. Exige manage_order_workflows.

POST/api/v1/admin/order-status-flow/templates/{key}Admin

Apply a ready-made flow template

Aplica um modelo pronto de fluxo: cria os status que faltam e grava a matriz do modelo. O único modelo disponível é b2b-five-steps (cinco etapas B2B). Exige manage_order_workflows.

Path parameters

keystringobrigatório

Chave do modelo: b2b-five-steps. Outra chave responde 404 template_not_found.

Corpo da requisição (opcional)

rename_labelsbooleanpadrão: false

true renomeia os status existentes para os nomes do modelo.

GET/api/v1/admin/order-status-blockAdmin

Status-change blocking settings (compatibility)

Exemplo de requisição

bash

# Valida o rascunho antes de salvar
curl -X POST "$BASE_URL/api/v1/admin/order-status-flow/validate" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "transitions": [
      { "from_code": "pending", "to_code": "processing", "allow_admin": true, "allow_system": true },
      { "from_code": "processing", "to_code": "shipped", "allow_admin": true, "allow_vendor": true },
      { "from_code": "shipped", "to_code": "delivered", "allow_admin": true, "allow_vendor": true, "allow_system": true },
      { "from_code": "processing", "to_code": "pending", "allow_admin": true, "requires_reason": true }
    ]
  }'

Resposta

200Rascunho validado

json

{
  "valid": true,
  "issues": [
    {
      "severity": "warning",
      "code": "unreachable_status",
      "status": "on_hold",
      "message": "status \"on_hold\" is only reached outside this flow (payment, integration or existing orders)"
    }
  ]
}

200Fluxo lido

json

{
  "enabled": true,
  "active": true,
  "can_manage_statuses": true,
  "updated_at": "2026-10-11T22:00:00Z",
  "order_counts": { "pending": 12, "processing": 4, "shipped": 30 },
  "positions": {},
  "transitions": [
    { "from_code": "pending", "to_code": "processing", "allow_admin": true, "allow_vendor": false, "allow_system": true, "requires_reason": false }
  ],
  "statuses": [
    { "code": "pending", "letter_code": "O", "name": "Pendente", "flow_stage": "main", "is_active": true }
  ]
}

422Matriz inválida (PUT)

json

{
  "error": "validation_failed",
  "issues": [
    { "severity": "error", "code": "self_transition", "from_code": "pending", "to_code": "pending", "message": "a status cannot transition to itself" }
  ]
}

200order-status-block

json

{
  "enabled": false,
  "blocking_cancelled_statuses": [],
  "customer_auto_block_threshold": null
}

Campos da resposta

enabledboolean

O recurso está ligado na loja.

activeboolean

Há uma matriz salva. Só com enabled e active as transições são consultadas.

transitionsarray

A matriz salva.

statusesarray

Os status da loja (formato de Status de pedido).

order_countsobject

Pedidos em cada status, para você medir o efeito de uma mudança.

positionsobject

Posições dos quadros no editor.

can_manage_statusesboolean

O usuário também tem manage_order_statuses.

validboolean

(validate) false se há algum problema com severity: "error".

issuesarray

Problemas achados. severity é error (bloqueia o salvamento) ou warning. code é estável e legível por máquina; message é um texto em inglês de apoio.

flowobject

(PUT/modelo) O fluxo depois de salvo.

created_statusesarray

(PUT/modelo) Códigos dos status criados.

renamed_statusesarray

(modelo) Códigos dos status renomeados.

Problemas que a validação aponta

`code`	`severity`	Significado
`missing_code`	error	Uma transição sem origem ou destino.
`self_transition`	error	Origem igual ao destino.
`duplicate_transition`	error	O mesmo par origem/destino repetido.
`unknown_status`	error	Status que não existe no cadastro.
`no_actor`	error	Transição que nenhum papel (administrador, seller, sistema) pode fazer.
`retired_target`	error	Destino aposentado (`is_active: false`).
`platform_forbidden`	error	A plataforma proíbe esta mudança (por exemplo, sair de reembolsado).
`backward_without_reason`	error	Voltar para uma etapa anterior sem exigir justificativa.
`no_initial_exit`	error	O status inicial (`pending`) não tem nenhuma saída.
`no_final_state`	error	Nenhum status final alcançável.
`unreachable_main_stage`	error	Etapa principal que não pode ser alcançada a partir de `pending`.
`main_stage_missing`	error	Etapa principal sem nenhuma transição.
`unreachable_status`	warning	Status que só é alcançado fora deste fluxo (pagamento, integração ou pedidos que já estavam nele).
`orders_without_exit`	warning	Há pedidos num status que a matriz não deixa sair.
`invalid_flow_stage`	error	`flow_stage` fora de `main`, `technical`, `exception`.
`new_status_name_required`, `new_status_code_invalid`, `new_status_code_taken`	error	Problemas em `new_statuses`.
`template_status_missing`	warning	O modelo cita um status que a loja não tem.

Erros

Status	Quando	Corpo
400	Corpo inválido	`{"error":"invalid request body"}`
401	Sem token ou token expirado	`{"error":"invalid or expired token"}`
403	Recurso desligado; sem `manage_order_workflows`; ou editar status sem `manage_order_statuses`	`{"error":"module_disabled","module":"order-status-flow"}` ou `{"error":"forbidden","detail":"manage_order_statuses is required to create or edit statuses"}`
404	Modelo inexistente	`{"error":"template_not_found"}`
422	A matriz tem erros	`{"error":"validation_failed","issues":[...]}`
503	Banco da loja ainda sem as tabelas do recurso	`{"error":"status_flow_unavailable"}`