Filtros y ordenación

Los endpoints GET de colección aceptan filtros y ordenación por query string, además de la paginación por cursor. Qué campos son filtrables y ordenables varía por recurso — consulta la especificación OpenAPI de cada endpoint. Aquí está la gramática común.

Filtros

Sintaxis: ?campo=valor (igualdad) o ?campo[operador]=valor.

Operador	Sintaxis	Significado
eq (implícito)	?status=paid o ?status[eq]=paid	Igual a
in	?status[in]=pending,paid	Está en (lista separada por comas)
gte	?due_date[gte]=2026-01-01	Mayor o igual
lte	?due_date[lte]=2026-01-31	Menor o igual
gt	?amount[gt]=100.00	Mayor que
lt	?amount[lt]=100.00	Menor que
not	?status[not]=cancelled	Distinto de

Reglas:

• Cada recurso permite un subconjunto de campos y operadores; un campo u operador fuera de la allowlist → 400 bad_request.
• eq siempre está permitido cuando el campo es filtrable.
• Valor vacío (?campo= o ?campo[in]=) → 400. Omite el parámetro para no filtrar.
• Varios filtros se combinan con Y lógico.

Ordenación

?sort=campo (ascendente) o ?sort=-campo (descendente — prefijo -). Un único campo a la vez; un campo fuera de la allowlist → 400.

Ejemplo

# Cuentas por pagar de una empresa, con vencimiento en enero, más recientes primero
curl -H "Authorization: Bearer $KOBANA_TOKEN" \
  -H 'User-Agent: Mi Sistema (contacto@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 con paginación

Los filtros y sort se mantienen entre páginas — pasa el cursor de la respuesta anterior junto con los mismos filtros. Ver Listado y Paginación.