Guia de Design de Workflows

Projete workflows no Flowker com clareza e controle. Este guia apresenta os tipos de nós, arestas, padrões do mundo real, transições de status, limites técnicos e boas práticas para ajudar você a construir orquestrações confiáveis e fáceis de manter.

Tipos de nós

Todo workflow é construído a partir de nós. Cada nó possui um type que define como o Flowker o processa em tempo de execução.

trigger

O ponto de entrada de um workflow. Todo workflow deve começar com um nó trigger. Quando a execução começa, o motor entra por esse nó e inicia o roteamento a partir dele.

{
  "id": "node-trigger",
  "type": "trigger",
  "name": "Payment Received"
}

executor

Chama um executor externo, um serviço HTTP, API ou provedor registrado no Flowker. Este é o bloco fundamental para integração com motores de fraude, provedores de pagamento, serviços de notificação e outros sistemas externos.

{
  "id": "node-fraud-check",
  "type": "executor",
  "name": "Check Fraud Score"
}

conditional

Avalia uma expressão contra o contexto de execução e roteia para diferentes ramificações com base no resultado. Use nós condicionais para implementar lógica de ramificação, por exemplo, roteando para um caminho de aprovação quando o risco é alto, ou continuando diretamente quando é baixo.

{
  "id": "node-risk-decision",
  "type": "conditional",
  "name": "Evaluate Risk Score"
}

action

Representa operações internas do workflow que não envolvem chamadas externas, como transformar dados, emitir eventos ou registrar mudanças de estado.

{
  "id": "node-record-approval",
  "type": "action",
  "name": "Record Approval Decision"
}

Arestas

Arestas conectam nós e definem caminhos de execução. Cada aresta inclui os seguintes campos:

Campo	Descrição
`id`	Identificador único da aresta.
`source`	ID do nó de origem.
`target`	ID do nó de destino.
`sourceHandle`	Porta de saída do nó de origem de onde a aresta se origina.
`condition`	Expressão que deve ser avaliada como verdadeira para que a aresta seja seguida.
`label`	Rótulo legível usado para visualização e depuração.

Exemplo de aresta

{
  "id": "edge-approved",
  "source": "node-risk-decision",
  "target": "node-process-payment",
  "sourceHandle": "approved",
  "condition": "node-risk-decision.riskScore < 70",
  "label": "Approved"
}

O campo condition é avaliado contra o contexto de execução. Se omitido, a aresta é sempre seguida quando o nó de origem é concluído com sucesso.

Transições de status

Workflows seguem um ciclo de vida bem definido. Compreender essas transições é essencial para implantar e evoluir workflows com segurança.

Diagrama de transição de status de workflow mostrando três estados: draft, active e inactive. Uma seta rotulada 'activate' aponta de draft para active. Uma seta rotulada 'deactivate' aponta de active para inactive. Uma seta rotulada 'draft' aponta de inactive de volta para draft.

draft — O estado inicial. Todas as modificações (adicionar nós, editar arestas, alterar configurações) são permitidas apenas no status draft.
active — Um workflow que foi ativado. Pode ser executado. Nenhuma modificação é permitida enquanto estiver ativo.
inactive — Um workflow que foi desativado. Não pode mais ser executado, mas pode ser movido de volta para draft para edição.

Regras

Apenas um workflow em draft pode ser ativado (transição: draft → active).
Apenas um workflow active pode ser desativado (transição: active → inactive).
Apenas um workflow inactive pode ser movido de volta para draft (transição: inactive → draft).
Tentar uma transição inválida retorna o erro FLK-0102.
Tentar modificar um workflow que não está em draft retorna o erro FLK-0103.

Movendo um workflow inativo de volta para draft

Se você desativou um workflow e quer editá-lo novamente, mova-o de volta para draft chamando POST /v1/workflows/{id}/draft. Isso torna o workflow editável sem precisar cloná-lo. Isso é útil quando você desativou um workflow por engano ou quando quer iterar sobre um workflow existente em vez de criar uma cópia.

Apenas workflows inativos podem ser movidos para draft. Se você precisar modificar um workflow ativo sem tirá-lo do ar, use a abordagem de clone descrita abaixo.

Iterando com segurança usando clone

Para modificar um workflow ativo, clone-o primeiro. A clonagem cria um novo draft a partir de qualquer status, copiando todos os nós e arestas. Você pode então atualizar, testar e ativá-lo sem impactar a versão atual. Esta é a abordagem recomendada para versionamento em produção.

Limites técnicos

Limite	Valor	Código de erro
Máximo de nós por workflow	100	`FLK-0113`
Máximo de arestas por workflow	200	`FLK-0114`
Payload máximo de entrada para execução	1 MB	`FLK-0506`

Tenha esses limites em mente ao projetar fluxos complexos. Workflows com mais de ~50 nós geralmente indicam que o fluxo deve ser dividido em workflows menores e compostos.

Padrões comuns

Sequencial

O padrão mais simples. Os nós são executados em uma sequência linear. Use quando cada etapa depende da anterior e nenhuma ramificação é necessária.

Exemplo: Orquestração de pagamento

{
  "nodes": [
    { "id": "n1", "type": "trigger",  "name": "Payment Initiated" },
    { "id": "n2", "type": "executor", "name": "Validate Payment Data" },
    { "id": "n3", "type": "executor", "name": "Route to Provider" },
    { "id": "n4", "type": "executor", "name": "Send Confirmation Notification" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Valid" },
    { "id": "e3", "source": "n3", "target": "n4", "label": "Routed" }
  ]
}

Ramificação condicional

Um nó conditional avalia uma expressão e roteia a execução de acordo. Cada aresta de saída carrega sua própria condition.

Exemplo: Verificação antifraude

{
  "nodes": [
    { "id": "n1", "type": "trigger",     "name": "Transaction Received" },
    { "id": "n2", "type": "executor",    "name": "Get Fraud Score" },
    { "id": "n3", "type": "conditional", "name": "Evaluate Score" },
    { "id": "n4", "type": "executor",    "name": "Approve Transaction" },
    { "id": "n5", "type": "executor",    "name": "Reject Transaction" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Score received" },
    {
      "id": "e3",
      "source": "n3",
      "target": "n4",
      "sourceHandle": "approved",
      "condition": "n2.fraudScore < 70",
      "label": "Approved"
    },
    {
      "id": "e4",
      "source": "n3",
      "target": "n5",
      "sourceHandle": "rejected",
      "condition": "n2.fraudScore >= 70",
      "label": "Rejected"
    }
  ]
}

Exemplos do mundo real

Verificação antifraude

Uma transação chega, uma pontuação de fraude é obtida, e a execução é roteada para aprovação ou rejeição.

{
  "nodes": [
    { "id": "n1", "type": "trigger",     "name": "Transaction Received" },
    { "id": "n2", "type": "executor",    "name": "Get Fraud Score" },
    { "id": "n3", "type": "conditional", "name": "Evaluate Fraud Score" },
    { "id": "n4", "type": "executor",    "name": "Approve Transaction" },
    { "id": "n5", "type": "executor",    "name": "Reject and Notify" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Score received" },
    {
      "id": "e3",
      "source": "n3",
      "target": "n4",
      "sourceHandle": "approved",
      "condition": "n2.fraudScore < 70",
      "label": "Low risk"
    },
    {
      "id": "e4",
      "source": "n3",
      "target": "n5",
      "sourceHandle": "rejected",
      "condition": "n2.fraudScore >= 70",
      "label": "High risk"
    }
  ]
}

Orquestração de pagamento

Um fluxo linear que valida os dados de pagamento recebidos, roteia para o provedor apropriado e envia uma confirmação.

{
  "nodes": [
    { "id": "n1", "type": "trigger",  "name": "Payment Initiated" },
    { "id": "n2", "type": "executor", "name": "Validate Payment Data" },
    { "id": "n3", "type": "executor", "name": "Route to Payment Provider" },
    { "id": "n4", "type": "executor", "name": "Send Confirmation" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Valid" },
    { "id": "e3", "source": "n3", "target": "n4", "label": "Payment routed" }
  ]
}

Onboarding KYC

Os documentos de um cliente são verificados por um serviço externo. Um nó condicional avalia se uma revisão manual é necessária. Se sim, uma ação de aprovação manual é acionada antes de ativar a conta.

{
  "nodes": [
    { "id": "n1", "type": "trigger",     "name": "Onboarding Started" },
    { "id": "n2", "type": "executor",    "name": "Run Document Check" },
    { "id": "n3", "type": "conditional", "name": "Manual Review Required?" },
    { "id": "n4", "type": "action",      "name": "Request Manual Approval" },
    { "id": "n5", "type": "executor",    "name": "Activate Account" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Check complete" },
    {
      "id": "e3",
      "source": "n3",
      "target": "n4",
      "sourceHandle": "review",
      "condition": "n2.reviewRequired == true",
      "label": "Needs review"
    },
    {
      "id": "e4",
      "source": "n3",
      "target": "n5",
      "sourceHandle": "clear",
      "condition": "n2.reviewRequired == false",
      "label": "Auto-approved"
    },
    { "id": "e5", "source": "n4", "target": "n5", "label": "Approved" }
  ]
}

Fluxo de aprovação manual

Uma solicitação é enviada para revisão. Uma ação de aprovação aguarda uma decisão. Um nó condicional então roteia para o caminho de aprovação ou rejeição.

{
  "nodes": [
    { "id": "n1", "type": "trigger",     "name": "Request Submitted" },
    { "id": "n2", "type": "executor",    "name": "Submit for Review" },
    { "id": "n3", "type": "action",      "name": "Await Approval Decision" },
    { "id": "n4", "type": "conditional", "name": "Decision Received" },
    { "id": "n5", "type": "executor",    "name": "Process Approved Request" },
    { "id": "n6", "type": "executor",    "name": "Notify Rejection" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Submitted" },
    { "id": "e3", "source": "n3", "target": "n4", "label": "Decision received" },
    {
      "id": "e4",
      "source": "n4",
      "target": "n5",
      "sourceHandle": "approved",
      "condition": "n3.decision == 'approved'",
      "label": "Approved"
    },
    {
      "id": "e5",
      "source": "n4",
      "target": "n6",
      "sourceHandle": "rejected",
      "condition": "n3.decision == 'rejected'",
      "label": "Rejected"
    }
  ]
}

Boas práticas

Convenções de nomenclatura de nós

Use nomes descritivos e orientados a ações que comuniquem o que o nó faz, e não qual é o seu tipo.

correto: Validate Payment Data, Get Fraud Score, Notify Customer, Await Approval
errado: executor1, conditional node, node3

Bons nomes tornam os workflows legíveis sem precisar abrir a configuração do nó. Eles também aparecem em logs de auditoria e rastreamentos de execução, tornando a depuração significativamente mais rápida.

Expressões de condição em arestas

As condições nas arestas são avaliadas contra o contexto de execução. Mantenha-as simples e explícitas:

Use comparações diretas de campos: <nodeId>.status == 'approved'
Use comparações numéricas: <nodeId>.riskScore < 70
Use campos booleanos: <nodeId>.reviewRequired == true

Evite expressões complexas que são difíceis de ler ou depurar. Se a lógica não for trivial, considere rotear através de um nó conditional que encapsula a decisão com um nome claro. Uma expressão inválida retorna FLK-0105. Sempre valide as expressões antes de ativar um workflow.

Estratégias de tratamento de erros

Projete workflows para lidar com falhas de forma explícita:

Adicione caminhos de rejeição a partir de nós conditional para cada ponto de decisão que pode falhar.
Use nós executor separados para lógica de retry ou provedores de fallback.
Nomeie os caminhos de erro de forma clara (por exemplo, Reject and Notify, Fallback to Manual Review) para que os logs de auditoria sejam autoexplicativos.

Evitando ciclos

O Flowker usa um mecanismo de detecção de ciclos baseado em DFS em tempo de execução. Se um ciclo for detectado durante a execução, o workflow falha com FLK-0508. Ciclos não são detectados em tempo de design, portanto valide a estrutura das suas arestas antes de ativar. Regras para prevenir ciclos:

As arestas devem sempre apontar para frente no fluxo, nunca de volta para um nó executado anteriormente.
Revise o grafo visualmente antes de ativar qualquer workflow com ramificações ou caminhos de junção.
Se um retry ou loop for necessário, modele-o como uma invocação de workflow separada, não como uma aresta de retorno no grafo atual.

Versionamento via clone

Nunca edite um workflow ativo diretamente. Em vez disso:

Clone o workflow (cria um novo draft com todos os nós e arestas copiados).

Faça suas alterações no rascunho.

Teste o rascunho com execuções.

Ative a nova versão.

Desative a versão antiga se ela não for mais necessária.

Isso preserva o histórico de execução da versão ativa e oferece um caminho de rollback caso a nova versão apresente problemas.

Criando workflows a partir de templates

Em vez de construir um workflow do zero, você pode criá-lo a partir de um template pré-construído no catálogo. Templates fornecem estruturas prontas de nós e arestas para padrões comuns — validação de pagamentos, verificações de fraude, fluxos de onboarding e mais. Chame POST /v1/workflows/from-template com o ID do template, um nome para o novo workflow e quaisquer parâmetros que o template requer. O resultado é um novo workflow com status draft que você pode revisar, personalizar e ativar.

Exemplo de requisição

POST /v1/workflows/from-template

{
  "templateId": "payment-validation",
  "params": {
    "providerConfigId": "a1b2c3d4-e5f6-4789-a012-345678901234",
    "currency": "USD"
  },
  "name": "Payment Validation - USD",
  "description": "Valida pagamentos USD antes da escrituração no ledger"
}

Para descobrir templates disponíveis e seus parâmetros obrigatórios, use os endpoints Listar templates do catálogo e Consultar template do catálogo. O endpoint de detalhe do template retorna um JSON Schema descrevendo os parâmetros esperados, incluindo opções dinâmicas para campos que referenciam configurações de provider.

Referência de erros

Os seguintes códigos de erro são relevantes para o design e a execução de workflows:

Código	Descrição
`FLK-0102`	Transição de status inválida
`FLK-0103`	Workflow não pode ser modificado — não está no status draft
`FLK-0105`	Expressão condicional inválida
`FLK-0113`	Nós em excesso — o máximo é 100
`FLK-0114`	Arestas em excesso — o máximo é 200
`FLK-0506`	Payload de entrada da execução muito grande — o máximo é 1 MB
`FLK-0508`	Ciclo detectado durante a execução do workflow

Documentation Index

​Tipos de nós

​trigger

​executor

​conditional

​action

​Arestas

​Exemplo de aresta

​Transições de status

​Regras

​Movendo um workflow inativo de volta para draft

​Iterando com segurança usando clone

​Limites técnicos

​Padrões comuns

​Sequencial

​Ramificação condicional

​Exemplos do mundo real

​Verificação antifraude

​Orquestração de pagamento

​Onboarding KYC

​Fluxo de aprovação manual

​Boas práticas

​Convenções de nomenclatura de nós

​Expressões de condição em arestas

​Estratégias de tratamento de erros

​Evitando ciclos

​Versionamento via clone

​Criando workflows a partir de templates

​Referência de erros

Tipos de nós

trigger

executor

conditional

action

Arestas

Exemplo de aresta

Transições de status

Regras

Movendo um workflow inativo de volta para draft

Iterando com segurança usando clone

Limites técnicos

Padrões comuns

Sequencial

Ramificação condicional

Exemplos do mundo real

Verificação antifraude

Orquestração de pagamento

Onboarding KYC

Fluxo de aprovação manual

Boas práticas

Convenções de nomenclatura de nós

Expressões de condição em arestas

Estratégias de tratamento de erros

Evitando ciclos

Versionamento via clone

Criando workflows a partir de templates

Referência de erros