La primera decisión de diseño es el formato de entrada y salida. Exige ISO 8601 (por ejemplo, 2026-05-15T16:00:00+09:00) y rechaza entradas que carezcan de información de zona horaria. Aceptar marcas de tiempo sin desfase crea ambigüedad sobre a qué zona pertenece el valor, y esa ambigüedad inevitablemente se filtra en errores que aparecen en producción.
Para la zona de destino, acepta nombres IANA (Asia/Tokyo) en lugar de desfases UTC (+09:00). Los desfases describen la diferencia de un solo instante y no pueden capturar las reglas de horario de verano. America/New_York permite que la API decida si la entrada cae en horario de verano o estándar y aplique el desfase correcto (-4 o -5) automáticamente.
Las transiciones de horario de verano crean tanto tiempos inexistentes como tiempos duplicados. En primavera (por ejemplo, las 2:00 saltan a las 3:00), el rango de 2:00 a 2:59 simplemente no ocurre. En otoño (por ejemplo, las 2:00 retroceden a la 1:00), el rango de 1:00 a 1:59 ocurre dos veces. La API debe abordar ambas situaciones explícitamente en lugar de confiar en los valores predeterminados de la biblioteca.
Para tiempos inexistentes existen tres opciones: devolver un error, redondear hacia adelante al tiempo posterior a la transición (2:30 a 3:00), o redondear hacia atrás al tiempo anterior (2:30 a 1:30). Para tiempos duplicados, pide al cliente qué desfase aplicar o usa por defecto la regla previa a la transición. En cualquier caso, incluye una bandera en la respuesta indicando que se realizó un ajuste, para que los clientes puedan detectarlo y reaccionar cuando sea necesario.
La base de datos de zonas horarias IANA (tzdata) se actualiza entre 3 y 10 veces al año. Cada vez que un país adopta, modifica o elimina el horario de verano, le sigue una nueva versión. Mantener actualizado el tzdata del servidor de la API es un requisito operativo innegociable; de lo contrario, las marcas de tiempo futuras de ciertos países devolverán resultados incorrectos sin que se genere ningún error.
Las actualizaciones de tzdata pueden tener implicaciones de compatibilidad retroactiva. Los nombres de zona a veces se consolidan (Asia/Calcutta a Asia/Kolkata), y los datos históricos a veces se corrigen. El patrón recomendado es aceptar nombres obsoletos como alias de entrada mientras se devuelven siempre los nombres canónicos en las respuestas. Esto permite a los clientes migrar a su ritmo mientras la superficie de la API se mantiene actualizada.
Una API de conversión de zonas horarias debe manejar fechas malformadas, nombres de zona desconocidos, fechas fuera del rango admitido (pasado o futuro muy lejano) y los tiempos de hueco DST mencionados anteriormente. Cada caso de error merece no solo un código de estado HTTP, sino un código de error legible por máquina y un mensaje legible por humanos que ayude al desarrollador a corregir el problema.
Cuidado con la entrada parcialmente válida. Una fecha como 2026-02-30T10:00:00+09:00 (el 30 de febrero no existe) podría ser corregida silenciosamente al 2 de marzo por algunas bibliotecas. El comportamiento seguro de la API es rechazar dicha entrada explícitamente en lugar de autocorregirla; los clientes no deberían ver un procesamiento exitoso contra una fecha que no especificaron. Es mejor un error hoy que problemas misteriosos de calidad de datos después.
La conversión en sí es computacionalmente barata, pero la caché ayuda bajo carga elevada. Ten cuidado con las claves de caché: la misma marca de tiempo de entrada y zona destino pueden devolver resultados diferentes entre versiones de tzdata. Vincula la invalidación de caché a las actualizaciones de tzdata para que las conversiones obsoletas desaparezcan cuando cambien las reglas subyacentes.
Un endpoint de conversión por lotes que acepte múltiples marcas de tiempo en una sola llamada reduce la sobrecarga de ida y vuelta para los clientes. Una aplicación de calendario que renderiza un mes de eventos en diferentes zonas puede emitir una sola petición por lotes en lugar de 30 peticiones individuales, mejorando tanto la latencia percibida por el cliente como el rendimiento del servidor. Las APIs por lotes también son más fáciles de limitar y medir con precisión que ráfagas de llamadas individuales.
¿Te resultó útil este artículo?
La regla cardinal del manejo de marcas de tiempo en software es almacenar en UTC y mostrar en hora local. Este artículo cubre la lógica detrás de esta práctica, el formato ISO 8601, patrones en JavaScript y Python, los errores más comunes y una estrategia de pruebas que detecta problemas de horario de verano y línea de fecha antes de llegar a producción.
Las tareas cron configuradas en hora local se ejecutan dos veces o se saltan silenciosamente durante las transiciones de horario de verano. Este artículo repasa los modos de fallo, el caso a favor de ejecutar programaciones en UTC, el campo timeZone de Kubernetes CronJob y cómo los planificadores en la nube gestionan el mismo problema.
Elegir entre DATE, TIME, TIMESTAMP y TIMESTAMPTZ determina si tu aplicación maneja correctamente las zonas horarias. Este artículo recorre sistemas de reservas, programación de eventos futuros, registros de auditoría y estrategias de migración para esquemas heredados que ignoraron las zonas horarias.