Cada vez que trabajas con APIs, bases de datos o logs de servidor, encuentras números que parecen 1719792000 o 1719792000000. Estos son timestamps Unix — un conteo del tiempo transcurrido desde un punto de referencia fijo. Aparecen en claims de expiración de JWT, campos created_at de bases de datos, cabeceras HTTP, tiempos de modificación de archivos y logs de eventos distribuidos. Entender qué representan y cómo convertirlos es una habilidad fundamental de desarrollador que previene categorías enteras de errores relacionados con el tiempo.
¿Qué Es el Epoch Unix?
El epoch Unix es el 1 de enero de 1970, a las 00:00:00 Tiempo Universal Coordinado (UTC). Un timestamp Unix es un entero que representa el número de segundos transcurridos desde este punto de referencia. El epoch fue elegido cuando Unix fue diseñado a finales de los años 60 y principios de los 70 como punto de partida práctico — una fecha lo suficientemente temprana para que las fechas históricas pudieran representarse como timestamps negativos, y lo suficientemente reciente para que los valores se mantuvieran manejables.
El timestamp Unix original usaba un entero con signo de 32 bits, dando un rango hasta el 19 de enero de 2038 (2.147.483.647 segundos). El problema del año 2038 — a veces llamado Y2K38 — ocurre cuando los timestamps Unix de 32 bits se desbordan y envuelven a un número negativo. Los sistemas modernos usan enteros de 64 bits para los timestamps, lo que extiende el rango representable a aproximadamente 292 mil millones de años.
Los timestamps Unix negativos representan momentos anteriores al epoch. El 1 de enero de 1970, 00:00:00 UTC es 0. El 31 de diciembre de 1969, 23:59:59 UTC es -1. No todas las bibliotecas de timestamps manejan correctamente los valores negativos, lo que es una fuente de errores en el código de aritmética de fechas que trata con fechas históricas.
Segundos vs. Milisegundos: El Error Más Común
El error de timestamp Unix más frecuente en el desarrollo web es confundir segundos y milisegundos. El mismo momento puede expresarse en cualquier unidad, y los valores difieren en un factor de 1.000. En segundos: 1719792000 (10 dígitos). En milisegundos: 1719792000000 (13 dígitos). Introducir un timestamp en milisegundos en código que espera segundos produce una fecha en el año 56.000. Introducir un timestamp en segundos en código que espera milisegundos produce una fecha en enero de 1970.
El objeto Date de JavaScript usa milisegundos: Date.now() devuelve el timestamp actual en milisegundos desde el epoch. La mayoría de los entornos del lado del servidor y las convenciones de bases de datos usan segundos. La discrepancia crea errores cuando los clientes JavaScript envían timestamps a APIs de servidor (enviando milisegundos a un endpoint que espera segundos) o cuando las respuestas del servidor son consumidas por JavaScript sin conversión.
La regla práctica: inspecciona el número de dígitos. Un timestamp Unix en segundos tiene 10 dígitos (actualmente alrededor de 1,7 mil millones). Un timestamp Unix en milisegundos tiene 13 dígitos (actualmente alrededor de 1,7 billones). Si recibes un valor de 13 dígitos, divide entre 1.000 para convertir a segundos. Si recibes un valor de 10 dígitos y necesitas milisegundos para JavaScript, multiplica por 1.000. Documenta esta conversión explícitamente en tu código — el error silencioso de factor de 1.000 es notoriamente difícil de detectar en las revisiones de código.
Problemas de Zona Horaria con Timestamps
Un timestamp Unix representa un único momento en el tiempo, globalmente. 1719792000 significa exactamente el mismo instante en cualquier parte de la Tierra — es un punto fijo en la línea temporal, no una "hora local". La conversión de un timestamp Unix a una fecha legible por humanos depende completamente del desplazamiento de zona horaria que apliques. 1719792000 se convierte al 30 de junio de 2024 a las 20:00:00 UTC, que es el 30 de junio de 2024 a las 16:00:00 en Nueva York (UTC-4) y el 1 de julio de 2024 a las 06:00:00 en Tokio (UTC+9).
El error de zona horaria más común es almacenar o mostrar tiempos sin tener en cuenta la zona horaria del usuario. Un servidor que muestra timestamps en la hora local del servidor mostrará tiempos incorrectos a usuarios en diferentes zonas horarias. Siempre convierte los timestamps a la zona horaria local del usuario para mostrar, y siempre almacena y compara timestamps como UTC.
El Horario de Verano (DST) añade otra capa de complejidad. En las regiones que observan el DST, el desplazamiento UTC cambia dos veces al año. La aritmética como "este evento ocurrió hace 7 días" no siempre puede hacerse restando 604.800 segundos — si una transición de DST ocurrió dentro de ese período de 7 días, el resultado estará desviado una hora en hora local. Usa una biblioteca de fecha y hora bien mantenida (date-fns, Luxon en JavaScript, o datetime de Python con zoneinfo) que maneje el DST automáticamente.
Casos de Uso Comunes en APIs y Bases de Datos
Los timestamps en APIs aparecen en claims JWT (los campos exp, iat, nbf son segundos Unix), cabeceras HTTP, payloads de eventos webhook y respuestas de límite de velocidad. La cabecera X-RateLimit-Reset, utilizada por GitHub, Twitter/X y muchas otras APIs, devuelve el timestamp en segundos Unix cuando se restablece la ventana del límite de velocidad. Convertirlo a hora local te dice exactamente cuánto tiempo esperar antes de reintentar.
Las columnas de bases de datos que almacenan timestamps comúnmente usan segundos Unix (entero) o cadenas de fecha y hora ISO 8601. Los timestamps enteros son más compactos y más rápidos de indexar y comparar, pero requieren conversión para su visualización legible. Las cadenas ISO 8601 (2024-06-30T20:00:00Z) se documentan solas y son directamente legibles pero toman más almacenamiento y tiempo de análisis.
Los TTL de caché y la programación de tareas dependen de los timestamps. Una cabecera HTTP Cache-Control: max-age=86400 indica al navegador que almacene en caché la respuesta durante 86.400 segundos (exactamente 24 horas). Los programadores de trabajos en segundo plano en sistemas como Celery, Sidekiq o Bull almacenan timestamps de ejecución como valores Unix para determinar qué trabajos están listos para ejecutarse.
Los timestamps Unix son la moneda universal del tiempo en los sistemas de software — la única representación inequívoca de un momento que funciona en todos los lenguajes, zonas horarias, bases de datos y APIs. Los dos invariantes a recordar: siempre almacena como UTC (los timestamps son inherentemente UTC, nunca hora local), y siempre sé explícito sobre segundos vs. milisegundos (13 dígitos significa milisegundos, 10 significa segundos). Un conversor de timestamps es un compañero de depuración esencial — cuando una API devuelve 1719792000 y necesitas saber qué significa eso para tus usuarios, una conversión con un clic a hora local elimina toda ambigüedad.