> ## 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 por configurações de provedor. Configure a autenticação, mapeie campos e rode workflows contra integrações reais. O Flowker chama serviços externos (como motores de fraude, processadores de pagamento e provedores de KYC) por configurações de provedor. Uma configuração de provedor é a sua conexão com uma instância viva de um serviço externo. Neste guia, você explora o catálogo, cria uma configuração de provedor e a referencia a partir de um nó de workflow. Depois você mapeia campos entre os seus dados e o serviço, e aprende como o Flowker repete e protege essas chamadas.

Passo 1: Explore o catálogo

*** O catálogo é um registro somente leitura dos provedores, executores de catálogo e gatilhos que vêm com o Flowker. Você os descobre. Você nunca os cria. Chame o endpoint [Listar provedores do catálogo](/pt/reference/products/flowker/list-catalog-providers) para ver os tipos de serviço a que o Flowker se conecta. O catálogo sempre inclui o conector HTTP genérico. Provedores nativos como `ledger` (Midaz) e `tracer` são sintetizados a partir de especificações OpenAPI publicadas e aparecem apenas quando o registro nativo de esquemas está configurado e a síntese tem sucesso. Chame o endpoint [Listar executores do catálogo](/pt/reference/products/flowker/list-catalog-executors) para ver as operações que um nó de workflow pode invocar. Use [Listar executores por provedor](/pt/reference/products/flowker/list-executors-by-provider) para estreitar a lista a um provedor. Chame o endpoint [Listar gatilhos do catálogo](/pt/reference/products/flowker/list-catalog-triggers) para ver os tipos de gatilho nativos: webhooks e agendamentos. A API de executar workflow começa um workflow, mas não é um gatilho de catálogo. Anote o `providerId` e o id do executor de catálogo que combinam com a sua integração. Você usa o primeiro no [Passo 2](#step-2-create-a-provider-configuration) e o segundo no [Passo 3](#step-3-reference-the-provider-configuration-from-a-workflow-node). Pense no catálogo como um cardápio: ele mostra o que o Flowker pode chamar. As configurações de provedor são os seus pedidos específicos: a URL base, as credenciais e as configurações de cada instância de serviço que você usa.

Passo 2: Crie uma configuração de provedor

*** Chame [`POST /v1/provider-configurations`](/pt/reference/products/flowker/create-provider-configuration) para definir a sua conexão com uma instância de um serviço externo. | Campo | Obrigatório | Descrição | | --------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | Sim | Um nome para esta conexão, de 1 a 100 caracteres. | | `kind` | Não | Que tipo de conexão é esta. Omita-o, ou envie `catalog`, para uma conexão com um provedor de catálogo — o caso que este guia cobre. Envie `external_openapi` para uma conexão com um documento OpenAPI que você subiu; veja [Como conectar sua própria API](/pt/products/flowker/connecting-your-own-api). Você escolhe o tipo quando cria a configuração. | | `providerId` | Para `catalog` | O provedor de catálogo do qual esta conexão é uma instância, como `ledger` ou `http`. Uma configuração do tipo `external_openapi` pode omiti-lo, e uma leitura dela devolve o id reservado `external.openapi`. | | `config` | Sim | Os detalhes de conexão daquela instância, como a URL base e as credenciais de autenticação. O Flowker valida este mapa contra o JSON Schema do provedor vindo do catálogo e devolve `422` quando ele não combina. O secret dentro do bloco `auth` fica no seu backend de secrets, não no documento de configuração; todo o resto do mapa é guardado com a configuração. | | `allowedHosts` | Para `http` | Os hosts públicos que esta configuração pode chamar. O conector HTTP genérico (`providerId: "http"`) exige pelo menos uma entrada, e uma lista vazia é rejeitada com `FLK-0323`. Provedores nativos aceitam uma lista vazia. Uma entrada com ponto inicial combina com subdomínios — `.kyc-provider.io` combina com `api.kyc-provider.io`. Apenas nomes de host: sem IPs literais, curingas ou portas. O host em `config.base_url` deve estar coberto pela lista, senão a criação é rejeitada com `FLK-0320`. | | `allowedPrivateHosts` | Não | Hosts privados nomeados que o seu time de operações permite que esta configuração alcance. Metadados de nuvem e endereços link-local continuam bloqueados. | | `schemaBindings` | Não | Os esquemas XSD ou OpenAPI vinculados a esta configuração, cada um com uma restrição opcional a operações OpenAPI específicas. | | `description` | Não | Texto livre, de até 500 caracteres. | | `metadata` | Não | Seus próprios pares de chave e valor. | Um `providerId` é um identificador de catálogo, e nem sempre combina com o nome do produto. O catálogo registra o Midaz como `ledger`. Pegue sempre o valor em [Listar provedores do catálogo](/pt/reference/products/flowker/list-catalog-providers) em vez de adivinhá-lo pelo nome do produto. O `providerId` na configuração e o `executorId` no nó que a usa devem pertencer ao mesmo provedor de catálogo. O conector HTTP genérico usa `http` nos dois. O Flowker rejeita um workflow que junta uma configuração de um provedor com um executor de outro, com `FLK-0151`. O exemplo abaixo monta a conexão que este guia usa daqui em diante: um serviço de pontuação de fraude alcançado pelo conector HTTP genérico. ```json theme={null} POST /v1/provider-configurations { "name": "FraudShield Production", "description": "Production fraud scoring service", "providerId": "http", "config": { "base_url": "https://api.fraudshield.example.com", "auth": { "type": "api_key", "config": { "key": "sk-prod-xxx", "header_name": "X-API-Key", "location": "header" } } }, "allowedHosts": ["api.fraudshield.example.com"], "metadata": { "environment": "production" } } ``` A resposta devolve o `id` da nova configuração. Guarde-o. O [Passo 3](#step-3-reference-the-provider-configuration-from-a-workflow-node) e o [Passo 4](#step-4-run-the-workflow) o colocam no `providerConfigId` do nó que chama o serviço.

Autenticação

O bloco `config.auth` guarda a autenticação que o serviço externo exige, como um par `{ type, config }`. Use o método que o seu serviço espera. | Tipo | Descrição | Campos de config | | ------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | `none` | Sem autenticação. | — | | `api_key` | API key no header ou na query. | `key`, `header_name`, `location`, `query_param_name`, `prefix` | | `bearer` | Bearer token no header Authorization. | `token` | | `basic` | Username e senha (Base64). | `username`, `password` | | `oidc_client_credentials` | Fluxo OAuth 2.0 de client credentials com gestão automática de token. | `issuer_url`, `client_id`, `client_secret`, `scopes` | | `oidc_user` | Fluxo OAuth 2.0 de senha do dono do recurso. | `issuer_url`, `client_id`, `username`, `password`, `client_secret`, `scopes` | | `oauth2_token_endpoint` | Client credentials OAuth 2.0 contra um token endpoint (sem descoberta OIDC). | `token_url`, `client_id`, `client_secret`, `scopes` | | `hmac` | Assina cada requisição com um secret HMAC compartilhado. | `secret`, `algorithm`, `encoding`, `header_name`, `signature_prefix`, `signing_string`, `timestamp_header` | O Flowker guarda as folhas secretas em `config.auth` fora do documento de configuração persistido. Uma leitura autorizada da configuração de provedor pode resolver esses valores no cofre e devolvê-los em texto claro. Folhas não resolvidas continuam mascaradas. Conceda o acesso de leitura de acordo. Qualquer outra coisa que você coloque no documento de configuração (um header, por exemplo) fica com a configuração, e uma leitura pode retorná-la. Coloque cada credencial em `config.auth`. Para rotacionar um secret, envie o novo valor em uma atualização. Para manter o atual, omita o campo ou envie-o em branco. Isso funciona enquanto `auth.type` continua o mesmo. Uma atualização que muda `auth.type` deve carregar um valor para cada secret que o novo tipo exige e o anterior não exigia. Caso contrário o Flowker a rejeita com `FLK-0952`. Uma mudança entre dois tipos que usam o mesmo secret, como `oidc_user` para `oidc_client_credentials`, não precisa desse valor de novo. Para integrações OAuth 2.0, use `oidc_client_credentials`. O Flowker cuida da obtenção e da renovação de token automaticamente. ```json theme={null} { "auth": { "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"] } } } ``` ### Como habilitar e desabilitar Configurações de provedor têm dois status: `active` (em uso) e `disabled` (temporariamente fora). Uma nova configuração de provedor começa no status `active`. Use [Desabilitar configuração de provedor](/pt/reference/products/flowker/disable-provider-configuration) para tirar uma conexão de serviço e [Habilitar configuração de provedor](/pt/reference/products/flowker/enable-provider-configuration) para trazê-la de volta. Veja a [API de configurações de provedor](/pt/reference/products/flowker/list-provider-configurations) para a referência completa.

Passo 3: Referencie a configuração de provedor a partir de um nó de workflow

*** Cada nó executor carrega um `providerConfigId`, o identificador da configuração de provedor pela qual ele chama. O Flowker rejeita um workflow cujo nó executor não tem `providerConfigId`, e rejeita um valor que não é um UUID. Em tempo de execução, ele monta cada requisição de saída com a URL base daquela configuração de provedor mais o caminho no nó. O nó falha se a configuração de provedor não estiver `active`. Estes são os campos que um nó executor define no seu objeto `data` quando chama pelo conector HTTP genérico: | Campo | Obrigatório | Descrição | | -------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `executorId` | Sim | O executor de catálogo que este nó invoca, tirado do [Passo 1](#step-1-explore-the-catalog). O Flowker rejeita o workflow quando o id não está no catálogo. Um nó que chama um documento OpenAPI que você subiu o omite — veja abaixo. | | `providerConfigId` | Sim | O UUID da configuração de provedor pela qual este nó chama. | | `path` | Não | O caminho da requisição anexado à URL base da configuração de provedor. O host de destino é sempre aquela URL base — um nó não pode informar uma URL absoluta. | | `endpointName` | Não | O mesmo segmento de requisição por nome, usado quando o nó não define `path`. Um nó que carrega os dois envia `path`. | | `method` | Não | `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD` ou `OPTIONS`. O padrão é `POST`. | | `headers` | Não | Headers da requisição, mesclados sobre os que a configuração de provedor define. Um header do nó vence um header de mesmo nome da configuração de provedor. | | `query` | Não | Parâmetros de query anexados à URL. | | `auth` | Não | Um bloco de autenticação `{type, config}` para este nó, no mesmo formato que a configuração de provedor usa. Quando presente, ele tem precedência sobre a autenticação na configuração de provedor. | | `body` | Não | Um corpo de requisição explícito, resolvido contra o contexto do workflow. Quando definido, ele é a única fonte de corpo — os mapeamentos de campo não se aplicam a ele. | | `content_digest` | Não | Uma trava SHA-256 para o corpo montado da requisição. Defina um digest hexadecimal de 64 caracteres, ou um valor resolvido a partir do contexto do workflow. O Flowker faz o hash dos bytes finais depois de montar o corpo e envia a requisição apenas quando eles combinam. | | `config` | Não | Valores literais fixos que alimentam o corpo da requisição. Veja [Mapeamento de campos e transformação de dados](#field-mapping-and-data-transformation). | | `inputMapping`, `outputMapping`, `transforms` | Não | Mapeamentos de campo e transformações. Veja [Mapeamento de campos e transformação de dados](#field-mapping-and-data-transformation). | | `timeout_seconds`, `retry`, `success_status_codes` | Não | Configurações de resiliência por nó. Veja [Novas tentativas e circuit breaker](#retry-and-circuit-breaker). | | `request_format` | Não | Como o Flowker serializa o corpo da requisição: `json` (o padrão), `xml_converted` ou `xml_passthrough`. `xml_converted` também exige `root_element`. | Um nó que chama uma operação de um documento OpenAPI que você subiu a nomeia com `operation_path` e `operation_method` em vez de um `executorId`. O Flowker preenche o `executorId` para você a partir da configuração de provedor para a qual o nó aponta. [Como conectar sua própria API](/pt/products/flowker/connecting-your-own-api) percorre esse caminho inteiro. ### Valide a configuração de um nó antes de salvar Chame o endpoint [Validar a configuração de um nó](/pt/reference/products/flowker/validate-executor-config) (`POST /v1/catalog/executors/{id}/validate`) para conferir a configuração de um nó contra o JSON Schema do executor de catálogo. Isso faz **apenas a validação de JSON Schema**. Confere se o seu objeto de configuração combina com a estrutura que o executor de catálogo espera (campos obrigatórios, tipos, formatos). Não chama o serviço externo, então a primeira ida e volta real acontece quando um workflow roda o nó. Passe `mappedTargets` para nomear os campos que o seu nó fornece por um `inputMapping` em vez de um valor fixo. Esses campos contam como satisfeitos, então um nó que mapeia um campo obrigatório vindo do gatilho valida antes de você salvá-lo.

Mapeamento de campos e transformação de dados

*** Use mapeamentos de campo e transformações quando os dados do workflow não combinam com o formato que um serviço externo espera. Use-os também quando um serviço devolve dados em um formato que a próxima etapa não consome. Você define os mapeamentos de campo e as transformações dentro do objeto `data` dos nós executores. 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. Um `target` de entrada é um caminho no corpo da requisição de saída, escrito exatamente como o serviço externo espera. Não há objeto envolvente nem prefixo a acrescentar. Um `source` de saída é um caminho dentro do envelope da resposta, então os campos da resposta ficam sob `body`. ```json theme={null} { "id": "executor-balance", "type": "executor", "name": "Check Balance", "data": { "executorId": "http", "providerConfigId": "a1b2c3d4-e5f6-4789-a012-345678901234", "path": "/accounts/balance", "inputMapping": [ { "source": "workflow.customerId", "target": "accountId" }, { "source": "workflow.amount", "target": "minimumBalance" } ], "outputMapping": [ { "source": "body.currentBalance", "target": "balance" }, { "source": "body.accountStatus", "target": "status" } ] } } ``` Os nós seguintes leem a saída mapeada sob o ID deste nó: `${executor-balance.balance}`. Para integrações complexas, você também pode anexar transformações a entradas individuais de mapeamento (por exemplo, remover caracteres, adicionar prefixos, mudar a caixa). Você pode definir operações Kazaam para transformações avançadas de JSON para JSON. [Trabalhar com dados de requisição e de resposta](/pt/products/flowker/working-with-request-and-response-data) percorre o caminho inteiro. Cobre como declarar os mapeamentos, escolher o que monta o corpo da requisição e remodelar valores em trânsito. Cobre também como ler a resposta de volta e conferir a requisição montada antes de chamar o serviço.

Passo 4: Rode o workflow

*** Referencie a configuração de provedor em um nó de workflow do tipo `executor`. O exemplo abaixo cria um workflow de validação de pagamento em cima da conexão FraudShield do [Passo 2](#step-2-create-a-provider-configuration). Quando um pagamento chega, o Flowker chama o serviço de checagem de fraude, avalia a pontuação de risco e aprova ou rejeita o pagamento conforme o resultado. O workflow tem cinco nós. Um **gatilho** de webhook recebe o pagamento, e um nó **executor** chama o serviço de checagem de fraude. Um nó **condicional** avalia a pontuação, e há dois nós de **ação** para os resultados de aprovar e rejeitar. Arestas os conectam em sequência, com o nó condicional ramificando para um caminho ou outro conforme o limiar da pontuação. Use o endpoint [Criar workflow](/pt/reference/products/flowker/create-workflow) para definir o workflow, depois [Ative](/pt/reference/products/flowker/activate-workflow) e por fim [Execute](/pt/reference/products/flowker/execute-workflow). ```json theme={null} POST /v1/workflows { "name": "payment-validation", "description": "Validates a payment before processing.", "nodes": [ { "id": "trigger-payment", "type": "trigger", "name": "Payment received", "position": { "x": 0, "y": 0 }, "data": { "triggerType": "webhook", "path": "payments/received", "method": "POST", "input_contract": "open", "format": "json" } }, { "id": "check-fraud", "type": "executor", "name": "Fraud check", "position": { "x": 200, "y": 0 }, "data": { "executorId": "http", "providerConfigId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a", "path": "/score-transaction", "method": "POST" } }, { "id": "evaluate-score", "type": "conditional", "name": "Score evaluation", "position": { "x": 400, "y": 0 }, "data": { "condition": "check-fraud.body.score < 80" } }, { "id": "approve", "type": "action", "name": "Approve payment", "position": { "x": 600, "y": -100 }, "data": { "actionType": "set_output", "output": { "decision": "approved" } } }, { "id": "reject", "type": "action", "name": "Reject payment", "position": { "x": 600, "y": 100 }, "data": { "actionType": "set_output", "output": { "decision": "rejected" } } } ], "edges": [ { "id": "e1", "source": "trigger-payment", "target": "check-fraud" }, { "id": "e2", "source": "check-fraud", "target": "evaluate-score" }, { "id": "e3", "source": "evaluate-score", "target": "approve", "sourceHandle": "true" }, { "id": "e4", "source": "evaluate-score", "target": "reject", "sourceHandle": "false" } ] } ``` O nó `check-fraud` nomeia `http`, o conector HTTP genérico do catálogo. Ele também nomeia a configuração FraudShield do Passo 2, que guarda a URL base e as credenciais. Os dois lados nomeiam o mesmo provedor, então o workflow salva. O Flowker envia a requisição para `https://api.fraudshield.example.com/score-transaction`. O nó não declara `outputMapping`, então a saída dele mantém o formato do envelope da resposta. A pontuação fica então em `check-fraud.body.score`, que é o que a condição `evaluate-score` lê. Adicione um `outputMapping` quando você preferir um nome mais raso. Veja [Mapeamento de campos e transformação de dados](#field-mapping-and-data-transformation). ```json theme={null} POST /v1/workflows/{workflowId}/executions Idempotency-Key: {unique-uuid} { "inputData": { "transactionId": "txn-98765", "amount": 1500.00, "currency": "BRL", "customerId": "cust-12345" } } ``` ## Como disparar workflows *** Você dispara execuções de workflow pelo endpoint [Executar workflow](/pt/reference/products/flowker/execute-workflow): ``` POST /v1/workflows/:workflowId/executions ``` O corpo da requisição contém o `inputData` da execução. Todos os campos ficam disponíveis para os nós seguintes pelo namespace `workflow` (por exemplo, `workflow.transactionId` ou `workflow.amount`). As saídas dos nós ficam disponíveis pelo ID do nó (por exemplo, `check-fraud.body.score` para um nó que não declara `outputMapping`). ### Idempotência Cada requisição de execução deve incluir um header `Idempotency-Key`. Uma requisição sem ele falha 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. ## Gatilhos de 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. Os serviços externos então enviam requisições HTTP para esse caminho. ### Como funciona 1. Adicione um nó de gatilho do tipo `webhook` ao seu workflow com um `path` e um `method` no seu `data`. Defina `input_contract` explicitamente em nós novos quando você precisa de validação `open`, `xsd` ou `openapi`. 2. Quando você ativa o workflow, o Flowker registra o caminho no seu registro de webhooks. 3. Sistemas externos enviam requisições para [`POST /v1/webhooks/{path}`](/pt/reference/products/flowker/trigger-webhook) (ou o método que você configurou). 4. O Flowker resolve o caminho para o workflow correspondente e o executa. ### Como definir um nó de gatilho de webhook O gatilho de webhook é um nó com `type: "trigger"` e `triggerType: "webhook"` no seu `data`, mais um `path`, um `method` e um `input_contract` opcional. [Como configurar um gatilho de webhook](/pt/products/flowker/configuring-a-webhook-trigger) cobre cada campo, os três modos de `input_contract` e o que cada um exige, e traz um nó resolvido para cada modo. A configuração do gatilho segue um contrato fechado. Salvar um workflow falha com `FLK-0934` quando o gatilho de webhook dele omite `path` ou `method`, ou deixa de fora um campo que o modo de `input_contract` escolhido exige. Também falha quando o gatilho nomeia o id de schema ou o campo de operação de outro modo. Falha também quando o gatilho carrega uma chave ou um valor que o schema não aceita. Uma declaração inválida de `accepted_headers` falha, em vez disso, com `FLK-0957`. O schema também declara os campos opcionais `response_mode`, `response_view` e `accepted_headers`. Veja [Como configurar um gatilho de webhook](/pt/products/flowker/configuring-a-webhook-trigger).

Como proteger um webhook

A entrega de webhook usa a mesma autenticação do resto da API. Com o Access Manager habilitado (`PLUGIN_AUTH_ENABLED=true`), cada requisição a `/v1/webhooks/*` deve carregar um Bearer token (OIDC JWT), e quem chama deve ter a permissão `execute` no recurso `webhooks`. Uma requisição sem um token válido falha com `401 Unauthorized`. Conceda essa permissão a uma identidade máquina a máquina para cada sistema que você deixa chamar os seus webhooks, e gerencie a concessão no Access Manager. Isso mantém o acesso ao webhook sob o mesmo modelo de papéis e políticas da gestão de workflows, em vez de uma credencial presa ao caminho.

Metadados do webhook

O Flowker injeta automaticamente um objeto `_webhook` no `inputData` da execução com metadados sobre a requisição que chegou: | Campo | Descrição | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `_webhook.method` | Método HTTP usado (por exemplo, `POST`). | | `_webhook.path` | O caminho de webhook resolvido. | | `_webhook.headers` | Headers da requisição, filtrados por uma lista de permissão segura (`Content-Type`, `Accept`, `User-Agent`, `X-Request-Id`, `X-Forwarded-For`, `Idempotency-Key`) mais os `accepted_headers` opcionais deste gatilho e, para uma rota `openapi`, os parâmetros de header da operação dela. A lista de bloqueio fixa barra `Authorization`, `Proxy-Authorization`, `Cookie`, `Set-Cookie`, `X-API-Key` e `X-Auth-Token`. Outros headers admitidos são persistidos literalmente; nunca admita nomes que carregam secrets, como `X-Amz-Security-Token`. | | `_webhook.query` | Preserva os nomes dos parâmetros de query recebidos. Preserva os valores apenas de `customerId`, `page`, `cursor`, `limit`, `offset` e `sortOrder` (sem diferenciar maiúsculas); todo outro valor é guardado como `[redacted]`. | | `_webhook.remote_ip` | Endereço IP de quem chamou. | Esses metadados ficam disponíveis para todos os nós do workflow pelo namespace `workflow._webhook`. ### Notas importantes * Apenas um workflow ativo pode registrar cada combinação de caminho e método de webhook. Ativar um segundo workflow com o mesmo caminho falha com um erro de conflito. * Caminhos de webhook aceitam segmentos aninhados (por exemplo, `payments/stripe/received`). * O tamanho máximo do corpo da requisição é 1 MB. * Desativar um workflow cancela automaticamente o registro das rotas de webhook dele. Veja a referência da API [Disparar um webhook](/pt/reference/products/flowker/trigger-webhook) para a documentação completa do endpoint.

Modo de resposta síncrona

Por padrão, um gatilho de webhook responde com um recibo `202` assim que a execução começa (o modo assíncrono). Quem chama deve consultar o status da execução em separado. Defina `response_mode` como `"sync"` no `data` do nó de gatilho para que o Flowker mantenha a conexão HTTP aberta e devolva o resultado da execução direto na resposta: | Campo | Tipo | Obrigatório | Descrição | | --------------- | ------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `response_mode` | string | Não | `"async"` (o padrão) devolve um recibo `202` na hora. `"sync"` bloqueia (até um limite interno) até a execução chegar a um estado terminal e devolve o resultado no corpo da resposta. | | `response_view` | string | Não | Dá forma ao corpo da resposta síncrona. Faz sentido apenas quando `response_mode` é `"sync"`. Veja a tabela abaixo. O padrão é `"full"`. | Se a execução não chega a um estado terminal antes de o limite interno de espera se esgotar, o Flowker recorre ao recibo `202` do modo assíncrono. Esse recibo carrega um header `Location` apontando para o endpoint de resultados. `response_view` escolhe o formato do corpo da resposta síncrona: | Valor | Descrição | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `full` (o padrão) | O dump completo da execução — `executionId`, `workflowId`, `status`, `stepResults`, `finalOutput` — o mesmo formato que você buscaria no endpoint de resultados da execução. | | `final_output` | Apenas o mapa `finalOutput` da execução, sem envelope em volta. | | `receipt` | O recibo enxuto da execução (`executionId`, `workflowId`, `status`, `startedAt`) — o mesmo formato que o caminho assíncrono devolve. | | `passthrough` | Dá forma à resposta pelo **tipo de nó da etapa terminal (a última executada)**. Para um executor terminal que capturou uma resposta de provedor, devolve o status do provedor (inclusive `4xx`) e o `Content-Type`. Repassa no máximo 8 KiB do corpo capturado; corpos maiores são truncados. Corpos JSON são decodificados e reserializados antes da captura, então o repasse byte a byte não é garantido. Se a etapa terminal é uma ação `set_output` com uma saída configurada, a resposta é a saída de negócio daquele nó, respeitando o override de `responseStatusCode` dele. Se nenhum dos dois se aplica (sem resposta de provedor capturada — circuito aberto, timeout, falha antes do despacho — e sem saída terminal), ele recorre ao envelope completo com HTTP `200`, para que quem chama ainda receba um resultado útil. | O `finalOutput` de uma execução que falhou (nas visões `full` ou `final_output`) sempre carrega `status: "failed"` e `errorMessage`, e `errorClass` quando o Flowker conseguiu classificar a falha, nunca um `{}` vazio. Sem um override de `responseStatusCode` (veja abaixo), o status HTTP síncrono continua `200` para `full`/`final_output`/`receipt` (ele reporta a saúde do transporte, não o resultado de negócio). Um `responseStatusCode` válido no nó `set_output` terminal sobrepõe esse status nessas três visões. Um nó de ação com `actionType: "set_output"` pode carregar um `responseStatusCode` opcional (inteiro, `200`–`599`) para sobrepor o status HTTP que uma resposta de webhook `sync` devolve. Um valor fora do intervalo ou não inteiro falha na hora de salvar (`FLK-0122`). Para `passthrough`, o override se aplica apenas quando o próprio nó `set_output` é a etapa terminal. O status de provedor repassado por um executor terminal sempre vence, e o caminho de reserva sem resposta sempre usa um `200` simples, para que um override nunca mascare uma falha. A detecção de passthrough é estrita: apenas a etapa terminal conta. Um `set_output` terminal depois de um executor dá forma à resposta como a saída dele mesmo. O Flowker nunca volta atrás para a resposta de um executor anterior. Em uma execução que falhou, a etapa que parou é a etapa terminal, então o Flowker repassa um `4xx` de provedor que parou o workflow como o `4xx` real. Os valores na saída de um nó `set_output` aceitam referências `${...}` resolvidas contra o contexto do workflow, incluindo `${workflow.}` (payload do gatilho), `${execution.id}`, `${execution.startedAt}` e `${execution.now}` (carimbado no momento da interpolação). Uma referência `${...}` que não resolve faz a etapa falhar (fail-closed). ## Tratamento de erros *** Se um nó falha, a execução para e o status dela vira `failed`. Não existe fallback automático. Depois que as novas tentativas acabam, a execução falha. Os resultados da execução reportam o `status` da execução e os `stepResults`. Uma etapa que falhou fornece `stepNumber`, `nodeId`, `status` e `errorMessage`, com `statusCode` e `errorClass` quando disponíveis. O campo `output` é opcional. Não prometa um `errorCode`, incluindo `FLK-0504` ou `FLK-0507`, em todo payload de resultados de execução.

Novas tentativas e circuit breaker

*** O Flowker inclui resiliência nativa para chamadas de executor. ### Novas tentativas Quando uma chamada de executor falha com um erro transitório (um erro de rede, um timeout na tentativa, qualquer status `5xx`, ou status `408` ou `429`), o Flowker tenta de novo automaticamente. O comportamento de nova tentativa é configurável por nó, no `data` do nó executor: | Configuração | Padrão | Limites | Descrição | | ----------------------- | -------------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------ | | `timeout_seconds` | 30 | 1–300 | Timeout por requisição. | | `retry.max_attempts` | 3 (1 para `POST` e `PATCH` sem configuração) | 1–10 aceitos; 1–5 efetivos | Aceita `1`–`10` no schema do nó, mas o Flowker limita a contagem efetiva de tentativas em runtime a `1`–`5`. | | `retry.backoff_seconds` | 1 | 1–60 | Primeiro teto de backoff; cada espera é um valor aleatório entre zero e o teto, que dobra a cada tentativa. | | `success_status_codes` | `[200, 201, 202, 204]` | 100–599 | Códigos de status HTTP tratados como sucesso. | As novas tentativas valem apenas quando a operação é segura de repetir. Por padrão, o Flowker trata chamadas `POST` e `PATCH` como não idempotentes e **não** as repete (uma única tentativa), enquanto `GET`, `PUT`, `DELETE` e outros verbos são repetidos normalmente. Um `retry.max_attempts` maior que `1` faz aquele nó aderir às novas tentativas seja qual for o método. Um `retry.max_attempts` de `1` não é uma adesão. Ele define uma única tentativa. **Erros que não permitem nova tentativa** vão direto para uma única tentativa, seja qual for a configuração. São eles: circuit breaker aberto, contexto cancelado, erros de configuração e falhas ao resolver secrets. Incluem também um corpo de requisição acima do limite de tamanho configurado, um corpo de resposta de provedor acima do mesmo limite e respostas `4xx` de provedor que não são transitórias. Isso significa qualquer `4xx` exceto `408` e `429`. A nova tentativa vale por execução de nó. Se todas as tentativas falham, a etapa falha e a execução para. ### Circuit breaker O Flowker usa um circuit breaker para que chamadas que falham repetidamente não sobrecarreguem serviços externos: | Parâmetro | Valor | | ------------------------ | ---------------------------------------------------------------- | | Limiar de falhas | 20 falhas consecutivas abrem o circuito (configurável no deploy) | | Timeout de recuperação | 30 segundos antes de tentar de novo (estado half-open) | | Requisições em half-open | 1 requisição permitida para testar se o serviço se recuperou | Erros `4xx` de cliente ou de autenticação do provedor **não** abrem o circuito: eles são problema de quem chama, não sinal de que o provedor está fora. Apenas falhas de transporte e `5xx` contam para o limiar. Quando o circuito está aberto, as chamadas de executor falham na hora com `FLK-0507` em vez de alcançar o serviço externo. Isso evita 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. Depois que o circuito alcança o limiar de falhas, ele passa para **Open** e bloqueia todas as requisições na hora. Depois de 30 segundos, ele vai para **Half-Open** e permite uma requisição de teste. Se essa requisição funciona, o circuito volta para Closed. Se falha, o circuito reabre por outro ciclo de 30 segundos. O circuit breaker opera por configuração de provedor, no escopo do seu tenant. Falhas contra uma conexão não afetam outra, e um tenant não pode abrir o circuito de outro. Os limiares do circuit breaker (contagem de falhas, timeout de recuperação) são padrões globais do deploy. Você não pode personalizá-los por conexão nesta versão. ## Registro de configurações de executor *** Este registro é um terceiro uso, separado, da palavra "executor". As entradas dele não são os executores de catálogo do [Passo 1](#step-1-explore-the-catalog). Não são os nós de workflow de `type: "executor"`, nem as configurações de provedor do [Passo 2](#step-2-create-a-provider-configuration). O motor lê as configurações de provedor para chamar serviços externos, não estas entradas, e o registro carrega o próprio vocabulário de campos (`baseUrl`, `endpoints`, `authentication`). O registro expõe quatro operações: | Operação | Endpoint | | --------- | ------------------------------------------------------------------------------------------- | | Listar | [`GET /v1/executors`](/pt/reference/products/flowker/list-executor-configurations) | | Obter | [`GET /v1/executors/{id}`](/pt/reference/products/flowker/get-executor-configuration) | | Atualizar | [`PATCH /v1/executors/{id}`](/pt/reference/products/flowker/update-executor-configuration) | | Apagar | [`DELETE /v1/executors/{id}`](/pt/reference/products/flowker/delete-executor-configuration) | Cada entrada carrega um `status`, que a API reporta em cada resposta: | Status | Descrição | | -------------- | -------------------------------------------- | | `unconfigured` | A entrada ainda não tem detalhes de conexão. | | `configured` | A entrada carrega detalhes de conexão. | | `tested` | A entrada foi verificada. | | `active` | A entrada está em serviço. | | `disabled` | A entrada está fora de serviço. | `PATCH` aceita `name`, `baseUrl`, `endpoints` e `authentication`, mais os opcionais `description` e `metadata`. Não aceita `status`, mas a operação de listar aceita `status` como filtro de query. A atualização vale para entradas em status `unconfigured` ou `configured`. A exclusão vale para entradas em status `unconfigured`, `configured` ou `disabled`. Nenhuma operação nesta versão move uma entrada para `tested`, `active` ou `disabled`. A tabela lista esses valores porque as respostas os reportam e o filtro da listagem os aceita. ## O que vem a seguir *** Entenda workflows, nós, arestas e execuções. Explore a API de configuração de provedor.