- Padrão de Datas e Timezone
- Operadores de Comparação
- Exemplos Práticos de Consulta
- Perguntas Frequentes (FAQ)
Padrão de Datas e Timezone
Na API Analytics, é possível utilizar filtros de data em diversos recursos. Para garantir a precisão das consultas, é fundamental compreender o formato aceito pelo sistema.
→ Todas as datas utilizadas na API devem seguir o formato ISO 8601. Além disso, os registros são sempre retornados em Timezone UTC.
Operadores de Comparação
Para refinar sua busca por períodos específicos, você deve utilizar os comparadores de operação abaixo:
- [eq]: Igual a (Equal).
- [gte]: Maior ou igual a (Greater than or equal).
- [lte]: Menor ou igual a (Less than or equal).
Com esses operadores, você pode consultar registros a partir de uma data, até uma data limite ou criar intervalos de período.
→ Se nenhum operador for informado na consulta, o sistema interpretará automaticamente como [eq] (igual à informação enviada).
Exemplos Práticos de Consulta
Abaixo, apresentamos cenários comuns utilizando a consulta de avaliações (Checklists Aplicados).
1. Avaliações concluídas após uma data específica
Neste exemplo, buscamos registros após 01/05/2022 às 12:00:00 (considerando o Timezone America/Sao_Paulo, ou seja, -03:00).
2. Avaliações em andamento iniciadas após uma data
Aqui filtramos avaliações que começaram a ser aplicadas após 10/04/2022 às 18:00:00 (Timezone America/Sao_Paulo).
3. Consulta por data exata (sem operador)
Ao buscar uma data exata, observe a diferença entre o fuso horário informado no filtro e o retornado pela API (UTC).
4. Consultando vários status na mesma requisição
Para filtrar mais de um status (ex: avaliações em andamento E concluídas), utilizamos o sufixo [] no parâmetro. No exemplo abaixo, filtramos pelos status 2 (em andamento) e 6 (concluído).
5. Filtrar registros não excluídos
Alguns registros podem ficar marcados no sistema antes da exclusão definitiva. Para buscar apenas o que está ativo, utilizamos o filtro deletedAt com valor null.
→ Isso informa à API que desejamos apenas registros onde o campo de data de exclusão esteja vazio.
Perguntas Frequentes (FAQ)
1. Por que a data retornada é diferente da que eu filtrei?
Isso ocorre devido ao fuso horário. A API retorna os dados sempre em UTC (Tempo Universal Coordenado), enquanto seu filtro pode ter sido feito considerando um fuso local (como -03:00 de Brasília).
2. Como filtro múltiplos valores para o mesmo campo?
Adicione colchetes [] ao final do nome do parâmetro na URL. Exemplo: status[]=2&status[]=6.
❓Tem dúvidas? Entre em contato com nosso time de suporte.