> ## 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. # Primeiros passos com o Flowker **Este guia é destinado a desenvolvedores.** Se você está procurando uma visão geral de nível de negócio sobre o que o Flowker faz, veja [O que é o Flowker?](/pt/flowker/what-is-flowker). O Flowker é um motor de orquestração de workflows projetado para modelar, executar e escalar processos de negócio com precisão. Neste guia, você vai rodar o Flowker localmente e executar seu primeiro workflow — da criação à obtenção dos resultados. Ao final, você terá um ambiente funcional para validar fluxos de automação e integrá-los aos seus sistemas. ## Pré-requisitos *** Antes de começar, verifique se o seu ambiente está pronto: | Ferramenta | Versão mínima | Comando de verificação | | -------------- | ------------- | ------------------------ | | Go | 1.22+ | `go version` | | Docker | 24+ | `docker --version` | | Docker Compose | 2.20+ | `docker compose version` | | Make | Instalado | `make --version` | O Flowker roda localmente usando Docker para seu banco de dados (MongoDB). Nenhuma infraestrutura externa é necessária para este guia. ## Passo 1: Obtenha o Flowker e configure o projeto *** O Flowker está disponível para clientes licenciados; seu repositório é mantido internamente. Os passos a seguir presumem que você já tem acesso aos arquivos do projeto Flowker necessários. Com acesso aos arquivos do projeto, navegue até o diretório Flowker e prepare o ambiente de desenvolvimento: ```bash theme={null} cd flowker ``` Instale as ferramentas de desenvolvimento e crie o arquivo de ambiente: ```bash theme={null} make dev-setup ``` Em seguida, inicie a stack local (MongoDB + Flowker na porta 4021): ```bash theme={null} make dev ``` Quando a saída mostrar que o servidor está rodando, o Flowker estará disponível em `http://localhost:4021`. O comando `make dev` inicia o MongoDB, gera a documentação da API e executa o Flowker com a autenticação por API key desabilitada — para que você possa testar livremente durante o desenvolvimento. ## Passo 2: Crie seu primeiro workflow *** Workflows definem como o seu processo de negócio se comporta — quais passos são executados, em qual ordem e sob quais condições. Cada workflow é composto por **nodes** (os passos) e **edges** (as conexões entre eles). Crie um workflow com um trigger de webhook e uma ação de log: ```bash theme={null} curl -s -X POST http://localhost:4021/v1/workflows \ -H "Content-Type: application/json" \ -d '{ "name": "meu-primeiro-workflow", "description": "Um workflow simples com um trigger e uma ação.", "nodes": [ { "id": "trigger-1", "type": "trigger", "name": "Início", "position": { "x": 0, "y": 0 }, "data": { "triggerId": "webhook" } }, { "id": "log-event", "type": "action", "name": "Registrar evento", "position": { "x": 200, "y": 0 }, "data": { "action": "log" } } ], "edges": [ { "id": "e1", "source": "trigger-1", "target": "log-event" } ] }' | jq . ``` A resposta confirma que o workflow foi criado com status `draft`: ```json theme={null} { "id": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a", "name": "meu-primeiro-workflow", "status": "draft" } ``` Guarde o valor do `id` — você vai precisar dele nos próximos passos. Novos workflows são sempre criados com status `draft`. Um workflow precisa ter pelo menos um node. No Flowker, os **nodes** representam os passos individuais do seu workflow — o que em termos de negócio você chamaria de tarefas. Os **edges** definem a ordem em que esses passos são executados. ## Passo 3: Ative o workflow *** Um workflow precisa ser ativado antes de poder ser executado. Isso transiciona o workflow de `draft` para `active`. ```bash theme={null} curl -s -X POST http://localhost:4021/v1/workflows/019c96a0-0ac0-7de9-9f53-9cf842a2ee5a/activate \ -H "Content-Type: application/json" | jq . ``` Uma vez ativado, a estrutura do workflow fica bloqueada e não pode ser editada diretamente. Para fazer alterações, clone o workflow, modifique o clone e ative a nova versão. ## Passo 4: Execute o workflow *** Dispare a execução de um workflow enviando dados de entrada. O header `Idempotency-Key` é obrigatório para garantir retentativas seguras. ```bash theme={null} curl -s -X POST http://localhost:4021/v1/workflows/019c96a0-0ac0-7de9-9f53-9cf842a2ee5a/executions \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 7f3e1a2b-4c5d-6e7f-8a9b-0c1d2e3f4a5b" \ -d '{ "inputData": { "message": "olá do meu primeiro workflow" } }' | jq . ``` A resposta retorna um `executionId` e um `status` de `running`: ```json theme={null} { "executionId": "019c96a0-10ce-75fc-a273-dc799079a99c", "workflowId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a", "status": "running", "startedAt": "2026-03-18T14:35:00Z" } ``` Guarde o `executionId` para o próximo passo. O header `Idempotency-Key` é obrigatório. Use um UUID único por requisição para evitar execuções duplicadas em caso de reenvio. ## Passo 5: Consulte os resultados *** Obtenha o resultado de uma execução do workflow: ```bash theme={null} curl -s http://localhost:4021/v1/executions/019c96a0-10ce-75fc-a273-dc799079a99c/results | jq . ``` A resposta inclui o status de cada passo e a saída final: ```json theme={null} { "executionId": "019c96a0-10ce-75fc-a273-dc799079a99c", "workflowId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a", "status": "completed", "stepResults": [ { "stepNumber": 1, "stepName": "action_log-event", "nodeId": "log-event", "status": "completed", "output": { "action": "log" }, "executedAt": "2026-03-18T14:35:00Z", "durationMs": 12 } ], "finalOutput": { "workflow": { "message": "olá do meu primeiro workflow" } }, "startedAt": "2026-03-18T14:35:00Z", "completedAt": "2026-03-18T14:35:00Z" } ``` Se a execução ainda estiver em andamento, este endpoint retorna um status `422`. Consulte `/v1/executions/{executionId}` para verificar o status atual antes de solicitar os resultados. ## Explore a API localmente *** O Flowker fornece uma interface interativa Swagger UI para testes e exploração: [http://localhost:4021/swagger/index.html](http://localhost:4021/swagger/index.html) Use-a para: * Inspecionar todos os endpoints disponíveis * Testar requisições de forma interativa * Entender as estruturas de request e response ## Uma nota sobre autenticação *** No ambiente de desenvolvimento local (`make dev`), a autenticação por API key está desabilitada por padrão. Em staging, produção ou qualquer ambiente configurado, todos os endpoints `/v1/*` exigem o header `X-API-Key`: ```bash theme={null} curl -H "X-API-Key: sua-api-key" http://seu-host-flowker/v1/workflows ``` ## Próximos passos *** Você agora tem um ambiente Flowker funcional e já executou seu primeiro workflow. A partir daqui, você pode: * **Modelar processos de negócio reais** usando diferentes tipos de nodes: `trigger`, `executor`, `conditional` e `action` * **Integrar sistemas externos** via configurações de executor (conecte-se a provedores de KYC, engines de fraude, serviços de pagamento) * **Projetar fluxos condicionais** com edges que avaliam expressões baseadas nas saídas dos passos * **Monitorar execuções** usando os endpoints de status e resultados de execução O Flowker foi projetado para evoluir de fluxos simples para orquestração em nível de produção sem alterar o modelo base.