Skip to navigation
Conceptos

Zonas horarias

Qué valor mandar en timezone, por qué no sirve un desfase, y la lista por país.

Algunos endpoints piden un campo timezone. Por ejemplo, el de enviar marcajes de asistencia. El valor es el nombre de una zona horaria IANA: la base de zonas que usan los sistemas operativos y todos los lenguajes de programación.

{ "timezone": "America/Mexico_City" }

La regla corta

1

Forma Área/Ciudad

America/Lima, America/Argentina/Buenos_Aires, Europe/Madrid. La única excepción es UTC.

2

Mayúsculas y minúsculas exactas

America/Mexico_City sí; america/mexico_city no. Hay sistemas que aceptan la versión en minúsculas, la API no.

3

La zona del lugar donde se marcó

No la del servidor que hace la llamada ni la de la casa matriz: la de la sede o el dispositivo donde estaba la persona.

Qué sirve y qué no

Valor¿Sirve?Por qué
America/Mexico_City✅Nombre IANA correcto
America/Argentina/Buenos_Aires✅Algunos países llevan tres niveles
UTC✅Solo si de verdad querés UTC: el día se calcula en UTC, no en el local
america/mexico_city❌Las mayúsculas cuentan
-06:00, UTC-6, GMT-6❌Un desfase no es una zona (ver abajo)
CST, EST, ART❌Las abreviaturas son ambiguas: CST es Central de EE. UU. y también China
America/Buenos_Aires❌Es un alias viejo. Usá America/Argentina/Buenos_Aires
Mexico City, Lima❌Falta el área y el guion bajo
""❌Es obligatorio
Etc/GMT+6⚠️ EvitarEs válido pero el signo va al revés: Etc/GMT+6 es UTC−6

Un valor que no sirve se rechaza con 422, antes de procesar nada.

Por qué se pide la zona y no un desfase

El desfase de un lugar cambia en el año. Chile, Paraguay hasta 2024, Estados Unidos y España cambian de hora dos veces por año. Si mandás -04:00 para Santiago, en verano estás una hora corrido. America/Santiago da la hora correcta para cualquier fecha.

También cambia por ley. México eliminó el horario de verano en 2022, salvo la franja fronteriza. Con el nombre IANA eso ya está resuelto, sin que tengas que cambiar nada.

Para qué se usa

En el envío de marcajes, marked_at y timezone van juntos y cada uno decide una cosa distinta:

  • marked_at fija el instante exacto. Lleva su propio desfase (2026-10-06T23:30:00-06:00) o va en UTC con Z (2026-10-07T05:30:00Z). Los dos ejemplos son el mismo instante.
  • timezone decide en qué día local cae ese instante y contra qué horario de turno se compara.

Una marca a las 23:30 del 6 de octubre en Ciudad de México son las 05:30 del 7 en UTC.

  • Con timezone: "America/Mexico_City" la marca es del 6, que es lo correcto.
  • Con timezone: "UTC" la marca cae en el 7, o sea en otra jornada.

Lo mismo con la puntualidad: un turno que entra a las 09:00 se interpreta a las 09:00 de esa zona. Una zona equivocada puede dejar como tarde una entrada que fue puntual.

Para no confundirse, mandá marked_at con el desfase de la misma zona que timezone. Por ejemplo, -06:00 con America/Mexico_City.

Lista por país

Las más usadas, verificadas contra los servidores de la API. Los desfases son los de enero y julio de 2026. Cuando difieren, ese lugar cambia de hora en el año, y por eso hay que mandar el nombre y no el desfase.

PaísZona (timezone)EneroJulio
ArgentinaAmerica/Argentina/Buenos_Aires−03:00−03:00
Argentina (Córdoba)America/Argentina/Cordoba−03:00−03:00
Argentina (Mendoza)America/Argentina/Mendoza−03:00−03:00
BoliviaAmerica/La_Paz−04:00−04:00
Brasil (São Paulo, Río, Brasilia)America/Sao_Paulo−03:00−03:00
Brasil (Nordeste)America/Fortaleza−03:00−03:00
Brasil (Amazonas)America/Manaus−04:00−04:00
Brasil (Mato Grosso)America/Cuiaba−04:00−04:00
Brasil (Acre)America/Rio_Branco−05:00−05:00
Brasil (Fernando de Noronha)America/Noronha−02:00−02:00
ChileAmerica/Santiago−03:00−04:00
Chile (Magallanes)America/Punta_Arenas−03:00−03:00
Chile (Isla de Pascua)Pacific/Easter−05:00−06:00
ColombiaAmerica/Bogota−05:00−05:00
Costa RicaAmerica/Costa_Rica−06:00−06:00
EcuadorAmerica/Guayaquil−05:00−05:00
Ecuador (Galápagos)Pacific/Galapagos−06:00−06:00
El SalvadorAmerica/El_Salvador−06:00−06:00
EspañaEurope/Madrid+01:00+02:00
España (Canarias)Atlantic/Canary+00:00+01:00
Estados Unidos (Este)America/New_York−05:00−04:00
Estados Unidos (Centro)America/Chicago−06:00−05:00
Estados Unidos (Montaña)America/Denver−07:00−06:00
Estados Unidos (Arizona)America/Phoenix−07:00−07:00
Estados Unidos (Pacífico)America/Los_Angeles−08:00−07:00
GuatemalaAmerica/Guatemala−06:00−06:00
HondurasAmerica/Tegucigalpa−06:00−06:00
México (Centro: CDMX, Guadalajara)America/Mexico_City−06:00−06:00
México (Monterrey)America/Monterrey−06:00−06:00
México (Yucatán)America/Merida−06:00−06:00
México (Quintana Roo)America/Cancun−05:00−05:00
México (Chihuahua)America/Chihuahua−06:00−06:00
México (Ciudad Juárez)America/Ciudad_Juarez−07:00−06:00
México (Sonora)America/Hermosillo−07:00−07:00
México (Sinaloa, Nayarit, BCS)America/Mazatlan−07:00−07:00
México (Baja California)America/Tijuana−08:00−07:00
México (Tamaulipas fronterizo)America/Matamoros−06:00−05:00
NicaraguaAmerica/Managua−06:00−06:00
PanamáAmerica/Panama−05:00−05:00
ParaguayAmerica/Asuncion−03:00−03:00
PerúAmerica/Lima−05:00−05:00
Puerto RicoAmerica/Puerto_Rico−04:00−04:00
República DominicanaAmerica/Santo_Domingo−04:00−04:00
UruguayAmerica/Montevideo−03:00−03:00
VenezuelaAmerica/Caracas−04:00−04:00
Sin zona localUTC+00:00+00:00

Si tu sede no está en la tabla, buscá su zona en la lista de zonas IANA. Usá la columna TZ identifier de una fila Canonical: los alias (Link) se rechazan.

Cómo obtener la zona en tu código

Si tu sistema ya guarda la zona de cada sede, mandá ese valor. Para validar uno antes de enviarlo:

from zoneinfo import available_timezones
# Según el sistema, available_timezones() también trae alias viejos
# (America/Buenos_Aires) que la API rechaza: mandá el nombre canónico.
VALID_TIMEZONES = {
    zone for zone in available_timezones() if "/" in zone or zone == "UTC"
}
def is_valid_timezone(value: str) -> bool:
    return value in VALID_TIMEZONES

Intl (navegadores, Node) puede devolver el alias America/Buenos_Aires en vez de America/Argentina/Buenos_Aires, y la API lo rechaza. Si tomás la zona del equipo, normalizala antes de enviarla, como en el ejemplo.

No uses la zona del servidor de tu integración. Suele estar en UTC, o en la zona de la casa matriz. Si un sistema central envía marcas de sedes en distintos países, cada marca lleva la zona de su sede.