Guia de integração

O Flowker chama serviços externos (como motores anti-fraude, processadores de pagamento e providers KYC) através de configurações de provider. Uma configuração de provider é a sua conexão com uma instância ativa de um serviço externo. Neste guia, você vai explorar o catálogo, criar uma configuração de provider, referenciá-la a partir de um node de workflow, mapear campos entre os seus dados e o serviço, e entender como o Flowker repete e protege essas chamadas.

Passo 1: Explorar o catálogo

O catálogo é um registro somente leitura dos providers, executors do catálogo e triggers que vêm com o Flowker. Você os descobre; você nunca os cria.

Listar providers disponíveis

Chame o endpoint Listar providers do catálogo para ver os tipos de serviço aos quais 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 somente quando o registro de schemas nativos está configurado e a síntese é bem-sucedida.

Listar executors do catálogo disponíveis

Chame o endpoint Listar executors do catálogo para ver as operações que um node de workflow pode invocar. Use Listar executors por provider para restringir a lista a um único provider.

Listar triggers disponíveis

Chame o endpoint Listar triggers do catálogo para ver os tipos de trigger integrados: webhooks e schedules. A API de executar um workflow inicia um workflow, mas não é um trigger do catálogo.

Escolha o que você precisa

Anote o providerId e o id do executor do catálogo que correspondem à sua integração. Você usa o primeiro no Passo 2 e o segundo no Passo 3.

Pense no catálogo como um cardápio: ele mostra o que o Flowker pode chamar. As configurações de provider são os seus pedidos específicos — a URL base, as credenciais e os ajustes de cada instância de serviço que você usa.

Passo 2: Criar uma configuração de provider

Chame POST /v1/provider-configurations 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, ou envie `catalog`, para uma conexão a um provider do catálogo — o caso que este guia cobre. Envie `external_openapi` para uma conexão a um documento OpenAPI que você subiu; veja Conectando a sua própria API. Você escolhe o kind ao criar a configuração.
`providerId`	Para `catalog`	O provider do catálogo do qual esta conexão é uma instância, como `ledger` ou `http`. Uma configuração de kind `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 esse mapa contra o JSON Schema do provider no catálogo e retorna `422` quando não corresponde. O valor secreto dentro do bloco `auth` fica no seu backend de segredos, não no documento de configuração; todo o resto do mapa é armazenado junto 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 a lista vazia é rejeitada com `FLK-0323`. Os providers nativos aceitam uma lista vazia. Uma entrada com ponto inicial corresponde a subdomínios — `.kyc-provider.io` corresponde a `api.kyc-provider.io`. Apenas nomes de host: sem literais de IP, curingas ou portas. O host de `config.base_url` precisa estar coberto pela lista; caso contrário, a criação é rejeitada com `FLK-0320`.
`allowedPrivateHosts`	Não	Hosts privados nomeados que seu time de operações permite que esta configuração alcance. Endereços de metadados de nuvem e link-local continuam bloqueados.
`schemaBindings`	Não	Os schemas 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, até 500 caracteres.
`metadata`	Não	Seus próprios pares chave-valor.

Um providerId é um identificador do catálogo e nem sempre corresponde ao nome do produto. O Midaz está registrado como ledger. Sempre pegue o valor em Listar providers do catálogo em vez de deduzi-lo do nome do produto.

O providerId da configuração e o executorId do node que a usa precisam pertencer ao mesmo provider do catálogo. O conector HTTP genérico usa http nos dois. Um workflow que combina uma configuração de um provider com um executor de outro é rejeitado 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.

Exemplo de requisição

POST /v1/provider-configurations

{
  "name": "FraudShield Production",
  "description": "Serviço de pontuação de fraude em produção",
  "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 e o Passo 4 o colocam no providerConfigId do node que chama o serviço.

Autenticação

O bloco config.auth contém 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`	Token bearer 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`	OAuth 2.0 client credentials contra um token endpoint (sem descoberta OIDC).	`token_url`, `client_id`, `client_secret`, `scopes`
`hmac`	Assina cada requisição com um segredo HMAC compartilhado.	`secret`, `algorithm`, `encoding`, `header_name`, `signature_prefix`, `signing_string`, `timestamp_header`

Os campos secretos de config.auth são armazenados fora do documento de configuração persistido. Uma leitura autorizada da configuração do provedor pode resolver esses valores no vault e devolvê-los sem máscara; os campos não resolvidos permanecem mascarados. Conceda o acesso de leitura de acordo com isso. Qualquer outra coisa que você colocar no documento de configuração — um header, por exemplo — é armazenada junto com a configuração, e uma leitura pode devolvê-la. Coloque cada credencial em config.auth. Para rotacionar um segredo, 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 não mudar. Uma atualização que muda auth.type deve levar um valor para cada segredo 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 segredo, como de oidc_user para oidc_client_credentials, não precisa desse valor novamente.

Para integrações OAuth 2.0, use oidc_client_credentials. O Flowker cuida da obtenção e renovação de tokens automaticamente.

Exemplo — OIDC client credentials

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

Habilitar e desabilitar

As configurações de provider possuem dois status: active (em uso) e disabled (temporariamente offline). Elas são criadas com status active. Use Desabilitar configuração de provider para tirar uma conexão de serviço e Habilitar configuração de provider para trazê-la de volta. Consulte a API de Configurações de provider para a referência completa.

Passo 3: Referenciar a configuração de provider a partir de um node de workflow

Todo node executor carrega um providerConfigId — o identificador da configuração de provider pela qual ele chama. O Flowker rejeita um workflow cujo node executor não tem providerConfigId e rejeita um valor que não seja um UUID. Em tempo de execução, ele monta cada requisição de saída com a URL base dessa configuração de provider mais o path do node, e o node falha se a configuração de provider não estiver active. Estes são os campos que um node executor define no seu objeto data quando chama através do conector HTTP genérico:

Campo	Obrigatório	Descrição
`executorId`	Sim	O executor do catálogo que este node invoca, obtido no Passo 1. O Flowker rejeita o workflow quando o id não está no catálogo. Um node que chama um documento OpenAPI enviado o omite — veja abaixo.
`providerConfigId`	Sim	O UUID da configuração de provider pela qual este node chama.
`path`	Não	O path da requisição, acrescentado à URL base da configuração de provider. O host de destino é sempre essa URL base — um node não pode informar uma URL absoluta.
`endpointName`	Não	O mesmo segmento da requisição, informado por nome, usado quando o node não define `path`. Um node 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, combinados sobre os que a configuração de provider define. Um header do node vence um header de mesmo nome na configuração de provider.
`query`	Não	Parâmetros de consulta acrescentados à URL.
`auth`	Não	Um bloco de autenticação `{type, config}` para este node, no mesmo formato que a configuração de provider usa. Quando presente, tem precedência sobre a autenticação da configuração de provider.
`body`	Não	Um corpo de requisição explícito, resolvido contra o contexto do workflow. Quando definido, é a única origem do corpo — os mapeamentos de campos não se aplicam a ele.
`content_digest`	Não	Um pin SHA-256 para o corpo de requisição montado. Informe um digest hexadecimal de 64 caracteres ou um valor resolvido a partir do contexto do workflow. O Flowker calcula o hash dos bytes finais depois de montar o corpo e só envia a requisição quando eles correspondem.
`config`	Não	Valores literais fixos que alimentam o corpo da requisição. Consulte Mapeamento de campos e transformação de dados.
`inputMapping`, `outputMapping`, `transforms`	Não	Mapeamentos de campos e transformações. Consulte Mapeamento de campos e transformação de dados.
`timeout_seconds`, `retry`, `success_status_codes`	Não	Ajustes de resiliência por node. Consulte Retentativas e 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 node que chama uma operação de um documento OpenAPI enviado a nomeia com operation_path e operation_method em vez de um executorId. O Flowker preenche o executorId por você a partir da configuração de provider para a qual o node aponta. Conectando a sua própria API percorre todo esse caminho.

Validar a configuração de um node antes de salvar

Chame o endpoint Validar uma configuração de node (POST /v1/catalog/executors/{id}/validate) para conferir a configuração de um node contra o JSON Schema do executor do catálogo. Isso executa apenas a validação de JSON Schema — verifica se o seu objeto de configuração corresponde à estrutura que o executor do 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 executa o node. Passe mappedTargets para nomear os campos que o seu node fornece por um inputMapping em vez de um valor fixo. Esses campos contam como satisfeitos, então um node que mapeia um campo obrigatório vindo do trigger valida antes de você salvá-lo.

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. Um target de entrada é um caminho no corpo da requisição enviada, escrito exatamente como o serviço externo espera recebê-lo: não há objeto invólucro nem prefixo a acrescentar. Um source de saída é um caminho dentro do envelope de resposta, portanto os campos da resposta ficam sob body.

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

{
  "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 nodes seguintes leem a saída mapeada sob o ID deste node: ${executor-balance.balance}.

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. Trabalhando com os dados da requisição e da resposta percorre todo o caminho: declarar os mapeamentos, escolher o que monta o corpo da requisição, ajustar os valores em trânsito, ler a resposta de volta e conferir a requisição montada antes de chamar o serviço.

Passo 4: Executar o workflow

Referencie a configuração de provider em um node de workflow do tipo executor. O exemplo abaixo cria um workflow de validação de pagamento sobre a conexão FraudShield do Passo 2. Quando um pagamento chega, o Flowker chama o serviço 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 Ative-o e por fim Execute-o.

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

POST /v1/workflows

{
  "name": "payment-validation",
  "description": "Valida um pagamento antes de processá-lo.",
  "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 node check-fraud nomeia http — o conector HTTP genérico do catálogo — e a configuração FraudShield criada no Passo 2, que guarda a URL base e as credenciais. Os dois lados nomeiam o mesmo provider, então o workflow é salvo. O Flowker envia a requisição para https://api.fraudshield.example.com/score-transaction.O node não declara nenhum outputMapping, então a saída dele mantém o formato do envelope de resposta. Por isso o score fica em check-fraud.body.score, que é o que a condição de evaluate-score lê. Adicione um outputMapping quando preferir um nome mais plano — veja Mapeamento de campos e transformação de dados.

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 pelo endpoint Executar 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 nodes seguintes pelo namespace workflow — por exemplo, workflow.transactionId ou workflow.amount. As saídas dos nodes ficam disponíveis pelo ID do node — por exemplo, check-fraud.body.score para um node que não declara nenhum outputMapping.

Idempotência

Toda requisição de execução deve 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 execução e reutilize a mesma chave apenas ao repetir a requisição idêntica.

Triggers de webhook

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

Como funciona

Adicione um node trigger do tipo webhook ao seu workflow com um path e um method no seu data. Defina input_contract explicitamente em nodes novos quando precisar de validação open, xsd ou openapi.
Quando o workflow é ativado, o Flowker registra o path no 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 path para o workflow correspondente e o executa.

Definindo um node trigger de webhook

O trigger de webhook é um node com type: "trigger" e triggerType: "webhook" no seu data, mais um path, um method e um input_contract opcional. Configurando um trigger de webhook cobre cada campo, os três modos de input_contract e o que cada um exige, e traz um node de exemplo para cada modo. A configuração do trigger é um contrato fechado. Salvar um workflow cujo trigger de webhook omite path ou method, esquece um campo que o seu modo input_contract selecionado exige, nomeia o id de schema ou um campo de operação de outro modo, ou carrega uma chave ou um valor que o schema não aceita falha com FLK-0934. Uma declaração accepted_headers inválida falha em vez disso com FLK-0957. O schema também declara os campos opcionais response_mode, response_view e accepted_headers — consulte Configurando um trigger de webhook.

Protegendo um webhook

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

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 usado (ex: `POST`).
`_webhook.path`	O path de webhook resolvido.
`_webhook.headers`	Headers da requisição, filtrados por uma lista segura (`Content-Type`, `Accept`, `User-Agent`, `X-Request-Id`, `X-Forwarded-For`, `Idempotency-Key`) mais os `accepted_headers` opcionais deste trigger e, para uma rota `openapi`, os parâmetros header da operação. A lista de bloqueio fixa rejeita `Authorization`, `Proxy-Authorization`, `Cookie`, `Set-Cookie`, `X-API-Key` e `X-Auth-Token`. Os demais headers admitidos são persistidos sem alteração; nunca permita nomes que carreguem segredos, como `X-Amz-Security-Token`.
`_webhook.query`	Preserva os nomes dos parâmetros de consulta recebidos. Ele preserva os valores somente de `customerId`, `page`, `cursor`, `limit`, `offset` e `sortOrder` (sem diferenciar maiúsculas de minúsculas); todos os demais valores são armazenados como `[redacted]`.
`_webhook.remote_ip`	Endereço IP de quem chamou.

Esses metadados ficam disponíveis para todos os nodes do workflow pelo namespace workflow._webhook.

Notas importantes

Cada combinação de path + método de webhook só pode ser registrada por um workflow ativo. Ativar um segundo workflow com o mesmo path falha com um erro de conflito.
Os paths de webhook aceitam segmentos aninhados (ex: payments/stripe/received).
O tamanho máximo do corpo da requisição é 1 MB.
Desativar um workflow desregistra automaticamente as 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 async) — quem chama precisa consultar o status da execução separadamente. Defina response_mode como "sync" no data do node trigger para que o Flowker mantenha a conexão HTTP aberta e retorne o resultado da execução diretamente na resposta:

Campo	Tipo	Obrigatório	Descrição
`response_mode`	string	Não	`"async"` (padrão) retorna um recibo `202` imediatamente. `"sync"` bloqueia (até um limite interno) até a execução alcançar um estado terminal e retorna o resultado no corpo da resposta.
`response_view`	string	Não	Molda o corpo da resposta sync. Só faz sentido quando `response_mode` é `"sync"`. Consulte a tabela abaixo. O padrão é `"full"`.

Se a execução não alcançar um estado terminal antes de o limite interno de espera se esgotar, o Flowker recai no mesmo recibo 202 (com um header Location apontando para o endpoint de resultados) que o modo async teria retornado. response_view seleciona o formato do corpo da resposta sync:

Valor	Descrição
`full` (padrão)	O despejo completo da execução — `executionId`, `workflowId`, `status`, `stepResults`, `finalOutput` — o mesmo formato que você obteria do endpoint de resultados da execução.
`final_output`	Apenas o mapa `finalOutput` da execução, sem invólucro.
`receipt`	O recibo enxuto da execução (`executionId`, `workflowId`, `status`, `startedAt`) — o mesmo formato que o caminho async retorna.
`passthrough`	Molda a resposta pelo tipo de node do passo terminal (o último executado). Para um executor terminal que capturou uma resposta do provedor, retorna o status do provedor (incluindo `4xx`) e o `Content-Type`. Ele retransmite no máximo 8 KiB do corpo capturado; corpos maiores são truncados. Corpos JSON são decodificados e serializados novamente antes da captura, portanto não há garantia de retransmissão byte a byte. Se o passo terminal for uma ação `set_output` com uma saída configurada, a resposta é a saída de negócio desse node, respeitando o override `responseStatusCode`. Se nenhum dos dois se aplicar (nenhuma resposta do provider capturada — circuito aberto, timeout, falha antes do envio — e nenhuma saída terminal), recai no envelope completo com HTTP `200` para que quem chama ainda receba um resultado com sentido.

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 responseStatusCode (veja abaixo), o status HTTP sync permanece 200 para full/final_output/receipt (ele informa 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 visões. Um node action com actionType: "set_output" pode carregar um responseStatusCode opcional (inteiro, 200–599) para sobrescrever o status HTTP que uma resposta de webhook sync retorna. Um valor fora do intervalo ou não inteiro é rejeitado ao salvar (FLK-0122). Para passthrough, o override se aplica apenas quando o próprio node set_output é o passo terminal — o status repassado de um executor terminal sempre vence, e o fallback sem resposta sempre usa um 200 simples para que um override nunca mascare uma falha. A detecção de passthrough é estrita: só o passo terminal conta. Um set_output terminal depois de um executor é moldado pela sua própria saída — o Flowker nunca volta à resposta de um executor anterior. Em uma execução que falhou, o passo que interrompe o fluxo é o passo terminal, então um 4xx do provider que parou o workflow é repassado como o 4xx real. Os valores na saída de um node set_output aceitam referências ${...} resolvidas contra o contexto do workflow — incluindo ${workflow.<campo>} (payload do trigger), ${execution.id}, ${execution.startedAt} e ${execution.now} (marcado no momento da interpolação). Uma referência ${...} que não possa ser resolvida faz o passo falhar (fail-closed).

Tratamento de erros

Se um node falha, a execução para e é marcada como failed. Não há fallback automático. Depois de esgotadas as retentativas, a execução falha. Os resultados de execução informam o status da execução e stepResults. Uma etapa com falha fornece stepNumber, nodeId, status e errorMessage, com statusCode e errorClass quando disponíveis; output é opcional. Não prometa um errorCode, incluindo FLK-0504 ou FLK-0507, em todos os payloads de resultados de execução.

Retentativas e circuit breaker

O Flowker inclui resiliência integrada para as chamadas de executor.

Retentativas

Quando uma chamada de executor falha com um erro transitório — um erro de rede, um timeout na tentativa, qualquer status 5xx, ou os status 408 ou 429 — o Flowker repete automaticamente. O comportamento de retentativa é configurável por node, no data do node executor:

Ajuste	Padrão	Limites	Descrição
`timeout_seconds`	30	1–300	Timeout por requisição.
`retry.max_attempts`	3 (1 para `POST` e `PATCH` não configuradas)	1–10 aceitos; 1–5 efetivos	Aceita `1`–`10` no schema do node, mas o Flowker limita a quantidade efetiva de tentativas em tempo de execução a `1`–`5`.
`retry.backoff_seconds`	1	1–60	Teto do primeiro 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 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 repetidas (uma única tentativa), enquanto GET, PUT, DELETE e outros verbos repetem normalmente. Um retry.max_attempts maior que 1 ativa as retentativas naquele node seja qual for o método. Um retry.max_attempts igual a 1 não é uma ativação — ele define uma única tentativa. Erros não repetíveis se reduzem a uma única tentativa independentemente da configuração: circuit breaker aberto, contexto cancelado, erros de configuração, falhas ao resolver segredos, um corpo de requisição acima do teto de tamanho configurado, um corpo de resposta do provider acima do mesmo teto, e respostas 4xx não transitórias do provider (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 deploy)
Timeout de recuperação	30 segundos antes de tentar de novo (estado half-open)
Requisições half-open	1 requisição permitida para testar se o serviço se recuperou

Erros 4xx de cliente/autenticação do provider não abrem o circuito: são problema de quem chama, não sinal de que o provider está fora do ar. Apenas falhas de transporte e 5xx contam para o limiar. Quando o circuito está aberto, as chamadas de executor falham imediatamente 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 — 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 transita para Open, bloqueando todas as requisições imediatamente. Depois de 30 segundos, passa para Half-Open e permite uma requisição de teste. Se essa requisição tiver sucesso, o circuito volta para Closed. Se falhar, o circuito reabre por outro ciclo de 30 segundos.

O circuit breaker opera por configuração de provider, delimitado ao 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 (número de falhas, timeout de recuperação) são padrões globais configurados no deploy — eles não podem ser personalizados por conexão nesta versão.

Registro de configurações de executor

O Flowker mantém um registro de configurações de executor. O registro expõe quatro operações:

Operação	Endpoint
Listar	`GET /v1/executors`
Consultar	`GET /v1/executors/{id}`
Atualizar	`PATCH /v1/executors/{id}`
Remover	`DELETE /v1/executors/{id}`

Cada registro carrega um status, que a API informa em cada resposta:

Status	Descrição
`unconfigured`	O registro ainda não tem detalhes de conexão.
`configured`	O registro carrega detalhes de conexão.
`tested`	O registro foi verificado.
`active`	O registro está em serviço.
`disabled`	O registro está fora de serviço.

O PATCH aceita name, baseUrl, endpoints e authentication, mais os opcionais description e metadata. Ele não aceita status, mas a operação de listagem aceita status como filtro de consulta. A atualização se aplica a registros em status unconfigured ou configured; a remoção se aplica a registros em status unconfigured, configured ou disabled. Nenhuma operação nesta versão move um registro para tested, active ou disabled; a tabela lista esses valores porque as respostas os informam e o filtro de listagem os aceita.

Visão geral

Guias

Console

Operações

Guia de integração

Passo 1: Explorar o catálogo

Passo 2: Criar uma configuração de provider

Autenticação

Habilitar e desabilitar

Passo 3: Referenciar a configuração de provider a partir de um node de workflow

Validar a configuração de um node antes de salvar

Mapeamento de campos e transformação de dados

Passo 4: Executar o workflow

Disparando workflows

Idempotência

Triggers de webhook

Como funciona

Definindo um node trigger de webhook

Protegendo um webhook

Metadados do webhook

Notas importantes

Modo de resposta síncrona

Tratamento de erros

Retentativas e circuit breaker

Retentativas

Circuit breaker

Registro de configurações de executor

Próximos passos

Conceitos fundamentais

API de Configurações de provider

​Passo 1: Explorar o catálogo

​Passo 2: Criar uma configuração de provider

​Autenticação

​Habilitar e desabilitar

​Passo 3: Referenciar a configuração de provider a partir de um node de workflow

​Validar a configuração de um node antes de salvar

​Mapeamento de campos e transformação de dados

​Passo 4: Executar o workflow

​Disparando workflows

​Idempotência

​Triggers de webhook

​Como funciona

​Definindo um node trigger de webhook

​Protegendo um webhook

​Metadados do webhook

​Notas importantes

​Modo de resposta síncrona

​Tratamento de erros

​Retentativas e circuit breaker

​Retentativas

​Circuit breaker

​Registro de configurações de executor

​Próximos passos

Conceitos fundamentais

API de Configurações de provider

Passo 1: Explorar o catálogo

Passo 2: Criar uma configuração de provider

Autenticação

Habilitar e desabilitar

Passo 3: Referenciar a configuração de provider a partir de um node de workflow

Validar a configuração de um node antes de salvar

Mapeamento de campos e transformação de dados

Passo 4: Executar o workflow

Disparando workflows

Idempotência

Triggers de webhook

Como funciona

Definindo um node trigger de webhook

Protegendo um webhook

Metadados do webhook

Notas importantes

Modo de resposta síncrona

Tratamento de erros

Retentativas e circuit breaker

Retentativas

Circuit breaker

Registro de configurações de executor

Próximos passos