Fluxos operacionais

Automações sem código sobre pedidos, produtos, devoluções e novos usuários: gatilho, condições e ações.

Um fluxo operacional (ops flow, também chamado de automação) faz a plataforma agir sozinha quando algo acontece: "quando um pedido acima de R$ 1.000 for criado, avise a equipe", "quando um pagamento for recusado, mude o status". Ele é um grafo desenhado no painel: um gatilho, condições que desviam para sim ou não, ações e uma saída. Esta seção é a API que o editor visual usa. Os fluxos que os sellers (lojistas) criam para os próprios pedidos aparecem aqui na lista, com vendor_id.

Como funciona

Rascunho→Ativo→Pausado

`status`	Significado
`draft`	Recém-criado. Não executa.
`active`	Cada evento do gatilho cria uma execução.
`paused`	Não executa. Pode ser reativado. Fluxos apagados também ficam pausados.

Desenhar
Crie o fluxo com gatilho, condições, ações e saída.
Testar
Valide a estrutura com test.
Ativar
Ative. Cada evento passa a criar uma execução.
Acompanhar
Leia as execuções e seus passos para ver o que aconteceu.

Gatilhos

`trigger_type`	Quando dispara	Dados para condições
`order.created`	Pedido criado.	`order.total` (centavos), `order.item_count`, `order.payment_method`, `order.customer_id`
`order.statusChanged`	Status do pedido mudou.	`order.status`, `order.old_status`
`order.paymentStatusChanged`	Status do pagamento mudou.	`order.payment_status`
`order.chargeback`	Chargeback aberto.	`order.total` (centavos), `order.gateway`
`product.pending_moderation`	Produto aguarda moderação.	`product.vendor_id`
`return.statusChanged`	Status da devolução mudou.	`return.status`, `return.order_id`
`user.registered`	Cadastro de novo usuário.	`user.email`
`product.stockChanged`	Não dispara hoje.

Etapas e ações

Etapa	`config`
`trigger`	`{}`. Exatamente uma por fluxo.
`condition`	`field` (um dado do gatilho), `op` e o valor. Números: `op` em `gt`, `gte`, `lt`, `lte`, `eq`, `neq` com `value`. Textos (campos que terminam em `.status`, `_status` ou `.payment_method`, ou quando `str` é enviado): `op` em `eq`, `neq` com `str`. Campo desconhecido avalia como "não". As ligações saem com `branch` `yes` ou `no`.
`action`	`kind` e `params` (tabela abaixo).
`exit`	`{}`. Pelo menos uma.

`kind` da ação	`params`	Efeito
`notify_inbox`	`title` (obrigatório), `body`, `link`, `user_id`	Notificação no painel. Sem `user_id`, vai para quem criou o fluxo.
`set_order_status`	`status` (obrigatório), `notes`	Muda o status do pedido do evento, pelas regras de status normais.
`set_product_status`	`status`	Muda o status do produto do evento.
`send_email`	`subject` (obrigatório), `body`, `to`	Envia e-mail. Sem `to`, usa o e-mail do evento (`user.email`). Nunca é repetido em caso de falha.

Os tipos send_whatsapp, post_webhook e vi_action existem no catálogo, mas a execução falha com "action not supported in v1".

Conceitos-chave

Execução e passo

Uma execução é uma passagem do fluxo por um evento. Cada etapa percorrida grava um passo com o resultado (qual ramo da condição, o retorno da ação) ou o erro. Uma ação que falha marca a execução como failed; ações que podem ser repetidas com segurança (mudar status) são tentadas até 3 vezes.

Sem repetição

O mesmo evento nunca cria duas execuções do mesmo fluxo: a combinação de fluxo e evento é única.

Fluxos do seller

Sellers criam fluxos pelo painel deles, que agem só nos pedidos e produtos deles (vendor_id). A lista do administrador mostra todos.

Quem executa

As ações rodam como o sistema, usando os mesmos serviços das telas (assim o histórico de status e os eventos acontecem). Elas não passam pelos privilégios de quem criou o fluxo: quem pode ativar um fluxo pode fazer a plataforma agir.

Endpoints

Método	Caminho	Para que serve	Autenticação
GET	`/api/v1/admin/ops-flows`	Listar fluxos	admin
GET	`/api/v1/admin/ops-flows/{id}`	Consultar um fluxo	admin
POST	`/api/v1/admin/ops-flows`	Criar um fluxo	admin
PUT	`/api/v1/admin/ops-flows/{id}`	Substituir a definição de um fluxo	admin
DELETE	`/api/v1/admin/ops-flows/{id}`	Apagar um fluxo	admin
POST	`/api/v1/admin/ops-flows/{id}/test`	Validar o desenho (simulação)	admin
POST	`/api/v1/admin/ops-flows/{id}/activate`	Ativar um fluxo	admin
POST	`/api/v1/admin/ops-flows/{id}/pause`	Pausar um fluxo	admin
GET	`/api/v1/admin/ops-flows/{id}/runs`	Listar execuções de um fluxo	admin
GET	`/api/v1/admin/ops-flows/runs/{runId}/steps`	Passos de uma execução	admin

Erros comuns

Esperar que criar ou alterar valide o desenho: só test e activate validam.
Escrever valores em reais nas condições: use centavos.
Esquecer a saída (exit) ou deixar uma etapa sem ligação chegando: 422 invalid_graph.
Usar o gatilho product.stockChanged: ele é aceito, mas nunca dispara.
Usar ações send_whatsapp, post_webhook ou vi_action: a execução falha.
Reenviar só parte do fluxo no PUT: ele substitui nome, gatilho e desenho.
Confiar em runs_7d fora da lista: vem 0.

Próximos passos

Criar e alterar

Desenhe o fluxo.

Ativar, pausar e testar

Como autenticar as chamadas.

API atual/Referência completa