Guia de integração

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.

Liste os provedores disponíveis

Chame o endpoint Listar provedores do catálogo 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.

Liste os executores de catálogo disponíveis

Chame o endpoint Listar executores do catálogo para ver as operações que um nó de workflow pode invocar. Use Listar executores por provedor para estreitar a lista a um provedor.

Liste os gatilhos disponíveis

Chame o endpoint Listar gatilhos do catálogo 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.

Escolha o que você precisa

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

Exemplo de requisição

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 e o Passo 4 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.

Exemplo: client credentials OIDC

{
  "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 para tirar uma conexão de serviço e Habilitar configuração de provedor para trazê-la de volta. Veja a API de configurações de provedor 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. 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.
`inputMapping`, `outputMapping`, `transforms`	Não	Mapeamentos de campo e transformações. Veja Mapeamento de campos e transformação de dados.
`timeout_seconds`, `retry`, `success_status_codes`	Não	Configurações de resiliência por nó. Veja Novas tentativas 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 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 percorre esse caminho inteiro.

Valide a configuração de um nó antes de salvar

Chame o endpoint Validar a configuração de um nó (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.

Exemplo rápido: mapear campos de workflow para um nó 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 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 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. 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 para definir o workflow, depois Ative e por fim Execute.

Exemplo: criar um workflow de validação de pagamento

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.

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

Como disparar workflows

Você dispara execuções de workflow 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 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

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.
Quando você ativa o workflow, o Flowker registra o caminho 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 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 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.

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 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.<field>} (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 — Transições de estado 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. Não são os nós de workflow de type: "executor", nem as configurações de provedor do Passo 2. 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`
Obter	`GET /v1/executors/{id}`
Atualizar	`PATCH /v1/executors/{id}`
Apagar	`DELETE /v1/executors/{id}`

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.

Visão geral

Guias

Console

Operações

Guia de integração

Passo 1: Explore o catálogo

Passo 2: Crie uma configuração de provedor

Autenticação

Como habilitar e desabilitar

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

Valide a configuração de um nó antes de salvar

Mapeamento de campos e transformação de dados

Passo 4: Rode o workflow

Como disparar workflows

Idempotência

Gatilhos de webhook

Como funciona

Como definir um nó de gatilho de webhook

Como proteger um webhook

Metadados do webhook

Notas importantes

Modo de resposta síncrona

Tratamento de erros

Novas tentativas e circuit breaker

Novas tentativas

Circuit breaker

Registro de configurações de executor

O que vem a seguir

Conceitos centrais

API de configurações de provedor

​Passo 1: Explore o catálogo

​Passo 2: Crie uma configuração de provedor

​Autenticação

​Como habilitar e desabilitar

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

​Valide a configuração de um nó antes de salvar

​Mapeamento de campos e transformação de dados

​Passo 4: Rode o workflow

​Como disparar workflows

​Idempotência

​Gatilhos de webhook

​Como funciona

​Como definir um nó de gatilho de webhook

​Como proteger um webhook

​Metadados do webhook

​Notas importantes

​Modo de resposta síncrona

​Tratamento de erros

​Novas tentativas e circuit breaker

​Novas tentativas

​Circuit breaker

​Registro de configurações de executor

​O que vem a seguir

Conceitos centrais

API de configurações de provedor

Passo 1: Explore o catálogo

Passo 2: Crie uma configuração de provedor

Autenticação

Como habilitar e desabilitar

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

Valide a configuração de um nó antes de salvar

Mapeamento de campos e transformação de dados

Passo 4: Rode o workflow

Como disparar workflows

Idempotência

Gatilhos de webhook

Como funciona

Como definir um nó de gatilho de webhook

Como proteger um webhook

Metadados do webhook

Notas importantes

Modo de resposta síncrona

Tratamento de erros

Novas tentativas e circuit breaker

Novas tentativas

Circuit breaker

Registro de configurações de executor

O que vem a seguir