> ## 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 fundamentais > Entenda os componentes do Flowker: workflows, nós, edges, catálogo, configurações de provedor, templates, execuções, dashboard e auditoria. O Flowker é construído em torno de um conjunto de conceitos interconectados. Entender como eles se relacionam ajuda você a projetar, configurar e executar workflows com eficiência. O diagrama ao final desta página mostra como tudo se encaixa. ## Workflows *** Um workflow é a definição de um processo de negócio — a sequência de passos que o Flowker segue para concluir uma operação. Todo workflow possui um ciclo de vida com três estados possíveis: | Status | Descrição | | ---------- | ------------------------------------------------- | | `draft` | Criado e editável. Ainda não pode ser executado. | | `active` | Pronto para execução. A estrutura está bloqueada. | | `inactive` | Desativado. Novas execuções não são aceitas. | Para alterar o estado de um workflow, use os endpoints [ativar](/pt/reference/flowker/activate-workflow), [desativar](/pt/reference/flowker/deactivate-workflow) e [mover para draft](/pt/reference/flowker/move-workflow-to-draft). ## Nodes e edges *** Os nodes são os passos individuais de um workflow — o que em termos de negócio você chamaria de **tarefas**. Cada node é uma unidade de trabalho: receber um evento, chamar um serviço, avaliar uma condição ou executar uma ação. O Flowker suporta quatro tipos de node: | Tipo | Propósito | Quando usar | | ------------- | ---------------------------------------------------- | ------------------------------------------------------------------ | | `trigger` | Ponto de entrada do workflow | Sempre o primeiro node. Inicia a execução quando um evento ocorre. | | `executor` | Chama um serviço externo via um executor configurado | Quando você precisa chamar uma API ou integração externa. | | `conditional` | Bifurca a execução com base em condições | Quando o próximo passo depende do resultado do anterior. | | `action` | Executa uma ação integrada (log, transform, etc.) | Para operações nativas que não requerem chamadas externas. | Os **edges** conectam nodes e definem a ordem de execução. Um edge pode ter uma condição — o próximo node só é executado se a condição for verdadeira. ## Catálogo *** O catálogo é o registro somente leitura de todos os providers, executors e triggers integrados disponíveis no Flowker. Você não pode criar ou modificar entradas do catálogo — apenas descobri-las. Antes de configurar qualquer integração, explore o catálogo para ver o que está disponível: * Os **executors** são as capacidades específicas que você pode invocar em um node (ex: requisições HTTP, transformações de dados). * Os **triggers** definem os tipos de eventos que podem iniciar um workflow (ex: webhooks). Use estes endpoints para explorar o que está disponível: * [Listar executors do catálogo](/pt/reference/flowker/list-catalog-executors) e [Listar triggers do catálogo](/pt/reference/flowker/list-catalog-triggers) para descobrir tipos de executor e trigger. * [Listar providers do catálogo](/pt/reference/flowker/list-catalog-providers) (`GET /v1/catalog/providers`) para listar todos os providers disponíveis. * [Consultar provider do catálogo](/pt/reference/flowker/get-catalog-provider) (`GET /v1/catalog/providers/{id}`) para obter detalhes de um provider específico. * [Listar executors por provider](/pt/reference/flowker/list-executors-by-provider) (`GET /v1/catalog/providers/{id}/executors`) para listar os executors disponíveis para um provider específico. ## Configurações *** Antes de usar um executor em um workflow, você precisa configurá-lo. Uma **configuração de executor** define como o Flowker se conecta a um serviço externo — incluindo a URL base, as credenciais de autenticação e os endpoints HTTP específicos a chamar. As configurações de executor passam por um ciclo de vida: | Status | Descrição | | -------------- | --------------------------------------------------------- | | `unconfigured` | Criada mas ainda não configurada com detalhes de conexão. | | `configured` | Detalhes de conexão fornecidos, pronta para testar. | | `tested` | Teste de conectividade bem-sucedido. | | `active` | Pronta para ser usada em execuções de workflows. | | `disabled` | Temporariamente fora de serviço. | Use os endpoints de [Configurações de executor](/pt/reference/flowker/list-executor-configurations) para configurar e gerenciar suas integrações. ## Configurações de provider *** O Flowker usa um modelo de três camadas para integrações externas: | Camada | O que é | Natureza | | ---------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------- | | **Provider** | Um tipo de serviço externo (ex: Midaz, Tracer). | Estático — definido no catálogo. | | **Configuração de Provider** | Uma instância configurada de um provider com credenciais e URL base. | Dinâmica — você cria e gerencia. | | **Configuração de Executor** | Uma operação específica em um provider, com endpoints e mapeamentos de campos. | Dinâmica — referencia uma configuração de provider. | Uma **configuração de provider** conecta o Flowker a uma instância ativa de um serviço externo. Você fornece a URL base, as credenciais de autenticação e quaisquer configurações específicas do provider. A configuração é validada contra o JSON Schema do provider no catálogo. As configurações de provider possuem dois status: `active` (em uso) e `disabled` (temporariamente offline). Você pode [testar a conectividade](/pt/reference/flowker/test-provider-configuration) a qualquer momento para verificar se a conexão está funcionando. Use os endpoints de [Configurações de provider](/pt/reference/flowker/list-provider-configurations) para criar, gerenciar e testar suas conexões com providers. ## Templates *** Templates de workflow são padrões pré-construídos disponíveis no catálogo. Em vez de definir um workflow do zero, você pode selecionar um template, preencher seus parâmetros e criar um workflow pronto para uso em segundos. Cada template possui um schema de parâmetros que define quais entradas ele espera (ex: qual configuração de provider usar, valores de limiar). Quando você consulta um template, o schema é **dinamicamente enriquecido** — campos que referenciam configurações de provider são populados com suas configurações ativas, para que você possa escolher de uma lista em vez de inserir UUIDs manualmente. Para usar um template: 1. [Navegue pelos templates disponíveis](/pt/reference/flowker/list-catalog-templates) no catálogo. 2. [Consulte o detalhe do template](/pt/reference/flowker/get-catalog-template) para ver seu schema de parâmetros. 3. Opcionalmente [valide seus parâmetros](/pt/reference/flowker/validate-catalog-template-params) antes de criar. 4. [Crie um workflow a partir do template](/pt/reference/flowker/create-workflow-from-template). O workflow resultante é criado com status `draft`, para que você possa revisá-lo e ajustá-lo antes de ativar. ## Execuções *** Uma execução é uma instância em tempo de execução de um workflow. Cada vez que você dispara um workflow, o Flowker cria uma nova execução e processa seus nodes em ordem. Cada execução registra: * `executionId` — Identificador único desta execução. * `status` — Estado atual: `pending`, `running`, `completed` ou `failed`. * `stepResults` — A saída de cada node executado, em ordem. * `finalOutput` — O resultado agregado de toda a execução. Use [Consultar status da execução](/pt/reference/flowker/get-execution-status) para monitorar o progresso e [Consultar resultados da execução](/pt/reference/flowker/get-execution-results) para obter a saída completa. O endpoint principal de status ([`GET /v1/executions/{id}`](/pt/reference/flowker/get-execution-status)) retorna `executionId`, `workflowId`, `status`, `currentStepNumber`, `totalSteps`, `startedAt`, `completedAt` e `errorMessage`. Os campos `stepResults` e `finalOutput` só estão disponíveis pelo endpoint dedicado de resultados ([`GET /v1/executions/{id}/results`](/pt/reference/flowker/get-execution-results)). ## Idempotência *** Toda requisição de execução requer o header `Idempotency-Key`. É um UUID que você gera e envia com cada requisição para identificá-la de forma única. Se o Flowker receber uma segunda requisição com o mesmo `Idempotency-Key`, ele retorna a resposta original em vez de criar uma nova execução. Isso torna as retentativas seguras — falhas de rede e timeouts não resultarão em execuções duplicadas. ``` Idempotency-Key: 7f3e1a2b-4c5d-6e7f-8a9b-0c1d2e3f4a5b ``` Use sempre um UUID novo para cada nova execução. Reutilize a mesma chave apenas ao reenviar exatamente a mesma requisição. ## Dashboard *** A API de Dashboard fornece resumos agregados dos seus workflows e execuções — útil para construir dashboards operacionais e ferramentas de monitoramento. Use-a sempre que precisar de uma visão de alto nível da saúde do sistema sem consultar execuções individuais. * [Resumo de workflows](/pt/reference/flowker/get-dashboard-workflow-summary) retorna totais e detalhamentos por status (draft, active, inactive). * [Resumo de execuções](/pt/reference/flowker/get-dashboard-execution-summary) retorna totais e detalhamentos por status, com filtros opcionais de intervalo de tempo e status. Exemplo de resposta de [`GET /v1/dashboards/executions`](/pt/reference/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 falha ao longo do tempo para identificar degradações precocemente. * **Construir páginas de status** — exiba métricas de throughput e sucesso dos workflows em dashboards internos ou voltados ao cliente. * **Alertar sobre picos de taxa de falha** — compare `failed / total` com um limiar para disparar alertas antes que problemas se propaguem. ## Auditoria e conformidade *** O Flowker registra automaticamente uma trilha de auditoria imutável para cada ação significativa — criação de workflows, mudanças de status, inícios e conclusões de execuções, chamadas a executors e alterações de configuração. Você não precisa habilitar ou configurar nada; o registro de auditoria acontece internamente. Propriedades-chave do sistema de auditoria: * **Imutável** — os registros de auditoria são somente-adição e não podem ser modificados ou excluídos. * **Integridade por cadeia de hash** — cada entrada inclui um hash criptográfico que a vincula à entrada anterior, tornando adulterações detectáveis. * **Busca flexível** — use [Buscar eventos de auditoria](/pt/reference/flowker/search-audit-events) para consultar eventos por tipo, ação, resultado, recurso ou intervalo de datas. * **Verificação da cadeia** — use [Verificar cadeia de hash](/pt/reference/flowker/verify-audit-hash-chain) para confirmar que a trilha de auditoria não sofreu adulteração. ## Como tudo se encaixa *** Os conceitos do Flowker se constroem uns sobre os outros em uma sequência clara: 1. **Explore o catálogo** para descobrir providers, executors, triggers e templates disponíveis. 2. **Configure providers** para conectar o Flowker a instâncias ativas de serviços externos. 3. **Configure executors** para definir as operações e endpoints específicos que seu workflow precisa. 4. **Defina workflows** — do zero ou a partir de um template — referenciando suas configurações de executor. 5. **Execute workflows** para rodar seu processo de negócio e obter resultados. 6. **Monitore e audite** — use o dashboard para resumos operacionais e a API de auditoria para conformidade. Pronto para ver isso na prática? Siga o [guia de primeiros passos](/pt/flowker/flowker-getting-started) para executar seu primeiro workflow do início ao fim.