VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Fluxos de automação

Fluxos

Lista, cria, consulta, substitui e apaga os fluxos de automação do seller.

O desenho dos fluxos, os gatilhos e as ações estão na home da seção. Aqui estão as rotas de cadastro.

Listar fluxos

Devolve todos os fluxos do seller que não foram apagados, do mais novo para o mais antigo, com os contadores dos últimos 7 dias.

GET/api/v1/vendor/flowsSeller

Listar fluxos

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Exemplo de requisição

bash
curl -X GET "$BASE_URL/api/v1/vendor/flows" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Fluxos
json
{
  "flows": [
    {
      "id": "52cb85db-b3fd-4683-b9db-efd8b6940c96",
      "name": "Avisar pedido grande",
      "status": "paused",
      "trigger_type": "order.created",
      "trigger_config": {},
      "graph": {
        "nodes": [
          {
            "id": "n_trigger",
            "type": "trigger",
            "config": {},
            "position": {
              "x": 240,
              "y": 40
            }
          },
          {
            "id": "n_cond",
            "type": "condition",
            "config": {
              "field": "order.total",
              "op": "gte",
              "value": 100000
            },
            "position": {
              "x": 240,
              "y": 180
            }
          },
          {
            "id": "n_action",
            "type": "action",
            "config": {
              "kind": "notify_inbox",
              "params": {
                "title": "Pedido grande",
                "body": "Chegou um pedido acima de R$ 1.000,00"
              }
            },
            "position": {
              "x": 120,
              "y": 320
            }
          },
          {
            "id": "n_exit",
            "type": "exit",
            "config": {},
            "position": {
              "x": 240,
              "y": 440
            }
          }
        ],
        "edges": [
          {
            "id": "e1",
            "from": "n_trigger",
            "to": "n_cond",
            "branch": null
          },
          {
            "id": "e2",
            "from": "n_cond",
            "to": "n_action",
            "branch": "yes"
          },
          {
            "id": "e3",
            "from": "n_cond",
            "to": "n_exit",
            "branch": "no"
          },
          {
            "id": "e4",
            "from": "n_action",
            "to": "n_exit",
            "branch": null
          }
        ]
      },
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "runs_7d": 3,
      "failed_7d": 0,
      "created_at": "2026-10-11T22:20:00Z",
      "updated_at": "2026-10-11T22:20:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

flowsobject[]

Os fluxos.

iduuid
Id do fluxo (UUID).
namestring
Nome.
statusstring
draftactivepaused
Estado do fluxo.
trigger_typestring
Evento que dispara o fluxo.
trigger_configobject
Configuração do gatilho. Hoje {}.
graphobject
O desenho do fluxo (veja a home da seção).
vendor_iduuid
Seller dono, sempre o do token.
runs_7dinteger
Execuções nos últimos 7 dias. Só na listagem; na consulta individual vem 0.
failed_7dinteger
Execuções que falharam nos últimos 7 dias. Só na listagem.
created_atstring
Criação, RFC 3339 em UTC.
updated_atstring
Última alteração, RFC 3339 em UTC.
totalinteger
Quantidade devolvida.

Erros

StatusQuandoCorpo de exemplo
401Token ausente, inválido, expirado ou revogado.invalid or expired token
403O token não é de um usuário seller, a loja está em análise de cadastro ou falta o privilégio de ajustes (vendor_settings ou equivalente).{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings","vendor_manage_delivery_areas","vendor_manage_whatsapp","vendor_manage_documents","vendor_manage_kyc","vendor_view_plan","vendor_manage_application","vendor_manage_vacation"]}

Criar fluxo

Cria um fluxo em rascunho. O servidor confere agora só a lista de ações permitidas; o resto do grafo é conferido em activate (e em test).

POST/api/v1/vendor/flowsSeller

Criar fluxo

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).
Content-Typestringobrigatório
application/json.

Corpo da requisição

namestringobrigatório
Nome do fluxo. Obrigatório ao criar.
trigger_typestringobrigatório
Evento que dispara o fluxo (veja Catálogo). Obrigatório ao criar. O valor não é conferido contra a lista: um valor desconhecido é aceito, mas o fluxo nunca dispara.
trigger_configobject
Configuração do gatilho. Omitido: {}.
graphobjectobrigatório

O desenho do fluxo.

graph.nodesobject[]obrigatório
Os passos. Cada um tem id, type (trigger, condition, action, exit), config e position (x, y, só para o editor visual).
graph.edgesobject[]obrigatório
As ligações. Cada uma tem id, from, to e branch (yes ou no ao sair de uma condição; null nos demais).

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/vendor/flows" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Avisar pedido grande", "trigger_type": "order.created", "graph": {"nodes": [{"id": "n_trigger", "type": "trigger", "config": {}, "position": {"x": 240, "y": 40}}, {"id": "n_cond", "type": "condition", "config": {"field": "order.total", "op": "gte", "value": 100000}, "position": {"x": 240, "y": 180}}, {"id": "n_action", "type": "action", "config": {"kind": "notify_inbox", "params": {"title": "Pedido grande", "body": "Chegou um pedido acima de R$ 1.000,00"}}, "position": {"x": 120, "y": 320}}, {"id": "n_exit", "type": "exit", "config": {}, "position": {"x": 240, "y": 440}}], "edges": [{"id": "e1", "from": "n_trigger", "to": "n_cond", "branch": null}, {"id": "e2", "from": "n_cond", "to": "n_action", "branch": "yes"}, {"id": "e3", "from": "n_cond", "to": "n_exit", "branch": "no"}, {"id": "e4", "from": "n_action", "to": "n_exit", "branch": null}]}}'

Resposta

201Fluxo criado
json
{
  "id": "52cb85db-b3fd-4683-b9db-efd8b6940c96",
  "name": "Avisar pedido grande",
  "status": "draft",
  "trigger_type": "order.created",
  "trigger_config": {},
  "graph": {
    "nodes": [
      {
        "id": "n_trigger",
        "type": "trigger",
        "config": {},
        "position": {
          "x": 240,
          "y": 40
        }
      },
      {
        "id": "n_cond",
        "type": "condition",
        "config": {
          "field": "order.total",
          "op": "gte",
          "value": 100000
        },
        "position": {
          "x": 240,
          "y": 180
        }
      },
      {
        "id": "n_action",
        "type": "action",
        "config": {
          "kind": "notify_inbox",
          "params": {
            "title": "Pedido grande",
            "body": "Chegou um pedido acima de R$ 1.000,00"
          }
        },
        "position": {
          "x": 120,
          "y": 320
        }
      },
      {
        "id": "n_exit",
        "type": "exit",
        "config": {},
        "position": {
          "x": 240,
          "y": 440
        }
      }
    ],
    "edges": [
      {
        "id": "e1",
        "from": "n_trigger",
        "to": "n_cond",
        "branch": null
      },
      {
        "id": "e2",
        "from": "n_cond",
        "to": "n_action",
        "branch": "yes"
      },
      {
        "id": "e3",
        "from": "n_cond",
        "to": "n_exit",
        "branch": "no"
      },
      {
        "id": "e4",
        "from": "n_action",
        "to": "n_exit",
        "branch": null
      }
    ]
  },
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "runs_7d": 0,
  "failed_7d": 0,
  "created_at": "2026-10-11T22:20:00Z",
  "updated_at": "2026-10-11T22:20:00Z"
}

Campos da resposta

(campos / fields)object
Os mesmos de Listar fluxos.

Erros

StatusQuandoCorpo de exemplo
400Corpo que não é JSON.{"error":"invalid body"}
422name ou trigger_type vazio.{"error":"failed","detail":"name and trigger_type required"}
422Ação fora da lista permitida ao seller. A estrutura do grafo só é conferida em testar e ativar.{"error":"invalid_graph","invalid_nodes":["n_action"],"reason":"action not allowed for vendor flows"}
401Token ausente, inválido, expirado ou revogado.invalid or expired token
403O token não é de um usuário seller, a loja está em análise de cadastro ou falta o privilégio de ajustes (vendor_settings ou equivalente).{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings","vendor_manage_delivery_areas","vendor_manage_whatsapp","vendor_manage_documents","vendor_manage_kyc","vendor_view_plan","vendor_manage_application","vendor_manage_vacation"]}

Consultar fluxo

GET/api/v1/vendor/flows/{id}Seller

Consultar fluxo

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

iduuidobrigatório
Id do fluxo (UUID).

Exemplo de requisição

bash
curl -X GET "$BASE_URL/api/v1/vendor/flows/52cb85db-b3fd-4683-b9db-efd8b6940c96" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Fluxo
json
{
  "id": "52cb85db-b3fd-4683-b9db-efd8b6940c96",
  "name": "Avisar pedido grande",
  "status": "draft",
  "trigger_type": "order.created",
  "trigger_config": {},
  "graph": {
    "nodes": [
      {
        "id": "n_trigger",
        "type": "trigger",
        "config": {},
        "position": {
          "x": 240,
          "y": 40
        }
      },
      {
        "id": "n_cond",
        "type": "condition",
        "config": {
          "field": "order.total",
          "op": "gte",
          "value": 100000
        },
        "position": {
          "x": 240,
          "y": 180
        }
      },
      {
        "id": "n_action",
        "type": "action",
        "config": {
          "kind": "notify_inbox",
          "params": {
            "title": "Pedido grande",
            "body": "Chegou um pedido acima de R$ 1.000,00"
          }
        },
        "position": {
          "x": 120,
          "y": 320
        }
      },
      {
        "id": "n_exit",
        "type": "exit",
        "config": {},
        "position": {
          "x": 240,
          "y": 440
        }
      }
    ],
    "edges": [
      {
        "id": "e1",
        "from": "n_trigger",
        "to": "n_cond",
        "branch": null
      },
      {
        "id": "e2",
        "from": "n_cond",
        "to": "n_action",
        "branch": "yes"
      },
      {
        "id": "e3",
        "from": "n_cond",
        "to": "n_exit",
        "branch": "no"
      },
      {
        "id": "e4",
        "from": "n_action",
        "to": "n_exit",
        "branch": null
      }
    ]
  },
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "runs_7d": 0,
  "failed_7d": 0,
  "created_at": "2026-10-11T22:20:00Z",
  "updated_at": "2026-10-11T22:20:00Z"
}

Erros

StatusQuandoCorpo de exemplo
404O fluxo não existe ou é de outro seller. Os dois casos dão 404.{"error":"not found"}
401Token ausente, inválido, expirado ou revogado.invalid or expired token
403O token não é de um usuário seller, a loja está em análise de cadastro ou falta o privilégio de ajustes (vendor_settings ou equivalente).{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings","vendor_manage_delivery_areas","vendor_manage_whatsapp","vendor_manage_documents","vendor_manage_kyc","vendor_view_plan","vendor_manage_application","vendor_manage_vacation"]}
Contadores zerados aqui

runs_7d e failed_7d só são calculados na listagem. Na consulta individual vêm 0; use Execuções se precisar do número.

Substituir fluxo

Substitui nome, gatilho, configuração e grafo. Não muda o status: um fluxo ativo continua ativo com o novo grafo.

PUT/api/v1/vendor/flows/{id}Seller

Substituir fluxo

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).
Content-Typestringobrigatório
application/json.

Parâmetros de caminho

iduuidobrigatório
Id do fluxo (UUID).

Corpo da requisição

namestring
Nome do fluxo. Não é validado ao substituir: se omitir, o nome gravado fica vazio, então sempre envie.
trigger_typestring
Evento que dispara o fluxo (veja Catálogo). Não é validado ao substituir: sempre envie. O valor não é conferido contra a lista: um valor desconhecido é aceito, mas o fluxo nunca dispara.
trigger_configobject
Configuração do gatilho. Omitido: {}.
graphobjectobrigatório

O desenho do fluxo.

graph.nodesobject[]obrigatório
Os passos. Cada um tem id, type (trigger, condition, action, exit), config e position (x, y, só para o editor visual).
graph.edgesobject[]obrigatório
As ligações. Cada uma tem id, from, to e branch (yes ou no ao sair de uma condição; null nos demais).

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/vendor/flows/52cb85db-b3fd-4683-b9db-efd8b6940c96" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Avisar pedido muito grande", "trigger_type": "order.created", "graph": {"nodes": [{"id": "n_trigger", "type": "trigger", "config": {}, "position": {"x": 240, "y": 40}}, {"id": "n_cond", "type": "condition", "config": {"field": "order.total", "op": "gte", "value": 100000}, "position": {"x": 240, "y": 180}}, {"id": "n_action", "type": "action", "config": {"kind": "notify_inbox", "params": {"title": "Pedido grande", "body": "Chegou um pedido acima de R$ 1.000,00"}}, "position": {"x": 120, "y": 320}}, {"id": "n_exit", "type": "exit", "config": {}, "position": {"x": 240, "y": 440}}], "edges": [{"id": "e1", "from": "n_trigger", "to": "n_cond", "branch": null}, {"id": "e2", "from": "n_cond", "to": "n_action", "branch": "yes"}, {"id": "e3", "from": "n_cond", "to": "n_exit", "branch": "no"}, {"id": "e4", "from": "n_action", "to": "n_exit", "branch": null}]}}'

Resposta

200Fluxo atualizado
json
{
  "id": "52cb85db-b3fd-4683-b9db-efd8b6940c96",
  "name": "Avisar pedido muito grande",
  "status": "draft",
  "trigger_type": "order.created",
  "trigger_config": {},
  "graph": {
    "nodes": [
      {
        "id": "n_trigger",
        "type": "trigger",
        "config": {},
        "position": {
          "x": 240,
          "y": 40
        }
      },
      {
        "id": "n_cond",
        "type": "condition",
        "config": {
          "field": "order.total",
          "op": "gte",
          "value": 100000
        },
        "position": {
          "x": 240,
          "y": 180
        }
      },
      {
        "id": "n_action",
        "type": "action",
        "config": {
          "kind": "notify_inbox",
          "params": {
            "title": "Pedido grande",
            "body": "Chegou um pedido acima de R$ 1.000,00"
          }
        },
        "position": {
          "x": 120,
          "y": 320
        }
      },
      {
        "id": "n_exit",
        "type": "exit",
        "config": {},
        "position": {
          "x": 240,
          "y": 440
        }
      }
    ],
    "edges": [
      {
        "id": "e1",
        "from": "n_trigger",
        "to": "n_cond",
        "branch": null
      },
      {
        "id": "e2",
        "from": "n_cond",
        "to": "n_action",
        "branch": "yes"
      },
      {
        "id": "e3",
        "from": "n_cond",
        "to": "n_exit",
        "branch": "no"
      },
      {
        "id": "e4",
        "from": "n_action",
        "to": "n_exit",
        "branch": null
      }
    ]
  },
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "runs_7d": 0,
  "failed_7d": 0,
  "created_at": "2026-10-11T22:20:00Z",
  "updated_at": "2026-10-11T22:20:00Z"
}

Erros

StatusQuandoCorpo de exemplo
404O fluxo não existe ou é de outro seller. Os dois casos dão 404.{"error":"not found"}
400Corpo que não é JSON.{"error":"invalid body"}
422Ação fora da lista permitida ao seller. A estrutura do grafo só é conferida em testar e ativar.{"error":"invalid_graph","invalid_nodes":["n_action"],"reason":"action not allowed for vendor flows"}
401Token ausente, inválido, expirado ou revogado.invalid or expired token
403O token não é de um usuário seller, a loja está em análise de cadastro ou falta o privilégio de ajustes (vendor_settings ou equivalente).{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings","vendor_manage_delivery_areas","vendor_manage_whatsapp","vendor_manage_documents","vendor_manage_kyc","vendor_view_plan","vendor_manage_application","vendor_manage_vacation"]}
Edição de fluxo ativo

Só a lista de ações é conferida no PUT. Se o grafo ficar inválido (por exemplo, sem exit), as próximas execuções falham. Para editar com segurança: pause, edite, rode o test e ative.

Apagar fluxo

Apaga o fluxo (ele some da listagem e fica pausado). O histórico de execuções deixa de ser alcançável pelas rotas do seller.

DELETE/api/v1/vendor/flows/{id}Seller

Apagar fluxo

Cabeçalhos

Authorizationstringobrigatório
Bearer $TOKEN. Token de acesso do usuário seller (veja Tokens).

Parâmetros de caminho

iduuidobrigatório
Id do fluxo (UUID).

Exemplo de requisição

bash
curl -X DELETE "$BASE_URL/api/v1/vendor/flows/52cb85db-b3fd-4683-b9db-efd8b6940c96" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Apagado
json
{
  "status": "deleted"
}

Erros

StatusQuandoCorpo de exemplo
404O fluxo não existe ou é de outro seller. Os dois casos dão 404.{"error":"not found"}
500Falha ao apagar.{"error":"failed"}
401Token ausente, inválido, expirado ou revogado.invalid or expired token
403O token não é de um usuário seller, a loja está em análise de cadastro ou falta o privilégio de ajustes (vendor_settings ou equivalente).{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings","vendor_view_settings","vendor_manage_delivery_areas","vendor_manage_whatsapp","vendor_manage_documents","vendor_manage_kyc","vendor_view_plan","vendor_manage_application","vendor_manage_vacation"]}
Sem desfazer

Não existe rota para recuperar um fluxo apagado. Para só parar de executar, use pause.

Veja também

  • Ligar, pausar e testar
  • Execuções
  • Catálogo
Anterior
Fluxos de automação
Próxima
Ligar, pausar e testar
Nesta página
  • Listar fluxos
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar fluxo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Consultar fluxo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Substituir fluxo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Apagar fluxo
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também