Query parameters

Aplicáveis principalmente a GET /items/:collection e a listagens de domínio.

Parâmetros

Param	Tipo	Default	Descrição
`filter`	object (query)	—	Filtros da API Kunk
`sort`	string / array	`-id` ou `id`	Ordenação
`limit`	int	`25`	Máx. por página (cap server-side)
`offset`	int	`0`	Paginação offset
`page`	int	—	Alternativa a offset (`page` 1-based)
`fields`	string	`*` seguro	Colunas a retornar
`search`	string	—	Busca full-text / icontains em campos indexados
`meta`	string	—	Metadados: `filter_count`, `total_count`, `*`

Filter (da API Kunk)

Exemplos

GET /items/orders?filter[status][_eq]=Pagamento%20concluído
GET /items/orders?filter[prescriber_code][_eq]=uuid-aqui
GET /items/users?filter[associate_name][_icontains]=silva
GET /items/orders?filter[_and][0][status][_eq]=x&filter[_and][1][date_created][_gte]=2026-01-01

JSON em query (alternativa, se o client preferir):

GET /items/orders?filter={"status":{"_eq":"Produção Finalizada"}}

O servidor aceita um formato canônico (recomendado: estilo de query aninhada); o outro pode existir como opcional.

Sort

GET /items/orders?sort=-date_created
GET /items/orders?sort=status,-id

Prefixo - = descendente
Múltiplos campos separados por vírgula

Fields

GET /items/users?fields=id,associate_name,user_code,status

Sem fields → conjunto default (sem campos sensíveis)
fields=* → todos os campos não sensíveis

Include (relações)

Expande objetos relacionados em rotas de domínio (e listagens que suportam o param).

GET /services?include=professional,associate
GET /users?include=responsible
GET /users/by-code/:user_code?include=responsible

Collection	Chaves `include`	Join
`services`	`professional`	`professional_id` → `professionals.professional_code`
`services`	`associate`	`associate_user_code` → `users.user_code`
`users`	`responsible`	`responsible_code` → `users.user_code`

Chave desconhecida → 400 VALIDATION_ERROR.

Patients (users)

GET /users?patients
GET /users/by-code/:user_code?patients

Embute array patients nos associados (WHERE responsible_code = user.user_code). Pacientes retornam patients: [].

A presença do param liga o embed (?patients ou ?patients=). Use patients=false para desligar explicitamente.

Meta	Significado
`filter_count`	total após filter (sem limit)
`total_count`	total da collection (sem filter)

Paginação

GET /items/orders?limit=50&offset=100
GET /items/orders?limit=50&page=3

Se page e offset forem enviados juntos: page vence, ou retornar 400.

Search

GET /items/users?search=maria

Aplica _icontains em um conjunto fixo de colunas por collection (ex.: users → associate_name, fullname, email_account, associate_cpf).

Limites e erros

Situação	Resposta
`limit` > max	clamp ou 400 `VALIDATION_ERROR`
Campo de filter inválido	400
Operador não suportado	400
Sort em coluna inexistente	400
`include` inválido	400

Implementação

Traduzir filter → SQL parametrizado (WHERE + binds)
Nunca concatenar valores crus
Índices no Postgres para colunas filtradas com frequência (user_code, status, prescriber_code, …)
include / patients: batch load (sem N+1)