Fechas y Fuso Horario¶

Estándar ISO 8601¶

Toda la API Pontotel utiliza el formato ISO 8601 para representar fechas y horarios.

Formatos aceptados¶

Fecha y hora con Fuso¶

Text Only
1 2 3	`YYYY-MM-DDTHH:MM:SS±HH:MM Exemplo: 2025-01-31T08:00:00-03:00`

Parte	Descripción	Ejemplo
`YYYY`	Año con 4 dígitos	`2025`
`MM`	Mes (01-12)	`01`
`DD`	Día (01-31)	`31`
`T`	Separador obligatorio	`T`
`HH:MM:SS`	Hora, minuto, segundo	`08:00:00`
`±HH:MM`	Offset de zona	`-03:00`

Solo fecha¶

Text Only
1 2 3	`YYYY-MM-DD Exemplo: 2025-01-31`

Usado para campos como data_admissao, data_inicio_ferias, etc.

UTC (Zero offset)¶

Text Only
1	`2025-01-31T11:00:00Z`

El Z equivale a +00:00 (UTC).

Zona horaria¶

Siempre informe la zona horaria

En campos de fecha/hora, siempre informe el offset de zona horaria. La ausencia de la zona puede generar marcas en horarios incorrectos.

Fusos Comunes en Brasil¶

Región	Offset	Ejemplo
Brasilia (BRT)	-03:00	`2025-01-31T08:00:00-03:00`
Acre (ACT)	-05:00	`2025-01-31T06:00:00-05:00`
Fernando Noronha	-02:00	`2025-01-31T09:00:00-02:00`

Consistencia interna

Pontotel almacena todos los horarios en UTC internamente, pero vuelve los valores con la zona original informado en el registro del empleador.

Ejemplos Prácticos en las peticiones¶

Filtrar marcas por período¶

HTTP
1	`GET /marcacoes/?data_inicio=2025-01-01T00:00:00-03:00&data_fim=2025-01-31T23:59:59-03:00`

Crear marcado con zona correcta¶

JSON
{
  "empregado_id": 123,
  "data_hora": "2025-01-31T08:05:00-03:00",
  "tipo": "entrada"
}

Manipulación en código¶

PythonJavaScript

Python
from datetime import datetime
import pytz

# Criar datetime com fuso de Brasília
brasilia = pytz.timezone("America/Sao_Paulo")
agora = datetime.now(brasilia)

# Formatar para API
data_hora = agora.isoformat()  # "2025-01-31T08:05:00-03:00"

JavaScript
// Usar biblioteca date-fns-tz para fusos
import { formatISO } from 'date-fns';
import { toZonedTime } from 'date-fns-tz';

const timeZone = 'America/Sao_Paulo';
const date = toZonedTime(new Date(), timeZone);
const dataHora = formatISO(date); // "2025-01-31T08:05:00-03:00"