Filtros Dinâmicos (query), Ordenação (orderby) e Paginação

Este guia descreve como usar query, orderby, page e pageSize nos endpoints que suportam listagem.

Formato da requisição

Os parâmetros são enviados no corpo como JSON.

Campos

page integer, opcional, default 0

pageSize integer, opcional, default 100

orderby array de strings, opcional

query object, opcional

Regras

Se query não for enviado, o endpoint retorna a lista sem filtros.

Se orderby não for enviado, a API aplica uma ordenação padrão do recurso.

Ordenação, orderby

orderby é uma lista, aplicada na ordem informada.

Sintaxe de cada item

campo assume ascendente

campo/asc ascendente

campo/desc descendente

Exemplo

{
  "orderby": [
    "id/desc",
    "kmStart/asc"
  ]
}

Filtros, query

query é um objeto de filtros onde cada chave é campo ou campo/sufixo.

Se o sufixo não for informado, assume igualdade.

Todos os filtros são combinados com AND.

Sufixos suportados

Sufixo	Operação	Valor esperado	Exemplo de chave
vazio ou `eq`	igual	escalar	`status` ou `status/eq`
`neq`	diferente	escalar	`status/neq`
`gt`	maior que	escalar	`km/gt`
`gte`	maior ou igual	escalar	`km/gte`
`lt`	menor que	escalar	`km/lt`
`lte`	menor ou igual	escalar	`km/lte`
`in`	em lista	array	`lane/in`
`nin`	não em lista	array	`lane/nin`
`like`	contém	string	`comments/like`
`nlike`	não contém	string	`comments/nlike`
`isnull`	é nulo	boolean	`updatedAt/isnull`
`isnotnull`	não é nulo	boolean	`updatedAt/isnotnull`
`btw`	entre	array com 2 valores	`km/btw`
`nbtw`	não entre	array com 2 valores	`km/nbtw`

Valores esperados

Escalar significa um único valor, por exemplo string, number, boolean ou date-time

in e nin aceitam um array com um ou mais itens

btw e nbtw aceitam um array com exatamente 2 itens, na ordem min, max

like e nlike aceitam string

% representa qualquer sequência de caracteres

_ representa um único caractere

para “contém X”, use %X%

isnull e isnotnull aceitam boolean

Tipos e formatação recomendados

date time em ISO 8601

números com ponto decimal

boolean true ou false

Observação relevante

Para comparações ordenadas em campos numéricos e data time, use formatos que preservem ordenação lexical quando serializados, por exemplo ISO 8601 para data time.

Exemplo completo

{
  "page": 0,
  "pageSize": 50,
  "orderby": [
    "id/desc",
    "capturedAt/desc"
  ],
  "query": {
    "roadId": 2795,
    "lane/in": ["R1", "R2"],
    "kmStart/gte": 10.0,
    "kmEnd/lte": 12.0,
    "surveyId/in": [11, 12, 13],
    "capturedAt/gte": "2025-01-01T00:00:00Z",
    "capturedAt/lt": "2026-01-01T00:00:00Z",
    "comments/like": "%trinca%",
    "updatedAt/isnull": true
  }
}

Boas práticas

Prefira filtros que reduzam o conjunto cedo, por exemplo recorte por rodovia e faixa antes de filtros textuais.

Em paginação, mantenha orderby estável para evitar resultados pulando entre páginas.

Erros comuns

in com valor que não é array

btw com array diferente de 2 itens

like sem % quando o objetivo é busca parcial

page ou pageSize com valores inválidos

Filtros Dinâmicos (query), Ordenação (orderby) e Paginação

Formato da requisição#

Ordenação, orderby#

Filtros, query#

Sufixos suportados#

Valores esperados#

Tipos e formatação recomendados#

Exemplo completo#

Boas práticas#

Erros comuns#