Pular para conteúdo

Filtros e Query Parameters¶

Visão Geral¶

Os endpoints de listagem da API Pontotel suportam filtros via query parameters para refinar e buscar dados específicos.

Sintaxe Básica¶

HTTP
1	`GET /recurso/?parametro=valor&outro=valor2`

Filtros Comuns por Entidade¶

Empregados¶

Parâmetro	Tipo	Descrição	Exemplo
`empregador_id`	integer	Filtrar por empresa	`?empregador_id=5`
`cpf`	string	Buscar por CPF	`?cpf=12345678900`
`matricula`	string	Buscar por matrícula	`?matricula=EMP-001`
`is_active`	boolean	Status ativo	`?is_active=true`
`data_admissao_gte`	date	Admitidos a partir de	`?data_admissao_gte=2025-01-01`
`data_admissao_lte`	date	Admitidos até	`?data_admissao_lte=2025-12-31`

Empregadores¶

Parâmetro	Tipo	Descrição	Exemplo
`cnpj`	string	Buscar por CNPJ	`?cnpj=12345678000199`
`is_active`	boolean	Status ativo	`?is_active=true`

Marcações de Ponto¶

Parâmetro	Tipo	Descrição	Exemplo
`empregado_id`	integer	Filtrar por empregado	`?empregado_id=123`
`data_inicio`	datetime	A partir de	`?data_inicio=2025-01-01T00:00:00-03:00`
`data_fim`	datetime	Até	`?data_fim=2025-01-31T23:59:59-03:00`
`tipo`	string	Tipo de marcação	`?tipo=entrada`

Férias¶

Parâmetro	Tipo	Descrição	Exemplo
`empregado_id`	integer	Filtrar por empregado	`?empregado_id=123`
`data_inicio_gte`	date	Início a partir de	`?data_inicio_gte=2025-01-01`
`status`	string	Status do período	`?status=aprovado`

Lookups de Comparação¶

Além de igualdade, a API suporta lookups usando sufixos:

Sufixo	Operação	Exemplo
`_gte`	≥ (maior ou igual)	`?data_admissao_gte=2025-01-01`
`_lte`	≤ (menor ou igual)	`?data_admissao_lte=2025-12-31`
`_gt`	> (maior que)	`?id_gt=100`
`_lt`	< (menor que)	`?id_lt=500`
`_contains`	Contém texto	`?nome_contains=Silva`
`_icontains`	Contém (case-insensitive)	`?nome_icontains=silva`
`_in`	Em uma lista	`?id_in=1,2,3`

Exemplos de Filtros Combinados¶

HTTP
# Empregados ativos de uma empresa, admitidos em 2025
GET /empregados/?empregador_id=5&is_active=true&data_admissao_gte=2025-01-01&data_admissao_lte=2025-12-31

# Marcações de um empregado em janeiro de 2025
GET /marcacoes/?empregado_id=123&data_inicio=2025-01-01T00:00:00-03:00&data_fim=2025-01-31T23:59:59-03:00

# Buscar empregado pelo CPF
GET /empregados/?cpf=12345678900

Busca Textual¶

Alguns endpoints suportam o parâmetro search para busca em múltiplos campos:

HTTP
# Buscar empregados por nome ou CPF
GET /empregados/?search=João

# Buscar empregadores por nome ou CNPJ
GET /empregadores/?search=empresa

Próximos Passos¶