Filtros — Visão Geral
Filtros — Visão geral
1.
GET/POST/PUT /v1/flows/{id}/filters) — gerenciam uma visualização pré-configurada do kanban de um flow, persistida para reuso na interface (ordenação, projeção de campos e condições). Cada usuário possui no máximo um filtro salvo por flow, sempre amarrado ao usuário autenticado.2.
POST /v1/filters/flows/{flowId}/search e POST /v1/filters/search) — executam uma consulta pontual usando uma linguagem de condições (DSL), retornando diretamente os cards encontrados. O primeiro escopa a busca a um único flow; o segundo abrange todos os flows acessíveis ao usuário autenticado.Filtro salvo é configuração; busca é consulta. Salvar um filtro não executa nenhuma busca, e buscar cards não persiste nada.
Endpoints deste domínio
| Método | Caminho | Descrição |
|---|---|---|
GET | /v1/flows/{id}/filters | Lista os filtros salvos do flow para o usuário autenticado |
POST | /v1/flows/{id}/filters | Cria o filtro salvo do usuário autenticado para o flow |
PUT | /v1/flows/{id}/filters | Atualiza o filtro salvo do usuário autenticado para o flow |
POST | /v1/filters/flows/{flowId}/search | Busca cards dentro de um único flow |
POST | /v1/filters/search | Busca cards entre todos os flows acessíveis ao usuário |
Nota sobre nomenclatura: o parâmetro de flow varia de caminho para caminho neste domínio. Nos filtros salvos, ele é {id}; na busca por flow, ele é{flowId}. Na busca global não há parâmetro de flow no caminho, pois a consulta abrange múltiplos flows.
Filtros salvos: regras de propriedade
userId nunca deve ser enviado no corpo de POST ou PUT. Enviá-lo retorna erro 400.POST) para o mesmo par retorna erro 422, informando que o filtro já existe — nesse caso, utilize a atualização (PUT) em vez de criar novamente.PUT) substitui integralmente a configuração anterior — ordenação, limite, projeção de campos e condições.Busca de cards: regras do envelope
page e pageSize não são aceitos em nenhum dos dois endpoints de busca e retornam erro 400 caso estejam presentes no corpo.order (asc ou desc), orderBy (caminho de ordenação, não vazio), fields (lista não vazia de projeções {path}) e conditions (lista não vazia de nós de condição).conditions é um grupo (scope, logic — AND ou OR — e uma lista de subcondições) ou uma folha (scope, path e, opcionalmente, operator e value). O campo scope — any, all ou sum — é obrigatório em todo nó, grupo ou folha, e define a semântica de agregação sobre coleções.conditions e fields.Comportamentos importantes
conditions é um único grupo (logic + lista de subcondições); na busca, conditions é uma lista de nós na raiz, cada um podendo ser grupo ou folha.userId) e do flow (flowId) presentes na resposta de leitura de um filtro salvo são sempre denormalizados pela API — nunca definidos pelo cliente.POST, mesmo se tratando de uma operação de leitura — o corpo da requisição carrega o envelope de condições, que normalmente não caberia em uma query string.Modificado em 2026-07-28 20:38:32