> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Guia de integração > Conecte serviços externos ao Flowker usando executors. Configure autenticação, teste conectividade e execute workflows com integrações reais. 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. | 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. Chame o endpoint [Listar executors do catálogo](/pt/reference/flowker/list-catalog-executors) para ver todos os tipos de executor que o Flowker suporta — requisições HTTP, transformações de dados e mais. Chame o endpoint [Listar triggers do catálogo](/pt/reference/flowker/list-catalog-triggers) para ver como os workflows podem ser iniciados — webhooks ou chamadas API manuais. 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`](/pt/reference/flowker/list-catalog-executors)) no [Passo 1](#passo-1-explorar-o-catálogo). 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`](/pt/reference/flowker/create-provider-configuration) 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](#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`](/pt/reference/flowker/list-executor-configurations) | | Consultar | [`GET /v1/executors/{id}`](/pt/reference/flowker/get-executor-configuration) | | Atualizar | [`PATCH /v1/executors/{id}`](/pt/reference/flowker/update-executor-configuration) | | Remover | [`DELETE /v1/executors/{id}`](/pt/reference/flowker/delete-executor-configuration) | 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](/pt/reference/flowker/list-executor-configurations) 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. ```json theme={null} { "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](/pt/reference/flowker/create-provider-configuration). 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`. ```json theme={null} 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](/pt/reference/flowker/test-provider-configuration). 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](/pt/reference/flowker/disable-provider-configuration) e reabilitá-la com o endpoint [Habilitar configuração de provider](/pt/reference/flowker/enable-provider-configuration). Consulte a [API de Configurações de provider](/pt/reference/flowker/list-provider-configurations) para a referência completa. ## Passo 3: Configurar o executor *** Marque o executor como configurado chamando o endpoint [Update executor configuration](/pt/reference/flowker/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](/pt/reference/flowker/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](/pt/reference/flowker/test-provider-configuration) 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. ```json theme={null} { "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](/pt/flowker/field-mapping-reference) 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](/pt/reference/flowker/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](/pt/reference/flowker/create-workflow) para definir o workflow, depois [Ativar](/pt/reference/flowker/activate-workflow), e finalmente [Executar](/pt/reference/flowker/execute-workflow). ```json theme={null} 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" } ] } ``` ```json theme={null} 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](/pt/reference/flowker/execute-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 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}`](/pt/reference/flowker/trigger-webhook) (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`: | 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. | ```json theme={null} { "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](/pt/reference/flowker/trigger-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.}` (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 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. ## Próximos passos *** Entenda workflows, nodes, edges e execuções. Explore a API de configuração de executors.