Unix Timestamps Explicados: Conversão e Armadilhas Comuns

Um Unix timestamp é um dos conceitos mais simples, porém mais mal compreendidos na programação. Trata-se do número de segundos que se passaram desde 1º de janeiro de 1970, 00:00:00 UTC — um momento conhecido como o Unix epoch. Apesar da sua simplicidade, timestamps são uma fonte de bugs relacionados a fusos horários, precisão e overflow.

O Que É o Unix Epoch?

O Unix epoch — 1º de janeiro de 1970, 00:00:00 UTC — foi escolhido como ponto de partida para o tempo Unix. Todo timestamp é medido em relação a esse momento:

Timestamps negativos representam datas anteriores ao epoch. Por exemplo, -86400 é 31 de dezembro de 1969.

Converta timestamps instantaneamente com nosso Conversor de Timestamps.

Segundos vs. Milissegundos

Esta é a fonte de confusão mais comum. Diferentes sistemas utilizam diferentes precisões:

Regra prática: Se o número tem 13 dígitos, é milissegundos. Se tem 10 dígitos, é segundos.

// JavaScript retorna milissegundos
const nowMs = Date.now();          // 1700000000000
const nowSec = Math.floor(nowMs / 1000);  // 1700000000

Tratamento de Fusos Horários

Unix timestamps são sempre UTC. Eles não contêm informação de fuso horário. Na verdade, isso é uma vantagem — fornece um ponto de referência universal.

A confusão surge ao converter timestamps para datas legíveis por humanos:

const ts = 1700000000;
const date = new Date(ts * 1000);

date.toUTCString();      // "Tue, 14 Nov 2023 22:13:20 GMT"
date.toLocaleString();    // Depende do fuso horário local do usuário
date.toISOString();       // "2023-11-14T22:13:20.000Z"

Boa prática: Armazene e transmita timestamps em UTC. Converta para o horário local apenas na camada de apresentação, o mais próximo possível do usuário.

O Problema do Ano 2038

Sistemas Unix tradicionais armazenam timestamps como um inteiro assinado de 32 bits. O valor máximo é 2.147.483.647, que corresponde a 19 de janeiro de 2038, 03:14:07 UTC.

Após esse momento, timestamps de 32 bits sofrem overflow para valores negativos, retornando a 13 de dezembro de 1901. Isso é análogo ao bug do Y2K.

Status atual:

• A maioria dos sistemas modernos usa timestamps de 64 bits (válido até o ano 292 bilhões)
• O kernel Linux está limpo para timestamps de 64 bits desde a versão 5.6 (2020)
• Sistemas embarcados e bancos de dados legados ainda estão em risco
• Se você está desenvolvendo software que lida com datas além de 2038, verifique seu armazenamento de timestamps

Conversão em Diferentes Linguagens

JavaScript

// Timestamp atual (segundos)
const now = Math.floor(Date.now() / 1000);

// Timestamp para Date
const date = new Date(1700000000 * 1000);

// Date para timestamp
const ts = Math.floor(new Date('2023-11-14').getTime() / 1000);

Python

import time, datetime

# Timestamp atual
now = int(time.time())

# Timestamp para datetime
dt = datetime.datetime.fromtimestamp(1700000000, tz=datetime.timezone.utc)

# Datetime para timestamp
ts = int(dt.timestamp())

SQL (PostgreSQL)

-- Timestamp atual
SELECT EXTRACT(EPOCH FROM NOW());

-- Timestamp para data
SELECT TO_TIMESTAMP(1700000000);

-- Data para timestamp
SELECT EXTRACT(EPOCH FROM '2023-11-14'::timestamp);

Armadilhas Comuns

1. Misturar Segundos e Milissegundos

Se uma data aparece como janeiro de 1970, provavelmente você passou segundos onde milissegundos eram esperados (ou vice-versa). Sempre verifique qual precisão a API espera.

2. Ignorar Fusos Horários em Strings de Data

Interpretar "2023-11-14" sem um fuso horário cria a data no fuso horário local, que varia conforme a localização do servidor. Sempre inclua o fuso horário: "2023-11-14T00:00:00Z".

3. Precisão de Ponto Flutuante

Ao armazenar timestamps como números de ponto flutuante, você pode perder precisão além dos milissegundos. Para precisão em microssegundos ou nanossegundos, use inteiros com o multiplicador apropriado.

4. Segundos Intercalares

Unix timestamps não consideram segundos intercalares. Um dia Unix tem sempre exatamente 86.400 segundos, mesmo que dias UTC reais ocasionalmente tenham 86.401 segundos. Para a maioria das aplicações, isso é irrelevante. Para aplicações científicas ou de satélites, use TAI (Tempo Atômico Internacional).

ISO 8601: A Alternativa Legível por Humanos

Enquanto timestamps são ótimos para computação, o ISO 8601 é o padrão para representação de datas legível por humanos:

2023-11-14T22:13:20Z          # UTC
2023-11-14T17:13:20-05:00     # Horário do Leste
2023-11-14                     # Apenas data

A maioria das APIs deve aceitar e retornar strings ISO 8601. Use timestamps internamente para cálculos e armazenamento.

FAQ

Por que o tempo Unix começa em 1º de janeiro de 1970?

A data foi escolhida arbitrariamente quando o Unix estava sendo desenvolvido nos Bell Labs no início dos anos 1970. Era necessária uma data recente o suficiente para evitar desperdício de bits com datas do passado distante. Como inteiros de 32 bits podem armazenar cerca de 68 anos em cada direção, começar em 1970 cobria datas de 1901 a 2038.

Devo armazenar datas como timestamps ou strings formatadas no meu banco de dados?

Armazene datas como timestamps (inteiro ou tipos datetime nativos) para ordenação, comparação e aritmética eficientes. Strings formatadas são mais difíceis de consultar e ordenar corretamente. A maioria dos bancos de dados possui tipos datetime nativos que lidam bem com isso. Reserve a formatação em string para exibição e respostas de API.

Recursos Relacionados

• Conversor de Timestamps — Converta entre Unix timestamps e datas legíveis por humanos
• Boas Práticas de Formatação JSON — Lidando com datas em respostas JSON
• Guia de UUID — Outro formato comum de identificador com variantes baseadas em tempo