Skip to main content

​
Descripción general

Todos los datos de nuestro sistema se almacenan en UTC, pero nuestro procesamiento se ejecuta según un horario EST (Eastern Standard Time). Comprender cómo funcionan los rangos de fechas es fundamental para consultar los datos correctos para tu caso de uso.
Un manejo incorrecto de las zonas horarias es la causa más común de datos faltantes o inesperados en las respuestas de la API. Lee esta guía con atención.

​
Comportamiento del sistema

​
Horario de procesamiento de datos

Nuestro sistema procesa los datos según la zona horaria EST:
  • El “día” 1 de enero EST comienza a las 00:00 EST (05:00 UTC)
  • El “día” 1 de enero EST termina a las 23:59 EST (04:59 UTC del día siguiente)
Todos los datos se almacenan con marcas de tiempo UTC en nuestra base de datos.

​
Formatos de fecha admitidos

La API acepta fechas en varios formatos:
  1. Solo fecha (recomendado para consultas diarias): 2025-01-01
  2. Fecha y hora sin zona horaria: 2025-01-01T00:00:00
  3. Fecha y hora con zona horaria UTC: 2025-01-01T05:00:00Z

​
Cómo se interpretan las fechas

​
Sin especificar la zona horaria

Cuando proporcionas una fecha sin zona horaria (sin el sufijo Z), la API la interpreta como EST:
Qué ocurre:
  • 2025-01-01 → Se interpreta como 2025-01-01T00:00:00 EST → Se convierte a 2025-01-01T05:00:00Z UTC
  • 2025-01-31 → Se interpreta como 2025-01-31T00:00:00 EST → Se convierte a 2025-01-31T05:00:00Z UTC
Esto coincide con la forma en que nuestro sistema define los “días” y es el enfoque recomendado para la mayoría de los casos de uso.

​
Con zona horaria UTC (sufijo Z)

Cuando proporcionas una fecha con el sufijo Z, la API la interpreta como UTC literal:
Qué ocurre:
  • 2025-01-01T00:00:00Z → Se usa tal cual en UTC
  • 2025-02-01T00:00:00Z → Se usa tal cual en UTC
Usar marcas de tiempo UTC (con Z) requiere que conviertas manualmente de EST a UTC. Este enfoque existe por compatibilidad con versiones anteriores, pero no se recomienda para integraciones nuevas.

​
Ejemplos

​
Correcto: consultar los datos de enero de 2025 (días EST)

Esto devuelve todos los datos desde:
  • Inicio: 1 de enero, 00:00 EST (05:00 UTC del 1 de enero)
  • Fin: 1 de febrero, 00:00 EST (05:00 UTC del 1 de febrero)
El rango es inclusivo (<=), pero como los datos normalmente no tienen marcas de tiempo exactamente a las 00:00, en la práctica esto abarca todo enero.

​
Incorrecto: consultar enero de 2025 con medianoche UTC

Esto devuelve datos desde:
  • Inicio: 31 de diciembre, 19:00 EST (00:00 UTC del 1 de enero)
  • Fin: 31 de enero, 19:00 EST (00:00 UTC del 1 de febrero)
Problema: te faltan 5 horas al inicio e incluyes 5 horas que no quieres al final.

​
Correcto: consultar enero de 2025 con UTC (conversión manual)

Si debes usar marcas de tiempo UTC, tienes que tener en cuenta el desfase de EST:
Esto abarca correctamente todo enero (días EST), pero requiere cálculos manuales de zona horaria.

​
Rangos horarios

​
El formato de solo fecha usa medianoche por defecto

Cuando usas el formato de solo fecha, la hora predeterminada es 00:00:00:

​
Especificar horas exactas

Puedes especificar horas exactas para consultas más detalladas:
Esto consulta los datos de 8 AM a 5 PM EST del 1 de enero.

​
Comportamiento de los rangos de fechas

Los rangos de fechas son inclusivos en ambos extremos (start <= x <= end):
Esto incluye:
  • Todo el 1 de enero (desde las 00:00 EST en adelante)
  • El 2 de enero exactamente a las 00:00 EST
  • Como los datos tienen marcas de tiempo a lo largo del día, normalmente no hay datos exactamente a las 00:00, así que en la práctica esto abarca todo el 1 de enero
Para consultar un solo día, establece end_date en el día siguiente a las 00:00.

​
Prácticas recomendadas

Recomendado: usa el formato de solo fecha sin zona horaria para consultas diarias
Recomendado: usa fecha y hora sin zona horaria para consultas dentro del mismo día
Recomendado: usa fecha y hora sin zona horaria para consultas de informes por hora (a través de la pestaña V2 (hourly) de Agent Analytics)
Usuarios de zonas horarias con desfase fraccionario: al consultar con granularidad por hora con /v2/reports/*, consulta 2 horas consecutivas para obtener datos completos de una sola hora local. Consulta Zonas horarias con desfase fraccionario para más detalles.
Evita: usar el sufijo Z a menos que comprendas las implicaciones del desfase UTC

​
Horario de verano

EST aplica el horario de verano (DST):
  • Horario estándar (EST): UTC-5 (normalmente de noviembre a marzo)
  • Horario de verano (EDT): UTC-4 (normalmente de marzo a noviembre)
La API gestiona automáticamente las transiciones del horario de verano. Cuando especificas fechas sin zona horaria, la conversión a UTC tiene en cuenta si el horario de verano estaba activo en esa fecha. Ejemplo durante el horario de verano:
→ Se convierte a 2025-07-01T04:00:00Z UTC (no 05:00 debido al horario de verano)

​
Zonas horarias con desfase fraccionario

Algunas zonas horarias usan desfases UTC fraccionarios en lugar de horas completas: Como los intervalos por hora están alineados con los límites de hora completa en UTC, una sola hora local en estas zonas horarias siempre abarcará dos intervalos por hora. Para obtener datos completos de cualquier hora local, debes consultar 2 horas consecutivas.

​
Ejemplo: consultar las 2:00 PM IST

IST es UTC+5:30, por lo que las 2:00 PM IST = 08:30 UTC. La hora de 2:00 PM a 3:00 PM IST (08:30 - 09:30 UTC) abarca dos intervalos horarios UTC:
  • 08:00 - 08:59 UTC (contiene los primeros 30 minutos: 2:00 PM - 2:30 PM IST)
  • 09:00 - 09:59 UTC (contiene los últimos 30 minutos: 2:30 PM - 3:00 PM IST)
Para obtener la hora completa, consulta ambos intervalos:
Esto se aplica al consultar con granularidad por hora a través de /v2/reports/*. Si estás en una zona horaria con desfase fraccionario y solicitas datos por hora, solicita siempre 2 horas consecutivas para no perder los datos que caen en el intervalo adyacente.

​
Solución de problemas

​
Faltan datos en los límites del día

Problema: consultas el 1 de enero, pero faltan las primeras o las últimas horas. Solución: asegúrate de no usar el sufijo Z. Usa "start_date": "2025-01-01" en lugar de "start_date": "2025-01-01T00:00:00Z".

​
Aparecen datos del día anterior o siguiente

Problema: tu consulta diaria incluye datos de días adyacentes. Solución: probablemente estés usando el sufijo Z con medianoche UTC, que no se alinea con los días EST. Elimina el sufijo de zona horaria.

​
Comportamiento inesperado con el horario de verano

Problema: tus consultas tienen una diferencia de 1 hora durante las transiciones del horario de verano. Solución: deja que la API gestione el horario de verano automáticamente usando fechas sin zona horaria. Si debes usar UTC, recuerda que el desfase cambia entre EST (-5) y EDT (-4).

​
Cambios futuros

En una versión futura de la API, planeamos admitir desfases de zona horaria ISO 8601 completos (por ejemplo, -05:00, +09:00) para permitir consultas en varias zonas horarias. En ese momento, las fechas sin especificación de zona horaria quedarán obsoletas.
Por ahora, el enfoque recomendado es usar fechas sin zona horaria y dejar que la API se encargue de la conversión a EST por ti.