> ## 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 > Rode o Flowker localmente, crie seu primeiro workflow, execute-o e recupere os resultados. Um início rápido prático para desenvolvedores que usam o mecanismo de orquestração. **Este guia é para desenvolvedores.** Se você está procurando uma visão geral de negócio do que o Flowker faz, veja [O que é o Flowker?](/pt/products/flowker/what-is-flowker). O Flowker é um mecanismo de orquestração de workflows. Use-o para modelar, executar e escalar processos de negócio. Você vai rodar o Flowker localmente e executar seu primeiro workflow, da criação até a recuperação do resultado. 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, confirme que seu ambiente está pronto: | Ferramenta | Versão mínima | Comando de verificação | | -------------- | ------------- | ------------------------ | | Go | 1.26.5+ | `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). Este guia não precisa de infraestrutura externa. ## Passo 1: Obtenha o Flowker e configure o projeto *** O Flowker está disponível para clientes licenciados. Seu repositório permanece interno. Os passos abaixo supõem que você já tem acesso aos arquivos necessários do projeto Flowker. A partir do diretório do projeto Flowker, 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 informar um servidor em execução, o Flowker estará disponível em `http://localhost:4021`. O comando `make dev` inicia o MongoDB, gera a documentação da API e roda a aplicação Flowker com autenticação desabilitada, para que você possa testar livremente durante o desenvolvimento. ## Passo 2: Crie seu primeiro workflow *** Workflows definem como seu processo de negócio se comporta: quais etapas rodam, em qual ordem e sob quais condições. Cada workflow tem **nós** (as etapas) e **arestas** (as conexões entre elas). Crie um workflow com um gatilho 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": "my-first-workflow", "description": "A simple workflow with one trigger and one action.", "nodes": [ { "id": "trigger-1", "type": "trigger", "name": "Start", "position": { "x": 0, "y": 0 }, "data": { "triggerType": "webhook", "path": "my-first-workflow", "method": "POST", "input_contract": "open", "format": "json" } }, { "id": "log-event", "type": "action", "name": "Log event", "position": { "x": 200, "y": 0 }, "data": { "action": "log" } } ], "edges": [ { "id": "e1", "source": "trigger-1", "target": "log-event" } ] }' | jq . ``` A resposta confirma o novo workflow no status `draft`: ```json theme={null} { "id": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a", "name": "my-first-workflow", "status": "draft" } ``` Guarde o valor de `id`. Você vai precisar dele nos próximos passos. Todo novo workflow começa no status `draft`. Um workflow deve ter pelo menos um nó. No Flowker, os **nós** representam as etapas individuais do seu workflow (o que você poderia chamar de tarefas em termos de negócio). As **arestas** definem a ordem em que essas etapas rodam. ## Passo 3: Ative o workflow *** Você deve ativar um workflow antes de poder executá-lo. 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 . ``` Depois da ativação, a estrutura de um workflow permanece travada. Você não pode editá-la diretamente. Para fazer mudanças, 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. Você deve enviar o header `Idempotency-Key` para tornar as novas tentativas 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": "hello from my first workflow" } }' | jq . ``` A resposta confirma que a execução foi iniciada: ```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 uma nova tentativa. ## Passo 5: Verifique os resultados da execução *** Recupere o resultado de uma execução de 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 etapa 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": "hello from my first workflow" } }, "startedAt": "2026-03-18T14:35:00Z", "completedAt": "2026-03-18T14:35:00Z" } ``` Enquanto a execução roda, esse endpoint retorna um status `422`. Consulte `/v1/executions/{executionId}` para checar o status atual antes de solicitar os resultados. ## Explore a API localmente *** O Flowker expõe sua descrição OpenAPI 3.1 e uma interface interativa de documentação quando `SWAGGER_ENABLED=true`. O arquivo de ambiente de exemplo que `make dev-setup` copia já define essa variável, então a superfície fica disponível em uma stack local. Onde a variável não estiver definida, o Flowker não monta as rotas e retorna `404`. | Superfície | URL | | ----------------------- | ------------------------------------------------------------------------ | | Documentação interativa | [http://localhost:4021/openapi/docs](http://localhost:4021/openapi/docs) | | Spec (JSON) | `http://localhost:4021/openapi/openapi.json` | | Spec (YAML) | `http://localhost:4021/openapi/openapi.yaml` | Use a interface de documentação para: * Inspecionar todos os endpoints disponíveis * Testar requisições de forma interativa * Entender as estruturas de requisição e resposta ## Uma nota sobre autenticação *** No ambiente de desenvolvimento local (`make dev`), a autenticação vem desabilitada por padrão. Em staging, produção, ou qualquer ambiente com o Access Manager habilitado (`PLUGIN_AUTH_ENABLED=true`), todos os endpoints `/v1/*` exigem um Bearer token no header `Authorization`: ```bash theme={null} curl -H "Authorization: Bearer " http://your-flowker-host/v1/workflows ``` ## Próximos passos *** Agora você tem um ambiente Flowker em execução e já executou seu primeiro workflow. A partir daqui, você pode: * **Modelar processos de negócio reais** usando diferentes tipos de nó: `trigger`, `executor`, `conditional` e `action` * **Integrar sistemas externos** por meio de configurações de provedor (conecte-se a provedores de KYC, mecanismos antifraude, serviços de pagamento) * **Projetar fluxos condicionais** com nós condicionais que avaliam expressões sobre as saídas das etapas e roteiam pela aresta `sourceHandle` correspondente * **Monitorar execuções** usando os endpoints de status e resultados de execução O modelo central é o mesmo para fluxos simples e para orquestração em nível de produção.