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)

Resposta (criar)

201Fluxo criado em rascunho

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)

Resposta (alterar)

200Fluxo alterado

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)

Resposta (apagar)

200Fluxo apagado

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
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}]}}'
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}]}}'
bash
curl -X DELETE "$BASE_URL/api/v1/admin/ops-flows/7f89112b-4bef-46fb-ac55-4e66baf978c4" \
  -H "Authorization: Bearer $TOKEN"
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"
}
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"
}
json
{
  "status": "deleted"
}