Datas e Fuso Horário¶

Padrão ISO 8601¶

Toda a API Pontotel utiliza o formato ISO 8601 para representar datas e horários.

Formatos Aceitos¶

Data e Hora com Fuso¶

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

Parte	Descrição	Exemplo
`YYYY`	Ano com 4 dígitos	`2025`
`MM`	Mês (01-12)	`01`
`DD`	Dia (01-31)	`31`
`T`	Separador obrigatório	`T`
`HH:MM:SS`	Hora, minuto, segundo	`08:00:00`
`±HH:MM`	Offset de fuso	`-03:00`

Apenas Data¶

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`

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

Fuso Horário¶

Sempre informe o fuso horário

Em campos de data/hora, sempre informe o offset de fuso horário. A ausência do fuso pode gerar marcações em horários incorretos.

Fusos Comuns no Brasil¶

Região	Offset	Exemplo
Brasília (BRT)	-03:00	`2025-01-31T08:00:00-03:00`
Acre (ACT)	-05:00	`2025-01-31T06:00:00-05:00`
Fernando de Noronha	-02:00	`2025-01-31T09:00:00-02:00`

Consistência Interna

A Pontotel armazena todos os horários em UTC internamente, mas retorna os valores com o fuso original informado no cadastro do empregador.

Exemplos Práticos nas Requisições¶

Filtrar marcações 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`

Criar marcação com fuso correto¶

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

Manipulação em 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"