Paginação e Filtros

Paginação por cursor

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

Como funciona

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

Parâmetros

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": "asc" }
  }
}

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

No payload JSON de filters, use { "f": "reference_code", "op": "is_null" } sem v (ou "v": null) — o operador não carrega valor:

{
    "logic": "and",
    "conditions": [{ "f": "reference_code", "op": "is_null" }]
}

Equivalente flat: GET /products?reference_code[is_null]=true

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

Ordenação padrão por recurso

Se você não enviar sort, cada recurso aplica a ordenação que faz sentido para o seu domínio — não existe um padrão único para toda a API:

O bloco meta.sort da resposta sempre ecoa a ordenação efetivamente aplicada, então você pode confirmar o comportamento sem adivinhar.

A ordenação padrão é estável e faz parte do contrato: paginar por cursor sem sort percorre a coleção inteira sem repetir nem pular registros. Se a sua integração depende de uma ordem específica, envie sort explicitamente em vez de confiar no padrão.

Regras

• Todos os filtros são combinados com AND
• is_null / is_not_null só funcionam em campos marcados como nullable no contrato do recurso (ex.: reference_code em cadastros que aceitam código opcional)
• 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