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

# Conceitos centrais

> Entenda os blocos de construção do Flowker: workflows, nós, arestas, catálogo, configurações de provedor, templates, execuções e dashboard.

O Flowker é construído sobre um conjunto de conceitos interligados. A última seção desta página mostra como tudo se conecta.

## Workflows

***

Um workflow é a definição de um processo de negócio, a sequência de etapas que o Flowker segue para concluir uma operação.

Os workflows passam por um ciclo de vida:

| Status     | Descrição                                       |
| ---------- | ----------------------------------------------- |
| `draft`    | Criado e editável. Ainda não pode rodar.        |
| `active`   | Pronto para executar. A estrutura está travada. |
| `inactive` | Desativado. Nenhuma nova execução é aceita.     |

Para mover um workflow entre estados, use os endpoints [ativar](/pt/reference/products/flowker/activate-workflow), [desativar](/pt/reference/products/flowker/deactivate-workflow) e [mover para rascunho](/pt/reference/products/flowker/move-workflow-to-draft).

## Nós e arestas

***

Os nós são as etapas individuais de um workflow, ou **tarefas** em termos de negócio. Cada nó é uma unidade de trabalho: receber um evento, chamar um serviço, avaliar uma condição ou fazer uma ação.

O Flowker tem quatro tipos de nó:

| Tipo          | Objetivo                                                                                      | Quando usar                                                        |
| ------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `trigger`     | Ponto de entrada do workflow                                                                  | Sempre o primeiro nó. Começa a execução quando um evento acontece. |
| `executor`    | Chama um serviço externo por uma configuração de provedor                                     | Quando você precisa chamar uma API ou integração externa.          |
| `conditional` | Ramifica a execução com base em condições                                                     | Quando a próxima etapa depende do resultado de uma anterior.       |
| `action`      | Faz uma ação embutida; o tipo disponível é `set_output`, que define a saída final da execução | Para definir a saída final do workflow sem uma chamada externa.    |

As **arestas** conectam os nós e definem a ordem de execução. A ramificação fica no nó condicional, não na aresta: o nó condicional avalia a condição dele e produz um handle de resultado, e o Flowker segue a única aresta de saída cujo `sourceHandle` corresponde a esse handle. Todos os outros tipos de nó seguem todas as arestas de saída deles.

## Catálogo

***

O catálogo é o registro somente leitura de todos os provedores, executores e gatilhos embutidos disponíveis no Flowker. Você não pode criar nem alterar entradas do catálogo. Você as descobre.

Antes de configurar qualquer integração, navegue pelo catálogo para ver o que já está disponível:

* Os **executores de catálogo** são os componentes embutidos que um nó de workflow invoca. Eles incluem o conector HTTP genérico e as operações de provedores nativos como o ledger do Midaz e o Tracer.
* Os **gatilhos** definem os tipos de evento que podem iniciar um workflow (por exemplo, webhooks).

Use estes endpoints para explorar o que está disponível:

* [Listar executores do catálogo](/pt/reference/products/flowker/list-catalog-executors) e [Listar gatilhos do catálogo](/pt/reference/products/flowker/list-catalog-triggers) para descobrir os tipos de executor e de gatilho.
* [Listar provedores do catálogo](/pt/reference/products/flowker/list-catalog-providers) (`GET /v1/catalog/providers`) para listar todos os provedores disponíveis.
* [Obter provedor do catálogo](/pt/reference/products/flowker/get-catalog-provider) (`GET /v1/catalog/providers/{id}`) para ver os detalhes de um provedor específico.
* [Listar executores por provedor](/pt/reference/products/flowker/list-executors-by-provider) (`GET /v1/catalog/providers/{id}/executors`) para listar os executores disponíveis em um provedor específico.

## Configurações de provedor

***

Uma **configuração de provedor** é a sua conexão com uma instância ativa de um serviço externo. É o objeto para o qual um nó de workflow aponta, e o objeto que o Flowker lê quando esse nó roda.

O Flowker separa o tipo de serviço da sua conexão com ele:

| Conceito                     | O que é                                                                             | Natureza                            |
| ---------------------------- | ----------------------------------------------------------------------------------- | ----------------------------------- |
| **Provedor**                 | Um tipo de serviço externo (por exemplo, Midaz, Tracer, um endpoint HTTP genérico). | Estático — publicado no catálogo.   |
| **Configuração de provedor** | A sua conexão com uma instância desse provedor.                                     | Dinâmico — você as cria e gerencia. |

Cada configuração de provedor guarda:

* **`config`**: os dados de conexão daquela instância, como a URL base e as credenciais de autenticação. Para a espécie padrão `catalog`, o Flowker valida esse mapa contra o JSON Schema do provedor de catálogo. Para `external_openapi`, ele usa um validador de configuração de OpenAPI externo. As folhas sensíveis reconhecidas são gravadas no backend de segredos e substituídas por `secretRef`. Configurações antigas sem `secretRef` podem conter valores inline.
* **`allowedHosts`**: os hosts públicos que esta configuração pode chamar.
* **`allowedPrivateHosts`**: hosts privados nomeados que o seu time de operações permite que esta configuração alcance. Ele levanta apenas a restrição do Flowker a endereços privados ou de loopback: se `allowedHosts` não estiver vazia, ela também deve incluir o host. Metadados de cloud e endereços link-local seguem bloqueados.
* **`schemaBindings`**: os schemas XSD ou OpenAPI vinculados a esta configuração, cada um com uma restrição opcional a operações OpenAPI específicas.

Uma configuração também carrega um **`kind`**. Os valores aceitos são `catalog` (o padrão), que conecta a um provedor do catálogo, e `external_openapi`, que conecta a um documento OpenAPI que você mesmo subiu, para que um nó de workflow chame as operações da sua própria API. Veja [Conectar a sua própria API](/pt/products/flowker/connecting-your-own-api).

As configurações de provedor têm dois status: `active` (em uso) e `disabled` (temporariamente fora do ar). 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.

### Como um workflow chega até ela

Cada nó de executor pode carregar um `providerConfigId`, o identificador da configuração de provedor pela qual ele chama. Em tempo de execução, o Flowker monta cada requisição de saída com a URL base dessa configuração de provedor mais o caminho definido no nó, e o nó falha se a configuração de provedor não estiver `active`.

Use os endpoints de [Configurações de provedor](/pt/reference/products/flowker/list-provider-configurations) para criar, ler, atualizar, desabilitar, habilitar e excluir as suas conexões.

## Registro de configurações de executor

***

O Flowker mantém um registro com os cadastros de configuração de executor. 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)  |
| Excluir   | [`DELETE /v1/executors/{id}`](/pt/reference/products/flowker/delete-executor-configuration) |

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

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

O corpo da atualização não inclui `status`, mas a operação de listagem o aceita como filtro de consulta. A atualização vale para cadastros no status `unconfigured` ou `configured`. A exclusão vale para cadastros no status `unconfigured`, `configured` ou `disabled`. Nenhuma operação desta versão move um cadastro para `tested`, `active` ou `disabled`. A tabela lista esses valores porque as respostas os informam e o filtro da listagem os aceita.

## Templates

***

Os templates de workflow são padrões de workflow prontos publicados no catálogo. Cada template descreve um padrão de integração conhecido e os parâmetros que esse padrão espera.

O catálogo traz o template `tracer-midaz-validation` ("Tracer Validation + Midaz Transaction"): ele recebe uma requisição de webhook, valida a transação pelo Tracer e cria a transação no Midaz quando o Tracer a aprova.

Cada template tem um schema de parâmetros que define quais entradas ele espera (por exemplo, qual configuração de provedor usar, valores de limiar). Quando o Flowker consegue recuperar as configurações de provedor ativas, ele enriquece os campos de parâmetro referenciados com opções selecionáveis. Se a consulta não estiver disponível ou falhar, ele devolve o schema original.

Para inspecionar um template:

1. [Liste os templates do catálogo](/pt/reference/products/flowker/list-catalog-templates).
2. [Obtenha o detalhe do template](/pt/reference/products/flowker/get-catalog-template) para ver o schema de parâmetros dele.
3. [Valide um conjunto de parâmetros](/pt/reference/products/flowker/validate-catalog-template-params) contra esse schema.

## Execuções

***

Uma execução é uma instância em tempo de execução de um workflow. Um gatilho normalmente inicia uma nova execução. Uma nova tentativa que reutiliza uma chave de idempotência existente devolve a execução já existente em vez de criar outra.

Cada execução acompanha:

* `executionId`: identificador único desta rodada.
* `status`: estado atual (`pending`, `running`, `completed` ou `failed`).
* `stepResults`: a saída de cada nó de executor, condicional ou ação executado, em ordem. Os nós de gatilho começam o percurso do grafo e não criam registros de etapa de execução.
* `finalOutput`: o valor final gravado para a execução. Quando uma ação `set_output` produz um objeto, o Flowker usa esse objeto. Caso contrário, o Flowker devolve o contexto acumulado do workflow.

Use [Obter status da execução](/pt/reference/products/flowker/get-execution-status) para acompanhar o progresso e [Obter resultados da execução](/pt/reference/products/flowker/get-execution-results) para recuperar a saída completa.

<Note>
  O endpoint de status devolve o registro da execução, com o status atual dele. O endpoint dedicado de resultados ([`GET /v1/executions/{id}/results`](/pt/reference/products/flowker/get-execution-results)) devolve `status`, `stepResults` e `finalOutput` quando presentes. Uma etapa com falha pode incluir `errorMessage`. Esta resposta não tem campo de detalhes de erro no nível superior.
</Note>

## Idempotência

***

As requisições de execução direta exigem uma string `Idempotency-Key` não vazia. O Flowker não impõe o formato UUID. O header do webhook é opcional.

Se o Flowker recebe uma segunda requisição com a mesma `Idempotency-Key`, ele devolve a execução já existente em vez de criar outra. Uma repetição direta devolve HTTP `200` e inclui `idempotencyReplayed` na resposta.

```
Idempotency-Key: 7f3e1a2b-4c5d-6e7f-8a9b-0c1d2e3f4a5b
```

Use uma chave nova quando você quer de propósito uma nova execução. Reutilize a mesma chave apenas ao repetir exatamente a mesma requisição.

## Dashboard

***

A API do Dashboard fornece resumos agregados dos seus workflows e execuções. Use-a sempre que você precisar de uma visão geral da saúde do sistema sem consultar execuções individuais.

* [Resumo de workflows](/pt/reference/products/flowker/get-dashboard-workflow-summary) devolve os totais e a divisão por status (draft, active, inactive).
* [Resumo de execuções](/pt/reference/products/flowker/get-dashboard-execution-summary) devolve os totais e a divisão por status, com filtros opcionais de intervalo de tempo e de status.

Exemplo de resposta de [`GET /v1/dashboards/executions`](/pt/reference/products/flowker/get-dashboard-execution-summary):

```json theme={null}
{
  "total": 12847,
  "completed": 11903,
  "failed": 712,
  "pending": 130,
  "running": 102
}
```

Casos de uso comuns:

* **Monitorar a saúde das execuções**: acompanhe as taxas de conclusão e de falha ao longo do tempo para notar cedo uma degradação.
* **Montar páginas de status**: mostre o throughput dos workflows e as métricas de sucesso em dashboards internos ou voltados ao cliente.
* **Alertar em picos de taxa de falha**: compare `failed / total` com um limiar para disparar alertas antes que os problemas se espalhem.

## Como tudo se encaixa

***

Os conceitos do Flowker se apoiam uns nos outros em uma sequência clara:

1. **Explore o catálogo** para descobrir os provedores, os executores de catálogo, os gatilhos e os templates disponíveis.
2. **Crie configurações de provedor** para conectar o Flowker a instâncias ativas de serviços externos.
3. **Defina workflows**: cada nó de executor nomeia um executor de catálogo e a configuração de provedor pela qual ele chama.
4. **Execute workflows** para rodar o seu processo de negócio e recuperar os resultados.
5. **Monitore**: use o dashboard para os resumos operacionais e a API de execuções para o detalhe por etapa.

Siga o [guia de primeiros passos](/pt/products/flowker/flowker-getting-started) para rodar o seu primeiro workflow de ponta a ponta.