Filtros e ordenação

Os endpoints GET de coleção aceitam filtros e ordenação por query string, além da paginação por cursor. Quais campos são filtráveis e ordenáveis varia por recurso — consulte a especificação OpenAPI de cada endpoint. Aqui está a gramática comum.

Filtros

Sintaxe: ?campo=valor (igualdade) ou ?campo[operador]=valor.

Operador	Sintaxe	Significado
eq (implícito)	?status=paid ou ?status[eq]=paid	Igual a
in	?status[in]=pending,paid	Está em (lista separada por vírgula)
gte	?due_date[gte]=2026-01-01	Maior ou igual
lte	?due_date[lte]=2026-01-31	Menor ou igual
gt	?amount[gt]=100.00	Maior que
lt	?amount[lt]=100.00	Menor que
not	?status[not]=cancelled	Diferente de

Regras:

• Cada recurso permite um subconjunto de campos e operadores; um campo ou operador fora da allowlist → 400 bad_request.
• eq é sempre permitido quando o campo é filtrável.
• Valor vazio (?campo= ou ?campo[in]=) → 400. Omita o parâmetro para não filtrar.
• Vários filtros combinam com E lógico.

Ordenação

?sort=campo (ascendente) ou ?sort=-campo (descendente — prefixo -). Um único campo por vez; um campo fora da allowlist → 400.

Exemplo

# Contas a pagar de uma empresa, vencendo em janeiro, mais recentes primeiro
curl -H "Authorization: Bearer $KOBANA_TOKEN" \
  -H 'User-Agent: Meu Sistema (contato@example.com)' \
  'https://api.finance.kobana.com.br/v1/payables?company_id=00000000-0000-0000-0000-000000000001&due_date[gte]=2026-01-01&due_date[lte]=2026-01-31&sort=-due_date&limit=100'

Combinando com paginação

Filtros e sort valem entre páginas — passe o cursor da resposta anterior junto dos mesmos filtros. Ver Listagem e Paginação.