Filtros dinâmicos

⚠️
Disponibilidade: Os filtros dinâmicos não estão habilitados em todos os endpoints. Você só pode utilizá-los naqueles que indicam explicitamente em sua documentação de referência. Consulte a página de cada endpoint para verificar se ele suporta filtros e quais campos estão disponíveis.

🔷 Como funcionam os filtros?

Todos os filtros aplicados em uma mesma consulta são avaliados sob uma lógica de cumprimento obrigatório (AND). Isso significa que os resultados exibidos serão apenas aqueles que atendam a todas as condições enviadas simultaneamente.

🔷 Estrutura do filtro

Cada filtro é composto por três partes: o nome do campo, o operador de comparação e o valor desejado.

Formato padrão:

campo[operador]=valor

Exemplo: Buscar ordens de trabalho cujo status seja "open" e cujo custo seja maior ou igual a 100:

GET https://app.fracttal.com/api/work_orders?status[eq]=open&cost[gte]=100

🔷 Operadores disponíveis

A seguir, são detalhados os operadores permitidos de acordo com o tipo de informação que o campo contém (texto, números ou datas).

Operador	Descrição	Tipos de dado suportados
eq	Igualdade exata	texto, número, data, booleano
neq	Diferente de	texto, número, data, booleano
gt	Maior que	número, data
gte	Maior ou igual a	número, data
lt	Menor que	número, data
lte	Menor ou igual a	número, data
like	Busca parcial (que contenha o texto)	texto
between	Faixa entre dois valores	número, data
in	Lista de valores (separados por vírgula)	somente números

🔷 Funcionamento dos operadores

Igualdade e Diferença

Busca uma correspondência exata (eq) ou exclui registros específicos (neq).

Exemplos:

?id[eq]=3 (Somente o registro com ID 3)
?id[neq]=1 (Todos os registros exceto o ID 1)
?status[eq]=open (Ordens de trabalho com status "open")

🔷 Aplicação de múltiplos filtros

Combine várias condições em uma única requisição utilizando o símbolo &. O sistema retorna apenas os registros que atendam a todas as condições ao mesmo tempo.

Exemplo: Buscar ordens de trabalho que não sejam a #3, com custo menor que 500 e descrição que contenha "urgente":

GET https://app.fracttal.com/api/work_orders?id[neq]=3&cost[lt]=500&description[like]=urgente

🔷 Filtragem por datas

As datas são um dos filtros mais utilizados. A API espera datas no formato ISO 8601: YYYY-MM-DDTHH:MM:SS±UTC.

Filtra ordens de trabalho criadas em janeiro de 2024:

GET https://app.fracttal.com/api/work_orders?date[between]=2024-01-01T00:00:00-05,2024-01-31T23:59:59-05

Alternativa ao between usando dois filtros separados. Filtra ordens de trabalho entre 1º de março e 30 de junho de 2024:

GET https://app.fracttal.com/api/work_orders?date[gte]=2024-03-01T00:00:00-05&date[lte]=2024-06-30T23:59:59-05

Esta forma é útil quando você precisa combinar a faixa de datas com outros filtros adicionais.

O sinal + em um fuso horário deve ser codificado como %2B na URL. Se não for codificado, o servidor o interpreta como um espaço e a consulta falha.

❌ Incorreto:

?date[gt]=2024-01-01T00:00:00+02

✅ Correto:

?date[gt]=2024-01-01T00:00:00%2B02

🔷 Exemplo completo de requisição e resposta

A seguir, é mostrada uma requisição real com filtros aplicados e as possíveis respostas.

Requisição: Obter ordens de trabalho com status "open" e custo maior ou igual a 100:

curl -X GET "https://app.fracttal.com/api/work_orders?status[eq]=open&cost[gte]=100" \
  -H "Authorization: Bearer SEU_TOKEN"

{
  "success": true,
  "message": "OK",
  "data": [
    {
      "wo_folio": "OT-001234",
      "description": "Manutenção preventiva bomba hidráulica",
      "status": "open",
      "cost": 250.00,
      "date": "2024-03-15T10:30:00-05"
    },
    {
      "wo_folio": "OT-001289",
      "description": "Revisão sistema elétrico planta norte",
      "status": "open",
      "cost": 180.50,
      "date": "2024-03-20T08:00:00-05"
    }
  ],
  "total": 2
}

Exemplo: é usado o operador like em um campo numérico (cost):

curl -X GET "https://app.fracttal.com/api/work_orders?cost[like]=100" \
  -H "Authorization: Bearer SEU_TOKEN"

{
  "success": false,
  "message": "Erro de validação",
  "errors": [
    {
      "field": "cost",
      "operator": "like",
      "error": "O operador 'like' não é compatível com campos numéricos."
    }
  ]
}

🔷 Erros comuns e solução

Erro	Causa	Solução
Operador incompatível com o tipo de dado	Usar `like` em um campo numérico ou `in` em um campo de texto	Consulte a tabela de operadores e verifique os tipos de dado suportados por cada um
Excesso de filtros	Enviar mais de 20 filtros em uma única requisição	Reduza o número de condições ou divida a consulta em várias requisições
Excesso de valores em `in`	Enviar mais de 100 valores em uma lista `in`	Divida os valores em múltiplas requisições com listas de 100 ou menos
Formato incorreto de data	Não seguir o formato ISO 8601 (`YYYY-MM-DDTHH:MM:SS±UTC`)	Use o formato correto: `2024-01-01T00:00:00-05`
Fuso horário com `+` sem codificar	Escrever `+02` em vez de `%2B02` na URL	Codifique o sinal `+` como `%2B`
Operador `between` com valores incorretos	Enviar mais ou menos de 2 valores separados por vírgula	Certifique-se de enviar exatamente dois valores: `?campo[between]=min,max`

🔷 Campos filtráveis por endpoint

📌
Nem todos os endpoints suportam os mesmos campos de filtragem. Os campos disponíveis dependem do recurso que você está consultando. Consulte a documentação de referência de cada endpoint para conhecer os campos específicos que aceita como filtro.
Por exemplo:

Ordens de trabalho (/work_orders): status, cost, date, description, entre outros.

Ativos (/items): code, description, status, entre outros.

Medidores (/meters): code, serial, entre outros.

🔷 Ordenamento e paginação

Os filtros podem ser combinados com parâmetros de ordenamento e paginação para controlar os resultados de forma precisa.

Parâmetros disponíveis:

Parâmetro	Descrição	Exemplo
`sort`	Campo pelo qual ordenar os resultados	`sort=date`
`order`	Direção do ordenamento: `asc` (ascendente) ou `desc` (descendente)	`order=desc`
`page`	Número da página de resultados	`page=1`
`limit`	Quantidade máxima de registros por página	`limit=50`

Exemplo completo: Obter ordens de trabalho com status "open", ordenadas por data descendente, exibindo 20 resultados por página:

GET https://app.fracttal.com/api/work_orders?status[eq]=open&sort=date&order=desc&page=1&limit=20

🔷 Exemplos no contexto Fracttal

Filtrar por status e faixa de datas:

GET https://app.fracttal.com/api/work_orders?status[eq]=open&date[gte]=2024-01-01T00:00:00-05&date[lte]=2024-03-31T23:59:59-05

Buscar por descrição e custo mínimo:

GET https://app.fracttal.com/api/work_orders?description[like]=preventivo&cost[gte]=500

Buscar ativos cuja descrição contenha "bomba":

GET https://app.fracttal.com/api/items?description[like]=bomba

Filtrar ativos ativos excluindo um código específico:

GET https://app.fracttal.com/api/items?status[eq]=ACTIVE&code[neq]=ACT-0001

Consultar leituras de um medidor por faixa de datas:

GET https://app.fracttal.com/api/meters_reading?date[between]=2024-01-01,2024-06-30

Filtrar medidores por código de ativo:

GET https://app.fracttal.com/api/meters?code[eq]=MED-0042

Filtrar solicitações por status e data de criação:

GET https://app.fracttal.com/api/work_requests?status[eq]=PENDING&date[gte]=2024-06-01T00:00:00-05

Buscar solicitações cuja descrição contenha "elétrico":

GET https://app.fracttal.com/api/work_requests?description[like]=elétrico

🔷 Considerações importantes

💡
Regras de validação

Limite de condições: É permitido um máximo de 20 filtros por requisição.

Limite de lista (IN): O operador in permite um máximo de 100 valores por lista.

Compatibilidade: Certifique-se de usar o operador correto para o tipo de dado. Por exemplo, tentar usar like em um campo de preço ou in em um campo de descrição gerará um erro de validação.

Caracteres especiais em datas: Ao filtrar por datas que incluam fusos horários com o sinal de mais (+), este deve ser escrito como %2B.

Correto: ?date[gt]=2024-01-01T00:00:00%2B02

Filtros dinâmicos

🔷 Como funcionam os filtros?

🔷 Estrutura do filtro

🔷 Operadores disponíveis

🔷 Funcionamento dos operadores

Igualdade e Diferença

Busca parcial

Comparações de magnitude

Faixas de valores

Seleção múltipla

🔷 Aplicação de múltiplos filtros

🔷 Filtragem por datas

🔷 Exemplo completo de requisição e resposta

🔷 Erros comuns e solução

🔷 Campos filtráveis por endpoint

🔷 Ordenamento e paginação

🔷 Exemplos no contexto Fracttal

🔷 Considerações importantes