Fluxos de automação
Como o seller cria automações do tipo "quando X acontecer, faça Y" pela API do painel do seller.
Um fluxo é uma automação do seller (lojista) no formato "quando acontecer X, e se Y, faça Z". Por exemplo: "quando entrar um pedido, e se o total passar de R$ 1.000, avise minha equipe". O seller desenha o fluxo como um grafo (um gatilho, condições, ações e uma saída), ativa, e a plataforma passa a executá-lo sozinha a cada evento. Esta seção documenta as onze rotas /api/v1/vendor/flows.
Como funciona
status | Significado |
|---|---|
draft | Recém-criado. Não executa. |
active | Ligado. Cada evento do gatilho cria uma execução. |
paused | Desligado por pause (ou ao apagar). Execuções em andamento ficam paradas até o fluxo ser reativado. |
- Escolha o gatilho e as ações
GET /vendor/flows/cataloglista os gatilhos e as ações disponíveis. - Crie o fluxo
POST /vendor/flowscom o nome, o gatilho e o grafo. O fluxo fica em rascunho. - Valide
POST /vendor/flows/{id}/testconfere o grafo sem executar nada. - Ative
POST /vendor/flows/{id}/activaterevalida e liga. A partir daí cada evento do gatilho cria uma execução (run). - Acompanhe
GET /vendor/flows/{id}/runslista as execuções eGET /vendor/flows/runs/{runId}/stepsmostra, passo a passo, o que cada uma fez.
Conceitos-chave
O grafo
O graph tem nodes (passos) e edges (ligações). Regras que a ativação confere: exatamente um passo trigger, pelo menos um exit, e nenhum passo (além do gatilho) sem ligação de entrada.
type | O que faz | config |
|---|---|---|
trigger | Ponto de partida. Um só. | {} |
condition | Testa um valor do evento e segue pelo ramo yes ou no. | field, op e value (número) ou str (texto). |
action | Faz algo. | kind e params. |
exit | Encerra a execução com sucesso. | {} |
Condição. field é um dado do evento (tabela abaixo) e op é gt, gte, lt, lte, eq ou neq. Campos de texto (terminados em .status, .payment_method ou _status) comparam com str e só aceitam eq e neq. Os numéricos comparam com value. Valores em dinheiro estão em centavos: 100000 é R$ 1.000,00. Um field que o evento não traz resulta em no.
Ligações. Ao sair de uma condição, cada ligação deve ter branch igual a yes ou no. Nos demais passos, branch é null.
Ações permitidas ao seller.
kind | params | Efeito |
|---|---|---|
notify_inbox | title (obrigatório), body, link, user_id | Cria uma notificação no painel. Sem user_id, vai para o usuário que criou o fluxo. |
set_order_status | status (obrigatório), notes | Muda o status do pedido do evento, passando pelas mesmas regras de transição de uma mudança manual. |
set_product_status | status | Muda o status do produto do evento. |
Gatilhos que realmente disparam
O catálogo lista oito gatilhos, mas para o seller funcionam seis:
| Gatilho | Dispara quando | Dados para condições |
|---|---|---|
order.created | Entra um pedido do seller. | order.total (centavos), order.item_count, order.payment_method, order.customer_id |
order.statusChanged | O status de um pedido do seller muda. | order.status, order.old_status (nome do status, como shipped) |
order.paymentStatusChanged | O pagamento muda de estado. | order.payment_status |
order.chargeback | Um pedido sofre estorno por disputa. | order.total, order.gateway |
product.pending_moderation | Um produto do seller vai para moderação. | product.vendor_id |
return.statusChanged | Uma devolução de pedido do seller muda de status. | return.status, return.order_id |
product.stockChanged e user.registered aparecem no catálogo, mas não executam para sellers: o primeiro não tem disparo ligado, o segundo não pertence a nenhum seller.
Execução e histórico
Cada evento cria uma execução (run) com os dados do evento em context. O mesmo evento não cria duas execuções do mesmo fluxo. Cada passo executado fica registrado em steps. Uma ação que falha por motivo temporário é tentada até 3 vezes no total; se continuar falhando, a execução termina como failed com o motivo em error.
status da execução | Significado |
|---|---|
active | Em andamento ou aguardando o próximo ciclo. |
done | Chegou a um exit. |
failed | Uma ação falhou. |
Endpoints
| Método | Caminho | Para que serve | Página |
|---|---|---|---|
| GET | /api/v1/vendor/flows | Lista os fluxos. | Fluxos |
| POST | /api/v1/vendor/flows | Cria um fluxo em rascunho. | Fluxos |
| GET | /api/v1/vendor/flows/{id} | Consulta um fluxo. | Fluxos |
| PUT | /api/v1/vendor/flows/{id} | Substitui o fluxo. | Fluxos |
| DELETE | /api/v1/vendor/flows/{id} | Apaga o fluxo. | Fluxos |
| POST | /api/v1/vendor/flows/{id}/activate | Valida e liga. | Ligar, pausar e testar |
| POST | /api/v1/vendor/flows/{id}/pause | Desliga. | Ligar, pausar e testar |
| POST | /api/v1/vendor/flows/{id}/test | Valida o grafo sem executar. | Ligar, pausar e testar |
| GET | /api/v1/vendor/flows/{id}/runs | Lista as execuções. | Execuções |
| GET | /api/v1/vendor/flows/runs/{runId}/steps | Passos de uma execução. | Execuções |
| GET | /api/v1/vendor/flows/catalog | Gatilhos e ações. | Catálogo |
Erros comuns
- Esperar que o fluxo dispare logo após criar. Ele nasce em
draft. É precisoactivate. - Achar que
testsimula um evento. Ele só valida a estrutura do grafo; nada é executado. - Usar uma ação de e-mail ou WhatsApp. O seller só pode
notify_inbox,set_order_statuseset_product_status. O restante volta422. - Escolher
user.registeredouproduct.stockChanged. Entram no catálogo mas nunca executam para o seller. - Escrever valor de dinheiro em reais na condição.
order.totalestá em centavos. - Mandar
PUTcomnameoutrigger_typevazios. Diferente doPOST, oPUTnão os exige e grava vazio. - Editar um fluxo ativo e supor que a validação roda de novo. O
PUTsó confere a lista de ações. Um grafo quebrado numa edição só aparece nas execuções, que falham. Pause, edite e ative de novo. - Esquecer o limite de 20 ativos.
activateresponde422quando o seller já tem 20.