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

Fluxos: criar, alterar, apagar

Cria um fluxo em rascunho, substitui o desenho de um fluxo e apaga um fluxo.

Estas rotas exigem manage_ops_flows. Um fluxo novo nasce em rascunho e não executa nada até ser ativado (Ativar, pausar e testar). Criar e alterar não validam o desenho: um desenho incompleto é aceito e só é recusado ao ativar.

Criar

POST/api/v1/admin/ops-flowsAdmin

Criar um fluxo

Corpo da requisição

namestringobrigatório
Nome do fluxo. Obrigatório.
trigger_typestringobrigatório
order.createdorder.statusChangedorder.paymentStatusChangedorder.chargebackproduct.stockChangedproduct.pending_moderationreturn.statusChangeduser.registered
O evento que dispara o fluxo.
trigger_configobjectpadrão: {}
Configuração do gatilho. Hoje não é lida: use {}.
graphobject

O desenho do fluxo.

nodesarray

Etapas.

idstringobrigatório
Identificador da etapa, único no fluxo.
typestringobrigatório
triggerconditionactionexit
Tipo da etapa.
configobject
Configuração. trigger: {}. condition: field, op, value/str. action: kind e params. exit: {}.
positionobject
Posição no editor visual: x e y. Só serve para desenhar.
edgesarray

Ligações entre etapas.

idstringobrigatório
Identificador da ligação.
fromstringobrigatório
Id da etapa de origem.
tostringobrigatório
Id da etapa de destino.
branchstring|null
yes ou no quando a origem é uma condição; null nas demais.

Exemplo de requisição (criar)

bash
curl -X POST "$BASE_URL/api/v1/admin/ops-flows" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Avisar pedido grande", "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": "Pedido acima de R$ 1.000"}}, "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 (criar)

201Fluxo criado em rascunho
json
{
  "id": "7f89112b-4bef-46fb-ac55-4e66baf978c4",
  "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": "Pedido acima de R$ 1.000" } }, "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 }
    ]
  },
  "runs_7d": 0,
  "failed_7d": 0,
  "created_at": "2026-10-11T21:19:34.256049Z",
  "updated_at": "2026-10-11T21:19:34.256049Z"
}

Campos da resposta

iduuid
Id do fluxo.
namestring
Nome.
statusstring
draftactivepaused
draft rascunho, active ligado, paused pausado.
trigger_typestring
Gatilho.
trigger_configobject
Configuração do gatilho.
graphobject
O desenho (nodes e edges).
vendor_iduuid
Só em fluxos criados por um seller (lojista). Ausente nos fluxos da loja.
runs_7dinteger
Execuções nos últimos 7 dias. Só vem calculado na listagem; na consulta e nas escritas é 0.
failed_7dinteger
Execuções com falha nos últimos 7 dias. Mesma regra.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.

Erros (criar)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem manage_ops_flows.{"error":"insufficient privileges","privilege_required_any":["manage_ops_flows"]}
400Corpo que não é JSON válido.{"error":"invalid body","detail":"unexpected EOF"}
422Falta name ou trigger_type, ou falha ao gravar.{"error":"failed","detail":"name and trigger_type required"}

Alterar

PUT/api/v1/admin/ops-flows/{id}Admin

Substituir a definição de um fluxo

Parâmetros de caminho

iduuidobrigatório
Id do fluxo (UUID).

Corpo da requisição

namestringobrigatório
Nome do fluxo. Obrigatório.
trigger_typestringobrigatório
order.createdorder.statusChangedorder.paymentStatusChangedorder.chargebackproduct.stockChangedproduct.pending_moderationreturn.statusChangeduser.registered
O evento que dispara o fluxo.
trigger_configobjectpadrão: {}
Configuração do gatilho. Hoje não é lida: use {}.
graphobject

O desenho do fluxo.

nodesarray

Etapas.

idstringobrigatório
Identificador da etapa, único no fluxo.
typestringobrigatório
triggerconditionactionexit
Tipo da etapa.
configobject
Configuração. trigger: {}. condition: field, op, value/str. action: kind e params. exit: {}.
positionobject
Posição no editor visual: x e y. Só serve para desenhar.
edgesarray

Ligações entre etapas.

idstringobrigatório
Identificador da ligação.
fromstringobrigatório
Id da etapa de origem.
tostringobrigatório
Id da etapa de destino.
branchstring|null
yes ou no quando a origem é uma condição; null nas demais.

Exemplo de requisição (alterar)

bash
curl -X PUT "$BASE_URL/api/v1/admin/ops-flows/7f89112b-4bef-46fb-ac55-4e66baf978c4" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Avisar pedido grande (v2)", "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": "Pedido acima de R$ 1.000"}}, "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 (alterar)

200Fluxo alterado
json
{
  "id": "7f89112b-4bef-46fb-ac55-4e66baf978c4",
  "name": "Avisar pedido grande (v2)",
  "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": "Pedido acima de R$ 1.000" } }, "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 }
    ]
  },
  "runs_7d": 0,
  "failed_7d": 0,
  "created_at": "2026-10-11T21:19:34.256049Z",
  "updated_at": "2026-10-11T21:19:34.256049Z"
}

Campos da resposta

(objeto)object
O fluxo depois da alteração. O PUT substitui nome, gatilho e desenho inteiros: reenvie tudo. O status não muda.

Erros (alterar)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem manage_ops_flows.{"error":"insufficient privileges","privilege_required_any":["manage_ops_flows"]}
400Corpo que não é JSON válido.{"error":"invalid body","detail":"unexpected EOF"}
422Falha ao gravar.{"error":"failed","detail":"..."}

Apagar

DELETE/api/v1/admin/ops-flows/{id}Admin

Apagar um fluxo

Parâmetros de caminho

iduuidobrigatório
Id do fluxo (UUID).

Exemplo de requisição (apagar)

bash
curl -X DELETE "$BASE_URL/api/v1/admin/ops-flows/7f89112b-4bef-46fb-ac55-4e66baf978c4" \
  -H "Authorization: Bearer $TOKEN"

Resposta (apagar)

200Fluxo apagado
json
{
  "status": "deleted"
}

Campos da resposta

statusstring
Sempre deleted.

Erros (apagar)

StatusQuandoCorpo
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O usuário não tem manage_ops_flows.{"error":"insufficient privileges","privilege_required_any":["manage_ops_flows"]}
500Falha ao consultar ou gravar.{"error":"failed","detail":"..."}
PUT em fluxo ativo vale na hora

Nada impede de alterar um fluxo active: o novo desenho passa a valer nos próximos eventos, sem passar de novo pela validação de ativação. Prefira pausar, alterar, testar e reativar.

Apagar é lógico e idempotente

O fluxo é marcado como apagado e pausado; a resposta é 200 mesmo se o id não existir ou já tiver sido apagado.

Veja também

  • Listar e consultar
  • Ativar, pausar e testar
  • Visão geral
Anterior
Fluxos: listar e consultar
Próxima
Fluxos: ativar, pausar, testar
Nesta página
  • Criar
  • Exemplo de requisição (criar)
  • Resposta (criar)
  • Erros (criar)
  • Alterar
  • Exemplo de requisição (alterar)
  • Resposta (alterar)
  • Erros (alterar)
  • Apagar
  • Exemplo de requisição (apagar)
  • Resposta (apagar)
  • Erros (apagar)
  • Veja também