Guia de integração

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:

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.

Status	O que significa	Próximo passo
`unconfigured`	Criado com detalhes de conexão mas não completamente configurado.	Configurá-lo (PATCH)
`configured`	Detalhes de conexão definidos e validados.	Testar conectividade
`tested`	Teste de conectividade bem-sucedido.	Ativá-lo
`active`	Disponível para execução de workflows.	—
`disabled`	Temporariamente 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.

Passo 1: Explorar o catálogo

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.

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.

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.

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ção	Endpoint
Listar	`GET /v1/executors`
Consultar	`GET /v1/executors/{id}`
Atualizar	`PATCH /v1/executors/{id}`
Remover	`DELETE /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.

Tipo	Descrição	Campos de configuração
`none`	Sem autenticação.	—
`api_key`	API key no header ou query.	`key`, `header_name`, `location`, `query_param_name`, `prefix`
`bearer`	Bearer token no header Authorization.	`token`
`basic`	Usuário e senha (Base64).	`username`, `password`
`oidc_client_credentials`	Fluxo OAuth 2.0 client credentials com gestão automática de tokens.	`issuer_url`, `client_id`, `client_secret`, `scopes`
`oidc_user`	Fluxo OAuth 2.0 resource owner password.	`issuer_url`, `client_id`, `username`, `password`, `client_secret`, `scopes`
`oauth2_token_endpoint`	Client credentials OAuth 2.0 contra um token endpoint (sem discovery OIDC).	`token_url`, `client_id`, `client_secret`, `scopes`

Para integrações OAuth 2.0, use oidc_client_credentials. O Flowker gerencia a obtenção e renovação do token automaticamente.

Exemplo — OIDC client credentials

{
  "authentication": {
    "type": "oidc_client_credentials",
    "config": {
      "issuer_url": "https://auth.fraudshield.com/realms/fraudshield",
      "client_id": "flowker-integration",
      "client_secret": "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.

Exemplo de requisição

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.

Exemplo rápido — mapeando campos do workflow para um executor

{
  "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.

Exemplo — Criar um workflow de validação de pagamento

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" }
  ]
}

Exemplo — Executar o workflow

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

Toda requisição de execução precisa incluir um header Idempotency-Key. Requisições sem ele são rejeitadas com 400 Bad Request (erro FLK-0509). Gere um UUID novo para cada nova execução e reutilize a mesma chave apenas ao repetir a requisição idêntica.

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

Adicione um trigger node do tipo webhook ao seu workflow com um path e method em seu data.
Quando o workflow é ativado, o Flowker registra o caminho em seu registro de webhooks.
Sistemas externos enviam requisições para POST /v1/webhooks/{path} (ou o método que você configurou).
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:

Campo	Tipo	Obrigatório	Descrição
`triggerType`	string	Sim	Deve ser `"webhook"`.
`path`	string	Sim	O caminho do webhook a registrar (ex: `"payments/received"`).
`method`	string	Sim	Método HTTP a corresponder (ex: `"POST"`).
`verify_token`	string	Não	Token estático para verificação de webhook. Quando definido, as requisições devem incluir um header `X-Webhook-Token` correspondente.

Exemplo — Trigger node de webhook

{
  "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:

Campo	Descrição
`_webhook.method`	Método HTTP utilizado (ex: `POST`).
`_webhook.path`	O caminho de webhook resolvido.
`_webhook.headers`	Headers da requisição (excluindo `Authorization`, `X-API-Key` e `X-Webhook-Token`).
`_webhook.query`	Parâmetros da query string.
`_webhook.remote_ip`	Endereç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.

Modo de resposta síncrona

Por padrão, um trigger de webhook responde com um recibo 202 assim que a execução começa (o modo assíncrono) — o chamador precisa consultar o status da execução separadamente. Defina response_mode como "sync" no data do trigger node para que o Flowker mantenha a conexão HTTP aberta e devolva o resultado da execução diretamente na resposta:

Campo	Tipo	Obrigatório	Descrição
`response_mode`	string	Não	`"async"` (padrão) devolve um recibo `202` imediatamente. `"sync"` bloqueia (até um limite interno) até a execução atingir um estado terminal e devolve o resultado no corpo da resposta.
`response_view`	string	Não	Define o formato do corpo da resposta síncrona. Só tem efeito quando `response_mode` é `"sync"`. Ver a tabela abaixo. O padrão é `"full"`.

Se a execução não atingir um estado terminal antes de o limite interno de espera se esgotar, o Flowker recorre ao mesmo recibo 202 (com um header Location apontando para o endpoint de resultados) que o modo assíncrono teria devolvido. response_view define o formato do corpo da resposta síncrona:

Valor	Descrição
`full` (padrão)	O dump completo da execução — `executionId`, `workflowId`, `status`, `stepResults`, `finalOutput` — o mesmo formato que você obteria do endpoint de resultados da execução.
`final_output`	Somente o mapa `finalOutput` da execução, sem envelope.
`receipt`	O recibo de execução enxuto (`executionId`, `workflowId`, `status`, `startedAt`) — o mesmo formato devolvido pelo caminho assíncrono.
`passthrough`	Define o formato da resposta pelo tipo de node do step terminal (o último executado). Se o step terminal é um executor que capturou uma resposta HTTP do provedor, essa resposta é repassada verbatim (código de status — incluindo `4xx` — + corpo + `Content-Type`), sem passar pelo envelope do Flowker. Se o step terminal é uma ação `set_output` com output configurado, a resposta é o output de negócio desse node, respeitando seu override de `responseStatusCode`. Se nenhum dos dois se aplica (sem resposta do provedor capturada — breaker aberto, timeout, falha antes do despacho — e sem output terminal), recorre ao envelope completo com HTTP `200` para que o chamador ainda receba um resultado significativo.

O finalOutput de uma execução com falha (nas views full ou final_output) sempre traz status: "failed" e errorMessage, e errorClass quando o Flowker conseguiu classificar a falha — nunca um {} vazio. Sem um override de responseStatusCode (ver abaixo), o status HTTP síncrono permanece 200 para full/final_output/receipt (reporta a saúde do transporte, não o resultado de negócio). Um responseStatusCode válido no node set_output terminal sobrescreve esse status para essas três views. Um node de ação com actionType: "set_output" pode carregar um responseStatusCode opcional (inteiro, 200–599) para sobrescrever o status HTTP que uma resposta de webhook sync devolve. Um valor fora do intervalo ou não inteiro é rejeitado ao salvar (FLK-0122). Para passthrough, o override se aplica somente quando o próprio node set_output é o step terminal — o status repassado de um executor terminal sempre vence, e o fallback sem resposta sempre usa um 200 puro para que um override nunca mascare uma falha. A detecção do passthrough é estrita: só o step terminal conta. Um set_output terminal depois de um executor responde com o próprio output — o Flowker nunca volta à resposta de um executor anterior. Em uma execução com falha, o step que interrompeu a execução é o terminal, então um 4xx do provedor que parou o workflow é repassado como o 4xx real. Os valores do output de um node set_output suportam referências ${...} resolvidas contra o contexto do workflow — incluindo ${workflow.<campo>} (payload do trigger), ${execution.id}, ${execution.startedAt} e ${execution.now} (carimbado no momento da interpolação). Uma referência ${...} que não pode ser resolvida faz o step falhar (fail-closed).

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 erro	Significado	Ação
`FLK-0504`	Execução de node falhou.	Verifique os resultados do passo e a resposta do serviço externo.
`FLK-0507`	Circuit 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. O comportamento de retentativa é configurável por node na configuração do executor:

Configuração	Padrão	Limites	Descrição
`timeout_seconds`	30	1–300	Timeout por requisição.
`retry.max_attempts`	3	1–5 (teto da plataforma)	Tentativas totais (inicial + retentativas).
`retry.backoff_seconds`	1	1–60	Semente do backoff inicial; a espera dobra a cada tentativa (com jitter).
`success_status_codes`	`[200, 201, 202, 204]`	100–599	Códigos de status HTTP tratados como sucesso.

Retentativas só se aplicam quando a operação é segura de repetir. Por padrão, chamadas POST e PATCH são tratadas como não idempotentes e não são retentadas (uma única tentativa), enquanto GET, PUT, DELETE e outros verbos retentam normalmente. Configurar retry.max_attempts explicitamente em um node habilita as retentativas para esse node independentemente do método. Erros não retentáveis cortam para uma única tentativa independentemente da configuração: circuit breaker aberto, contexto cancelado, erros de configuração, falhas de resolução de secrets e respostas 4xx não transitórias do provedor (qualquer 4xx exceto 408 e 429). A retentativa se aplica por execução de node. Se todas as 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âmetro	Valor
Limiar de falhas	20 falhas consecutivas abrem o circuito (configurável no deployment)
Timeout de recuperação	30 segundos antes de tentar novamente (estado half-open)
Requisições half-open	1 requisição permitida para testar a recuperação

Erros 4xx de cliente/autenticação do provedor não disparam o circuito: são um problema do chamador, não um sinal de que o provedor está fora do ar. Somente falhas de transporte e 5xx contam para o limiar. 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 — Transições de estado do circuit breaker

O circuito começa no estado Closed, onde todas as requisições passam normalmente. Ao atingir o limiar de falhas, 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 no deployment — não podem ser personalizados por executor nesta versão.

Visão geral

Guias

Console

Operações

Guia de integração

Ciclo de vida da configuração de executor

Passo 1: Explorar o catálogo

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

Criar uma configuração de provider

Gerenciar configurações de executor

Tipos de autenticação

Configurações de provider

Criar uma configuração de provider

Testar conectividade

Habilitar e desabilitar

Passo 3: Configurar o executor

Passo 4: Validar sua configuração

Mapeamento de campos e transformação de dados

Passo 5: Usar o executor em um workflow

Usando um executor em um workflow

Disparando workflows

Idempotência

Triggers por webhook

Como funciona

Definindo um trigger node de webhook

Metadados do webhook

Observações importantes

Modo de resposta síncrona

Tratamento de erros

Retentativas e circuit breaker

Retentativas

Circuit breaker

Próximos passos

Conceitos fundamentais

Executor configurations API

​Ciclo de vida da configuração de executor

​Passo 1: Explorar o catálogo

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

​Criar uma configuração de provider

​Gerenciar configurações de executor

​Tipos de autenticação

​Configurações de provider

​Criar uma configuração de provider

​Testar conectividade

​Habilitar e desabilitar

​Passo 3: Configurar o executor

​Passo 4: Validar sua configuração

​Mapeamento de campos e transformação de dados

​Passo 5: Usar o executor em um workflow

​Usando um executor em um workflow

​Disparando workflows

​Idempotência

​Triggers por webhook

​Como funciona

​Definindo um trigger node de webhook

​Metadados do webhook

​Observações importantes

​Modo de resposta síncrona

​Tratamento de erros

​Retentativas e circuit breaker

​Retentativas

​Circuit breaker

​Próximos passos

Conceitos fundamentais

Executor configurations API

Ciclo de vida da configuração de executor

Passo 1: Explorar o catálogo

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

Criar uma configuração de provider

Gerenciar configurações de executor

Tipos de autenticação

Configurações de provider

Criar uma configuração de provider

Testar conectividade

Habilitar e desabilitar

Passo 3: Configurar o executor

Passo 4: Validar sua configuração

Mapeamento de campos e transformação de dados

Passo 5: Usar o executor em um workflow

Usando um executor em um workflow

Disparando workflows

Idempotência

Triggers por webhook

Como funciona

Definindo um trigger node de webhook

Metadados do webhook

Observações importantes

Modo de resposta síncrona

Tratamento de erros

Retentativas e circuit breaker

Retentativas

Circuit breaker

Próximos passos