Pular para o conteúdo principal
O Flowker se conecta a serviços externos (como motores anti-fraude, processadores de pagamento, provedores KYC e mais) através de configurações de executor. Neste guia, você vai explorar o catálogo, criar e configurar um executor, testar conectividade, usá-lo em um workflow e entender o modelo de resiliência do Flowker.

​
Ciclo de vida da configuração de executor

Antes de um executor poder ser usado em um workflow, ele passa pelo seguinte ciclo de vida:
Ciclo de vida da configuração de executor
As configurações de executor são gerenciadas através dos endpoints /v1/executors (listar, obter, atualizar, remover). Os estados do ciclo de vida (unconfigured, configured, tested, active, disabled) são rastreados internamente — as transições acontecem por meio da camada de serviço.
StatusO que significaPróximo passo
unconfiguredCriado com detalhes de conexão mas não completamente configurado.Configurá-lo (PATCH)
configuredDetalhes de conexão definidos e validados.Testar conectividade
testedTeste de conectividade bem-sucedido.Ativá-lo
activeDisponível para execução de workflows.—
disabledTemporariamente fora de serviço.Habilitá-lo
O ciclo de vida da configuração de executor é gerenciado pela camada de serviço (comandos MarkConfigured, MarkTested, Activate, Disable, Enable). Observe que a API HTTP atual expõe os endpoints GET, PATCH e DELETE. O PATCH atualiza os dados de configuração, mas não dispara transições de status.
Antes de criar uma configuração de executor, explore o catálogo para ver o que está disponível. O catálogo é um registro somente leitura de executors e triggers integrados que vêm com o Flowker. Você não precisa criar entradas no catálogo — você as descobre e configura as que precisa.
1

Listar executors disponíveis

Chame o endpoint Listar executors do catálogo para ver todos os tipos de executor que o Flowker suporta — requisições HTTP, transformações de dados e mais.
2

Listar triggers disponíveis

Chame o endpoint Listar triggers do catálogo para ver como os workflows podem ser iniciados — webhooks ou chamadas API manuais.
3

Escolha o que você precisa

Identifique o tipo de executor e trigger que correspondem à sua integração. Você vai referenciá-los ao criar sua configuração no próximo passo.
Pense no catálogo como um menu: ele mostra a que o Flowker pode se conectar. As configurações de executor são seus pedidos específicos — as credenciais, URLs e configurações para cada serviço que você quer usar.

​
Passo 2: Configurar uma conexão de provider e executor

Os executors são componentes integrados que vêm com o Flowker. Você não os cria via API — eles são descobertos pelo catálogo (GET /v1/catalog/executors) no Passo 1. Para usar um executor, primeiro crie uma configuração de provider que define a conexão com o serviço externo e, em seguida, gerencie as configurações de executor que associam um executor do catálogo a uma conexão de provider com configurações específicas da operação.

​
Criar uma configuração de provider

Chame POST /v1/provider-configurations para configurar a conexão com seu serviço externo — incluindo a URL base, credenciais e configurações específicas do ambiente. O campo config é validado contra o JSON Schema do provider no catálogo. Consulte Configurações de provider abaixo para detalhes e exemplos.

​
Gerenciar configurações de executor

Uma vez que você tenha uma configuração de provider, gerencie as configurações de executor pelos endpoints /v1/executors:
OperaçãoEndpoint
ListarGET /v1/executors
ConsultarGET /v1/executors/{id}
AtualizarPATCH /v1/executors/{id}
RemoverDELETE /v1/executors/{id}
Uma configuração de executor define qual endpoint chamar e como mapear os dados para essa operação. Ela referencia uma configuração de provider para os detalhes reais da conexão. Consulte a API de Configurações de executor para a referência completa da API.

​
Tipos de autenticação

O Flowker suporta múltiplos métodos de autenticação. Use o método exigido pelo seu serviço externo.
TipoDescriçãoCampos de configuração
noneSem autenticação.—
api_keyAPI key no header ou query.key, value, location
bearerBearer token no header Authorization.token
basicUsuário e senha (Base64).username, password
oidc_client_credentialsFluxo OAuth 2.0 client credentials com gestão automática de tokens.tokenURL, clientID, clientSecret, scopes
oidc_userFluxo OAuth 2.0 resource owner password.tokenURL, clientID, clientSecret, username, password, scopes
Para integrações OAuth 2.0, use oidc_client_credentials. O Flowker gerencia a obtenção e renovação do token automaticamente.
{
  "authentication": {
    "type": "oidc_client_credentials",
    "config": {
      "tokenURL": "https://auth.fraudshield.com/oauth/token",
      "clientID": "flowker-integration",
      "clientSecret": "secret-value",
      "scopes": ["transactions:read", "transactions:score"]
    }
  }
}

​
Configurações de provider

As configurações de provider são independentes das configurações de executor. Enquanto uma configuração de executor define como o Flowker chama uma operação específica em um serviço externo, uma configuração de provider representa uma conexão configurada a uma instância de provider — incluindo sua URL base, credenciais e configurações específicas do ambiente. Pense assim: uma configuração de provider é a conexão, e uma configuração de executor é a operação que você executa sobre essa conexão.

​
Criar uma configuração de provider

Crie uma configuração de provider chamando o endpoint Criar configuração de provider. Forneça o providerId do catálogo e a configuração específica do provider (URL base, credenciais, etc.). O campo config é validado contra o JSON Schema do provider no catálogo. Se não corresponder, a requisição retorna um erro 422. 
POST /v1/provider-configurations

{
  "name": "Midaz Production",
  "description": "Instância Midaz de produção para operações de saldo",
  "providerId": "midaz",
  "config": {
    "base_url": "https://midaz.example.com/api/v1",
    "api_key": "sk-prod-xxx"
  },
  "metadata": {
    "environment": "production"
  }
}

​
Testar conectividade

Após criar uma configuração de provider, teste-a com o endpoint Testar configuração de provider. O teste executa três etapas — conectividade, autenticação e ponta a ponta — e retorna resultados para cada uma.

​
Habilitar e desabilitar

As configurações de provider são criadas com status active. Você pode desabilitá-la temporariamente com o endpoint Desabilitar configuração de provider e reabilitá-la com o endpoint Habilitar configuração de provider. Consulte a API de Configurações de provider para a referência completa.

​
Passo 3: Configurar o executor

Marque o executor como configurado chamando o endpoint Update executor configuration. Isso transiciona o status de unconfigured para configured.

​
Passo 4: Validar sua configuração

Antes de usar um executor em um workflow, valide sua configuração contra o schema do catálogo usando o endpoint Validate executor config (POST /v1/catalog/executors/{id}/validate). Isso executa apenas a validação de JSON Schema — verifica se o seu objeto de configuração corresponde à estrutura que o executor espera (campos obrigatórios, tipos, formatos). Não testa a conectividade com o serviço externo.
Para testar a conectividade real com um serviço externo, use o endpoint Testar configuração de provider na configuração de provider. Esse endpoint executa verificações de conectividade, autenticação e ponta a ponta contra o serviço real.

​
Mapeamento de campos e transformação de dados

Quando os dados do workflow não correspondem ao formato esperado por um serviço externo — ou quando um serviço retorna dados em um formato que o próximo passo não consegue consumir — use mapeamentos de campos e transformações para cobrir essa lacuna. Os mapeamentos de campos e transformações são definidos dentro do objeto data dos nodes executor. O Flowker aplica os mapeamentos de entrada antes de chamar o serviço externo e os mapeamentos de saída depois de receber a resposta. 
{
  "id": "executor-balance",
  "type": "executor",
  "name": "Check Balance",
  "data": {
    "providerConfigId": "a1b2c3d4-e5f6-4789-a012-345678901234",
    "inputMapping": [
      { "source": "workflow.customerId", "target": "executor.accountId" },
      { "source": "workflow.amount", "target": "executor.minimumBalance" }
    ],
    "outputMapping": [
      { "source": "executor.currentBalance", "target": "workflow.balance" },
      { "source": "executor.accountStatus", "target": "workflow.status" }
    ]
  }
}
Para integrações mais complexas, você também pode anexar transformações a entradas individuais de mapeamento (por exemplo, remover caracteres, adicionar prefixos, alterar o case) e definir operações Kazaam para transformações avançadas de JSON para JSON. Consulte a Referência de mapeamento de campos para a lista completa de tipos de transformação, estruturas JSON e orientações para solução de problemas.

​
Passo 5: Usar o executor em um workflow

Uma vez que a configuração do executor é validada, referencie-a em um workflow. O executor se torna ativo quando é usado em um workflow ativo. Para retirar temporariamente um executor de serviço, atualize sua configuração usando o endpoint Update executor configuration.

​
Usando um executor em um workflow

Referencie o executor em um node do tipo executor. O exemplo abaixo cria um workflow de validação de pagamento. Quando um pagamento chega, o Flowker chama o executor de verificação de fraude, avalia o score de risco e aprova ou rejeita o pagamento com base no resultado. O workflow tem cinco nodes: um trigger webhook que recebe o pagamento, um node executor que chama o serviço de verificação de fraude, um node conditional que avalia o score, e dois nodes action para os resultados de aprovação e rejeição. Os edges os conectam em sequência, com o node condicional bifurcando para um ou outro caminho com base no limiar do score. Use o endpoint Criar workflow para definir o workflow, depois Ativar, e finalmente Executar. 
POST /v1/workflows

{
  "name": "payment-validation",
  "description": "Valida um pagamento antes de processar.",
  "nodes": [
    {
      "id": "trigger-payment",
      "type": "trigger",
      "name": "Payment received",
      "position": { "x": 0, "y": 0 },
      "data": { "triggerType": "webhook" }
    },
    {
      "id": "check-fraud",
      "type": "executor",
      "name": "Fraud check",
      "position": { "x": 200, "y": 0 },
      "data": {
        "providerConfigId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
        "endpointName": "score-transaction"
      }
    },
    {
      "id": "evaluate-score",
      "type": "conditional",
      "name": "Score evaluation",
      "position": { "x": 400, "y": 0 },
      "data": {
        "condition": "check-fraud.score < 80"
      }
    },
    {
      "id": "approve",
      "type": "action",
      "name": "Approve payment",
      "position": { "x": 600, "y": -100 },
      "data": { "action": "log" }
    },
    {
      "id": "reject",
      "type": "action",
      "name": "Reject payment",
      "position": { "x": 600, "y": 100 },
      "data": { "action": "log" }
    }
  ],
  "edges": [
    { "id": "e1", "source": "trigger-payment", "target": "check-fraud" },
    { "id": "e2", "source": "check-fraud", "target": "evaluate-score" },
    { "id": "e3", "source": "evaluate-score", "target": "approve", "condition": "true" },
    { "id": "e4", "source": "evaluate-score", "target": "reject", "condition": "false" }
  ]
}

POST /v1/workflows/{workflowId}/executions
Idempotency-Key: {unique-uuid}

{
  "inputData": {
    "transactionId": "txn-98765",
    "amount": 1500.00,
    "currency": "BRL",
    "customerId": "cust-12345"
  }
}

​
Disparando workflows

As execuções de workflow são disparadas via endpoint Executar workflow: 
POST /v1/workflows/:workflowId/executions
O corpo da requisição contém o inputData para a execução. Todos os campos ficam disponíveis para os nodes seguintes via namespace workflow — por exemplo, workflow.transactionId ou workflow.amount. As saídas de nodes ficam disponíveis via o ID do node — por exemplo, check-fraud.score.

​
Idempotência

Para prevenir execuções duplicadas, inclua um header Idempotency-Key na requisição. Se nenhum Idempotency-Key for fornecido, a proteção contra duplicatas não é garantida.

​
Triggers por webhook

Webhooks são a principal forma de sistemas externos dispararem workflows do Flowker. Em vez de o seu sistema chamar a API de execuções diretamente, você registra um caminho de webhook em um workflow e os serviços externos enviam requisições HTTP para esse caminho.

​
Como funciona

  1. Adicione um trigger node do tipo webhook ao seu workflow com um path e method em seu data.
  2. Quando o workflow é ativado, o Flowker registra o caminho em seu registro de webhooks.
  3. Sistemas externos enviam requisições para POST /v1/webhooks/{path} (ou o método que você configurou).
  4. O Flowker resolve o caminho para o workflow correspondente e o executa.

​
Definindo um trigger node de webhook

O trigger de webhook é um node com type: "trigger" e os seguintes campos em data:
CampoTipoObrigatórioDescrição
triggerTypestringSimDeve ser "webhook".
pathstringSimO caminho do webhook a registrar (ex: "payments/received").
methodstringSimMétodo HTTP a corresponder (ex: "POST").
verify_tokenstringNãoToken estático para verificação de webhook. Quando definido, as requisições devem incluir um header X-Webhook-Token correspondente.
{
  "id": "trigger-1",
  "type": "trigger",
  "name": "Payment Webhook",
  "position": { "x": 0, "y": 0 },
  "data": {
    "triggerType": "webhook",
    "path": "payments/received",
    "method": "POST",
    "verify_token": "my-secret-token"
  }
}
Uma vez que esse workflow é ativado, sistemas externos podem dispará-lo enviando:
POST /v1/webhooks/payments/received
X-Webhook-Token: my-secret-token
Content-Type: application/json

{ "transactionId": "txn-123", "amount": 1500.00 }

​
Metadados do webhook

O Flowker injeta automaticamente um objeto _webhook no inputData da execução com metadados sobre a requisição recebida:
CampoDescrição
_webhook.methodMétodo HTTP utilizado (ex: POST).
_webhook.pathO caminho de webhook resolvido.
_webhook.headersHeaders da requisição (excluindo Authorization, X-API-Key e X-Webhook-Token).
_webhook.queryParâmetros da query string.
_webhook.remote_ipEndereço IP do chamador.
Esses metadados ficam disponíveis para todos os nodes do workflow via namespace workflow._webhook.

​
Observações importantes

  • Cada combinação de caminho de webhook + método só pode ser registrada por um workflow ativo. Ativar um segundo workflow com o mesmo caminho falha com um erro de conflito.
  • Os caminhos de webhook suportam segmentos aninhados (ex: payments/stripe/received).
  • O tamanho máximo do corpo da requisição é 1 MB.
  • Desativar um workflow automaticamente remove o registro de suas rotas de webhook.
Consulte a referência de API Disparar um webhook para a documentação completa do endpoint.

​
Tratamento de erros

Se um node falha, a execução para e é marcada como failed. Não há fallback automático. Após esgotar as retentativas, a execução falha. Cada falha inclui:
  • Node que falhou e motivo
  • Número do passo e saída
  • Código de erro
Código de erroSignificadoAção
FLK-0504Execução de node falhou.Verifique os resultados do passo e a resposta do serviço externo.
FLK-0507Circuit breaker aberto.Aguarde a recuperação ou verifique a saúde do serviço.

​
Retentativas e circuit breaker

O Flowker inclui resiliência integrada para chamadas a executors.

​
Retentativas

Quando uma chamada a um executor falha com um erro transitório, o Flowker retenta automaticamente:
  • Retentativas máximas: 5 tentativas
  • Estratégia de backoff: Exponencial — 1s, 2s, 4s, 8s
  • Erros não retentáveis: Circuit breaker aberto, contexto cancelado, configuração inválida
A retentativa se aplica por execução de node. Se todas as 5 tentativas falharem, o passo é marcado como falho e a execução para.

​
Circuit breaker

O Flowker usa um circuit breaker para proteger os serviços externos de serem sobrecarregados por chamadas falhas repetidas:
ParâmetroValor
Limiar de falhas5 falhas consecutivas abrem o circuito
Timeout de recuperação30 segundos antes de tentar novamente (estado half-open)
Requisições half-open1 requisição permitida para testar a recuperação
Quando o circuito está aberto, as chamadas a executors falham imediatamente com FLK-0507 em vez de alcançar o serviço externo. Isso previne falhas em cascata e dá tempo ao serviço externo para se recuperar.
Estados do circuit breaker
O circuito começa no estado Closed, onde todas as requisições passam normalmente. Após 5 falhas consecutivas, ele transiciona para Open, bloqueando todas as requisições imediatamente. Após 30 segundos, passa para Half-Open e permite uma requisição de teste. Se essa requisição for bem-sucedida, o circuito volta para Closed. Se falhar, o circuito reabre por mais um ciclo de 30 segundos.
O circuit breaker opera por configuração de executor. Falhas em um executor não afetam outros. Os limiares do circuit breaker (contagem de falhas, timeout de recuperação) são valores globais configurados na inicialização — não podem ser personalizados por executor nesta versão.

​
Próximos passos

Conceitos fundamentais

Entenda workflows, nodes, edges e execuções.

Executor configurations API

Explore a API de configuração de executors.