Paginação e Filtros

Como paginar resultados e filtrar dados na API de Integrações usando cursor pagination e flat query params.

Paginação por cursor

Endpoints de listagem usam cursor-based pagination. Esse modelo é mais eficiente que offset pagination para datasets grandes.

Como funciona

Faça a primeira chamada sem o parâmetro cursor
Se pagination.has_next_page for true, use o valor de pagination.next_cursor na próxima chamada
Repita até pagination.has_next_page ser false

Parâmetros

Parâmetro	Tipo	Descrição
`cursor`	string	Cursor opaco da página anterior. Omitir na primeira chamada.
`limit`	number	Itens por página (padrão: 20, máximo: 100)

Exemplo

# Primeira página
curl -H "Authorization: Bearer sk_xxx_yyy" \
  "https://api.biterp.ai/products?limit=10"

# Próxima página
curl -H "Authorization: Bearer sk_xxx_yyy" \
  "https://api.biterp.ai/products?limit=10&cursor=eyJmIjoiY3Jl..."

Formato da resposta

Os dados vêm em data; os metadados de navegação, em pagination; e o eco de filtros/ordenação aplicados, em meta:

{
  "data": [...],
  "pagination": {
    "limit": 20,
    "has_next_page": true,
    "has_previous_page": false,
    "next_cursor": "eyJmIjoiY3JlYXRlZF9hdCIsInYiOi...",
    "previous_cursor": null
  },
  "meta": {
    "sort": { "field": "created_at", "order": "desc" }
  }
}

Filtros (Flat Query Params)

Os endpoints de listagem aceitam filtros via query params planos, no estilo Stripe (bracket notation).

Sintaxe

# Igualdade (sem operador)
GET /products?name=notebook&is_active=true

# Operadores via bracket notation
GET /products?sale_price[gte]=1000&sale_price[lte]=5000

# Busca parcial (contains)
GET /customers?legal_name[contains]=acme

# Combinando filtros, ordenação e paginação
GET /quotes?created_at[gte]=2026-01-01&sort=created_at:desc&limit=50

Operadores disponíveis

Sintaxe	Operador	Tipos suportados
`field=value`	Igual (`eq`)	string, number, boolean, date
`field[neq]=value`	Diferente	string, number, boolean, date
`field[gt]=value`	Maior que	number, date
`field[gte]=value`	Maior ou igual	number, date
`field[lt]=value`	Menor que	number, date
`field[lte]=value`	Menor ou igual	number, date
`field[contains]=value`	Contém (busca parcial)	string
`field[not_contains]=value`	Não contém	string

Ordenação

Use o parâmetro sort com o formato campo:direcao:

# Ordenar por preço decrescente
GET /products?sort=sale_price:desc

# Ordenar por data de criação crescente
GET /products?sort=created_at:asc

Regras

Todos os filtros são combinados com AND
Campos desconhecidos retornam 400 Bad Request
Valores inválidos (ex: texto em campo numérico) retornam 400 Bad Request
Cada recurso tem seus próprios campos filtráveis — consulte a referência de endpoints

Paginação e Filtros

En esta página