***

title: Filtros e paginação
subtitle: 'Como usar limit, offset e q sem se confundir'
slug: filters-and-pagination
----------------------------

## Visão rápida

Nesta API, a consulta segue esta lógica:

* `limit` controla a quantidade por resposta;
* `offset` controla de onde a página começa;
* `q` aplica filtros, ordenação ou combinações de condição.

## Paginação

* o padrão documentado de paginação é `100` registros por página;
* para ter previsibilidade, informe `limit` explicitamente;
* na carga inicial, siga paginando até `hasMore = false`;
* na sincronização incremental, combine paginação com filtro temporal quando fizer sentido;

## Padrão recomendado

1. teste o endpoint sem filtro;
2. adicione `limit` e `offset` se precisar controlar a paginação;
3. use `q` somente quando quiser restringir ou ordenar o retorno.

## Exemplo sem filtro

```http
GET {{base_url}}/simplificav2/reuniao
Authorization: Bearer {{bearer_token}}
Accept: application/json
```

## Exemplo com paginação

```http
GET {{base_url}}/simplificav2/reuniao?limit={{limit}}&offset=0
Authorization: Bearer {{bearer_token}}
Accept: application/json
```

## Exemplo com filtro simples

Formato legível:

```http
GET {{base_url}}/simplificav2/pessoa?q={"ativo":"S"}
Authorization: Bearer {{bearer_token}}
Accept: application/json
```

Formato pronto para URL:

```http
GET {{base_url}}/simplificav2/pessoa?q=%7B%22ativo%22%3A%22S%22%7D
Authorization: Bearer {{bearer_token}}
Accept: application/json
```

## Exemplo por ID

Formato legível:

```http
GET {{base_url}}/simplificav2/pessoa?q={"id":162472}
Authorization: Bearer {{bearer_token}}
Accept: application/json
```

Formato pronto para URL:

```http
GET {{base_url}}/simplificav2/pessoa?q=%7B%22id%22%3A162472%7D
Authorization: Bearer {{bearer_token}}
Accept: application/json
```

## Exemplo com ordenação

Formato legível:

```http
GET {{base_url}}/simplificav2/pessoa?q={"$orderby":{"alterado_em":"DESC"}}
Authorization: Bearer {{bearer_token}}
Accept: application/json
```

Formato pronto para URL:

```http
GET {{base_url}}/simplificav2/pessoa?q=%7B%22%24orderby%22%3A%7B%22alterado_em%22%3A%22DESC%22%7D%7D
Authorization: Bearer {{bearer_token}}
Accept: application/json
```

## Exemplo por período

Formato legível:

```http
GET {{base_url}}/simplificav2/receita?q={"criado_em":{"$between":[{"$date":"2026-03-01T00:00:00Z"},{"$date":"2026-03-31T23:59:59Z"}]}}
Authorization: Bearer {{bearer_token}}
Accept: application/json
```

Formato pronto para URL:

```http
GET {{base_url}}/simplificav2/receita?q=%7B%22criado_em%22%3A%7B%22%24between%22%3A%5B%7B%22%24date%22%3A%222026-03-01T00%3A00%3A00Z%22%7D%2C%7B%22%24date%22%3A%222026-03-31T23%3A59%3A59Z%22%7D%5D%7D%7D
Authorization: Bearer {{bearer_token}}
Accept: application/json
```

## Operadores úteis no q

* `$or`
* `$between`
* `$orderby`
* `$date`
* `$ne`
* `$lt`
* `$lte`
* `$gt`
* `$gte`
* `$instr`
* `$ninstr`
* `$notnull`

## Regras importantes

* `offset` e `limit` ficam fora do `q`;
* use os campos publicados naquele endpoint;
* use sempre o nome do campo exatamente como ele aparece no schema do endpoint;
* em clientes HTTP fora do Postman, o JSON de `q` normalmente precisa ser URL-encoded.

## Erros comuns

* tentar usar no `q` um campo que aquele endpoint não publica;
* copiar um filtro de `pessoa` e usar igual em `receita` ou `venda`;
* colocar `offset` e `limit` dentro do objeto JSON;
* montar filtro complexo antes de testar a resposta base.