Fluxo — Visão Geral
Fluxo — Visão geral
Fluxo é o recurso estrutural de mais alto nível do AgFlow. Não deve ser confundido com fase, que é uma etapa dentro de um fluxo — nem com os módulos habilitados em cada fase (aprovação, parecer, motores, mensageria).
Endpoints deste domínio
| Método | Caminho | Descrição |
|---|---|---|
GET | /v1/flows/health-check | Verifica a disponibilidade da API |
POST | /v1/flows | Cria um fluxo |
GET | /v1/flows | Lista os fluxos da empresa |
GET | /v1/flows/{id} | Obtém um fluxo específico |
PUT | /v1/flows/{id} | Atualiza um fluxo (substituição completa) |
DELETE | /v1/flows/{id} | Remove um fluxo por completo |
POST | /v1/flows/{id}/users | Adiciona um usuário ao fluxo |
DELETE | /v1/flows/{id}/users/{userId} | Remove um usuário do fluxo |
GET | /v1/flows/{flowId}/dynamic-fields-paths | Lista os caminhos de campos disponíveis para condições e regras |
Nota sobre nomenclatura: a maioria dos endpoints deste domínio utiliza {id}como parâmetro de caminho do fluxo. A exceção édynamic-fields-paths, que utiliza{flowId}.
Criação vs. atualização: exigências diferentes
POST /v1/flows) e a atualização (PUT /v1/flows/{id}) de um fluxo têm regras bem distintas quanto aos campos obrigatórios:| Campo | Na criação | Na atualização |
|---|---|---|
name | Obrigatório | Obrigatório, mesmo sem mudar |
description | Opcional | Obrigatório, mesmo sem mudar |
createCardLabel | Obrigatório na prática | Se ausente, reset silencioso para "Novo Card" |
cardCountLabel | Obrigatório na prática | Se ausente, reset silencioso para "cards" |
color | Opcional | Obrigatório, mesmo sem mudar |
icon | Opcional | Obrigatório, mesmo sem mudar |
GET /v1/flows/{id} antes de montar o payload de uma atualização, reenviando todos os campos existentes.Comportamentos importantes
createButtonLabel não é aceito em POST /v1/flows — ele pertence ao formulário de abertura, não ao fluxo. Utilize createCardLabel no lugar.color do fluxo aceita um código hexadecimal (#RRGGBB) ou um dos 7 valores nominais fixos (turquoise, blue, orange, violet, pink, purple, light_blue). Já a cor de cada item em labelOptions deve ser sempre um código hexadecimal — valores nominais são rejeitados nesse campo específico.createCardLabel ou cardCountLabel em uma atualização não gera erro — a API reseta silenciosamente esses campos para os valores padrão, sem aviso. É o único caso, dentro deste domínio, em que a ausência de um campo não retorna um erro explícito.GET /v1/flows retorna a lista de fluxos dentro de items, sem metadados de paginação (sem cursor ou contagem total).DELETE /v1/flows/{id}) é uma operação destrutiva e irreversível — remove fases, cards e todas as configurações associadas.{users:[{userId, userName, userEmail, role:{id, name}}]} — formatos simplificados como {userId, roleId} são rejeitados com erro 400.dynamic-fields-paths é o catálogo de referência para montar condições de triggers, regras e templates — cada caminho já vem com seu type esperado (array, text, currency, date, boolean ou number).Modificado em 2026-07-28 20:38:32