Conversor de Timestamp Unix a Fecha

Segundos, milisegundos y todo lo que hay por debajo

El tiempo Unix se define en segundos. El Date de JavaScript trabaja en milisegundos. Casi todos los errores de fechas en una base de código mixta empiezan en esa frontera.

Los síntomas se reconocen en cuanto los conoces. Un valor en segundos entregado a algo que espera milisegundos cae en la madrugada del 1 de enero de 1970: si una fecha de tu interfaz aparece como 1970, el motivo es este prácticamente siempre. Un valor en milisegundos leído como segundos cae hacia el año 55.000, lo que suele detectarse, pero no siempre, porque hay código de visualización que lo muestra sin quejarse.

Aquí la unidad se deduce por el número de dígitos, una heurística pero predecible y explicable: una marca de tiempo actual tiene 10 dígitos en segundos, 13 en milisegundos, 16 en microsegundos y 19 en nanosegundos, y los rangos no se solapan para ninguna fecha con la que alguien trabaje realmente. La unidad elegida se muestra en lugar de darse por hecha, y puedes cambiarla. Las marcas en microsegundos aparecen en Postgres y en las trazas de Chrome; en nanosegundos, en Go, Prometheus e InfluxDB. Los valores en nanosegundos superan lo que un número de JavaScript puede representar con exactitud, así que la conversión se hace con BigInt.

Lo que una marca de tiempo no contiene

Una marca de tiempo Unix es un instante y nada más. No lleva zona horaria, ni desplazamiento, ni calendario. Dos personas que leen la misma marca en Tokio y en Lisboa están viendo el mismo momento y anotarán correctamente horas locales distintas, lo cual es una ventaja: un instante no es ambiguo, algo que una hora local nunca consigue.

La consecuencia es que una marca de tiempo no te dice qué día era en un lugar concreto, y convertirla en fecha exige elegir una zona. Por eso todas las salidas de aquí indican su zona, con la hora UTC siempre junto a tu hora local para poder compararlas directamente.

También significa que una marca de tiempo es la forma equivocada de guardar algo intrínsecamente local. Una reunión semanal a las 09:00, un cumpleaños, el horario de una tienda: son horas locales ligadas a una zona y a sus reglas, y guardarlas como instantes las rompe la próxima vez que cambie el desplazamiento de la zona. Guarda la hora local y el nombre de la zona, y calcula el instante cuando lo necesites.

Segundos intercalares

El tiempo Unix se define como si todos los días tuvieran exactamente 86.400 segundos. La Tierra no colabora, así que en UTC se insertan segundos intercalares para mantenerlo alineado con la rotación del planeta: veintisiete desde 1972.

Como la definición no tiene sitio para ellos, el tiempo Unix trata un segundo intercalar repitiendo un valor en lugar de añadir uno. No existe ninguna marca de tiempo Unix que represente el propio segundo intercalar, y por eso la diferencia entre el tiempo Unix y el TAI ha ido creciendo con las décadas en lugar de mantenerse fija. Cualquier código que calcule el tiempo transcurrido restando dos marcas Unix se equivoca en silencio por el número de segundos intercalares que hubo entre ellas, lo que casi nunca importa y de vez en cuando importa muchísimo.

Los grandes proveedores evitan la discontinuidad repartiéndolo (smearing): Google y AWS distribuyen el segundo extra en una ventana antes y después del evento para que los relojes nunca repitan un valor, a costa de ir ligeramente lentos durante un día. Ten en cuenta que esos relojes no coinciden con los que no lo reparten durante esa ventana, algo que conviene saber si comparas marcas de tiempo entre proveedores.

2038 y los otros límites

Un entero de 32 bits con signo se agota a las 03:14:07 UTC del 19 de enero de 2038, y el segundo siguiente vuelve a diciembre de 1901. Todo lo que siga guardando tiempo Unix en un campo de 32 bits - sistemas embebidos, formatos de archivo antiguos, columnas de base de datos que nunca se ampliaron - fallará en ese momento. Por eso aquí se señalan las marcas posteriores a esa fecha. El almacenamiento de 64 bits lleva el límite mucho más allá de la edad del universo y es lo que usan los sistemas actuales.

El almacenamiento de 32 bits sin signo desplaza el límite a 2106, a cambio de no poder representar nada anterior a 1970. Las marcas negativas funcionan aquí: -86400 es el 31 de diciembre de 1969, y las fechas hasta el inicio del calendario gregoriano se convierten sin problema. El Date de JavaScript tiene su propio techo en 8,64e15 milisegundos a cada lado de la época, unos 273.000 años, y los valores que lo superan se indican como fuera de rango en lugar de mostrarse como Invalid Date.

Los formatos de texto y cuál conviene emitir

ISO 8601 es el estándar internacional para escribir fechas y horas, y RFC 3339 es el perfil más estricto de ese estándar que usan los protocolos de internet. La forma de RFC 3339 - 2026-03-14T09:30:00Z, o con un desplazamiento como +09:00 - es la que conviene emitir desde una API, porque se ordena correctamente como texto, no es ambigua y se interpreta en todas partes.

La Z significa UTC, y un desplazamiento como +09:00 significa una diferencia fija respecto de él. Ninguno de los dos es una zona horaria. Asia/Tokyo sí es una zona horaria: un conjunto de reglas que indica cuál es el desplazamiento en cualquier fecha dada, incluido el historial de cambios. Un desplazamiento te dice qué marcaba el reloj; solo el nombre de la zona te dice cuándo volverá a marcar eso en el futuro.

Formatos que conviene evitar en los datos: cualquiera con año de dos dígitos, cualquiera que use barras, y las fechas RFC 2822 de las cabeceras de correo, que arrastran abreviaturas de zona ya obsoletas. Las abreviaturas son lo peor de todo: CST es Central Standard Time en América del Norte, pero también China Standard Time y Cuba Standard Time, e IST abarca India, Irlanda e Israel.

Guardar el tiempo en una base de datos

El tipo timestamptz de PostgreSQL es el que la mayoría de las aplicaciones necesita. A pesar del nombre, no guarda una zona: convierte la entrada a UTC al escribir y la muestra en la zona de la sesión al leer, que es exactamente el comportamiento que quieres para un instante. El timestamp simple, en cambio, guarda el texto de reloj de pared que le diste sin zona alguna, y comparar dos valores así de orígenes distintos produce un sinsentido silencioso.

El DATETIME de MySQL se comporta como el tipo simple, y TIMESTAMP convierte a UTC pero está limitado al rango de 32 bits que termina en 2038, una restricción real para cualquier sistema que guarde fechas futuras. SQLite no tiene ningún tipo de fecha y guarda la convención que elijas, normalmente texto ISO 8601 o un entero.

La disciplina que sobrevive a todo esto es guardar los instantes en UTC, convertir en los bordes y mantener la zona del usuario en una columna aparte cuando haya que mostrar o programar algo para él. Cuando un valor es de verdad una hora local de reloj de pared - el horario de una tienda, una reunión recurrente a las 09:00 -, guarda la hora local y el nombre de la zona, y calcula el instante cuando lo necesites, porque el desplazamiento puede cambiar por ley.

Los relojes no coinciden, y algunos van hacia atrás

El reloj de pared de una máquina lo ajusta NTP, lo que significa que puede saltar hacia adelante o retroceder. Medir una duración restando dos lecturas de ese reloj produce, por tanto, tiempos negativos de vez en cuando y tiempos equivocados con regularidad. Los relojes monotónicos existen para esto: solo avanzan, y son los que usan performance.now, clock_gettime con CLOCK_MONOTONIC y todas las bibliotecas de benchmarking.

Entre máquinas el problema es peor, porque dos servidores nunca están sincronizados con exactitud. Ordenar los eventos de un sistema distribuido por sus marcas de tiempo produce secuencias que contradicen la causalidad - una respuesta registrada antes del mensaje que contesta -, y por eso existen los relojes lógicos y los números de secuencia.

Para aplicaciones corrientes el consejo práctico es más modesto: no uses una marca de tiempo como identificador único, no supongas que dos eventos con la misma marca ocurrieron a la vez, y cuenta con un desfase de al menos unos segundos al comparar cualquier cosa registrada en máquinas distintas. La validación de tokens admite una tolerancia de desfase precisamente por esta razón.

Mostrarle una hora a una persona

Un instante almacenado hay que mostrarlo en la zona de quien lee, en el formato de su región y en su idioma. En JavaScript, la API Intl.DateTimeFormat hace las tres cosas a partir de la configuración del navegador, y se encarga de los detalles que la gente equivoca cuando los resuelve a mano: los nombres de los meses en el idioma correcto, el orden correcto de día y mes, y el reloj de doce o veinticuatro horas según la costumbre del lugar y no según la preferencia de quien programa.

Los tiempos relativos - hace tres horas, en dos días - resultan más cercanos para los eventos recientes y peores para los antiguos, porque nadie puede hacer nada con un hace 431 días. El patrón habitual es usar el relativo durante uno o dos días y pasar después a una fecha absoluta, dejando la marca completa disponible al pasar el cursor o al mantener pulsado.

Hay dos detalles que marcan una diferencia visible. Muestra las fechas en la zona del usuario y no en la del servidor, lo que implica enviar un instante y formatearlo en el cliente en lugar de armar la cadena en el servidor. Y etiqueta con la zona todo lo que pueda ser ambiguo, porque una hora de reunión sin zona es la forma más segura de que alguien llegue una hora tarde.

Fechas que no existen y otros casos límite

Programar cualquier cosa a las 02:30 en una zona con horario de verano garantiza un incidente anual: esa hora no existe en el cambio de primavera y ocurre dos veces en el de otoño. Las tareas que deben ejecutarse exactamente una vez van en UTC, o fuera de la franja de una a tres donde se producen los cambios.

La aritmética de calendario tiene sus propias trampas. Sumar un mes al 31 de enero no tiene una única respuesta correcta, y las bibliotecas se reparten entre el 28 de febrero y el 3 de marzo. Sumar 24 horas no es lo mismo que sumar un día cuando hay un cambio de por medio. Los años bisiestos requieren la regla completa - divisible entre cuatro, salvo los siglos, salvo los divisibles entre 400 - y el 29 de febrero rompe la lógica de aniversarios cada cuatro años.

Y los límites son reales. El tiempo de 32 bits con signo termina el 19 de enero de 2038, algo que todavía importa en dispositivos embebidos y en columnas antiguas de bases de datos; el Date de JavaScript cubre unos 273.000 años a cada lado de 1970 y reporta como inválido cualquier valor más allá. Vale la pena probar ambos límites si tus datos incluyen fechas muy lejanas en el futuro, como suele ocurrir en sistemas hipotecarios, de pensiones y de archivo.