Timestamps Unix: o que o número significa e como lê-lo

Um timestamp Unix é um número só: a contagem de segundos desde as 00:00:00 UTC de 1º de janeiro de 1970. 1789776000 é 19 de setembro de 2026 à meia-noite UTC. Essa é a definição inteira. Não tem fuso horário dentro dele, nem calendário, nem formatação: só uma contagem corrida a partir de um instante fixo com o qual toda máquina concorda.

Esse instante fixo se chama época Unix (epoch). Valores anteriores a ele são negativos, valores posteriores sobem de um em um a cada segundo e, como a coisa toda é aritmética em vez de data, dois timestamps podem ser comparados, ordenados e subtraídos sem que ninguém precise saber quantos dias tem fevereiro.

Por que contar segundos em vez de guardar uma data?

Porque inteiros se comportam e datas não. Os meses vão de 28 a 31 dias. Anos bissextos acontecem a cada quatro anos, exceto a cada cem, exceto a cada quatrocentos. Os relógios adiantam e atrasam duas vezes por ano em alguns países e nunca em outros, e os países mudam de ideia sobre em qual grupo estão. Datas escritas como texto são piores ainda: 03/04/2026 são dois dias diferentes dependendo de quem escreveu.

Um timestamp escapa de tudo isso. "Qual veio primeiro" é uma comparação. "Quanto tempo passou entre os dois" é uma subtração. Ordenar um log é ordenar números. O valor cabe em 8 bytes, sobrevive a ser escrito em um arquivo ou em uma URL sem escape, e qualquer coisa capaz de ler um inteiro consegue lê-lo.

O preço é que uma pessoa não consegue lê-lo, e que um timestamp só pode significar um instante. Ele não consegue expressar "9 da manhã, seja lá o que isso signifique em Madri em março que vem", que é uma coisa real que os calendários precisam guardar e um motivo real pelo qual um timestamp às vezes é a ferramenta errada.

Como ler um de cabeça

Você não vai chegar ao minuto, mas consegue o ano e o mês aproximado em duas divisões.

1. Divida por 86.400, o número de segundos que um dia tem. Isso te dá os dias desde 1º de janeiro de 1970. O resto são os segundos depois da meia-noite UTC.
2. Divida os dias por 365,25 para os anos desde 1970. Some isso a 1970 para chegar ao ano; a fração que sobra, vezes 12, é mais ou menos o mês.

Pegue 1789776000. Dividido por 86.400 dá exatamente 20.715 dias, sem nada de resto, então ele cai bem na meia-noite UTC. 20.715 ÷ 365,25 dá 56,7, então 1970 + 56 dá 2026, e 0,7 × 12 o coloca por volta do nono mês. A resposta real é meia-noite UTC de 19 de setembro de 2026, perto o suficiente para conferir de olho uma linha de log.

Vale a pena decorar alguns pontos de referência, porque eles deixam você situar qualquer número na hora:

Quando o minuto exato importa, faça direito. Cole o número no conversor de timestamp e ele diz qual unidade deduziu pela quantidade de dígitos, e depois te dá a hora local, a UTC, as duas formas ISO 8601 e a que distância de agora está aquele instante. Ele roda dentro da página, então o valor não vai a lugar nenhum.

Segundos, milissegundos ou outra coisa?

É daqui que sai a maior parte dos bugs de timestamp. As ferramentas Unix, a maioria dos bancos de dados SQL e um monte de APIs contam segundos inteiros. JavaScript, Java e tudo que descende deles contam milissegundos. Go e alguns sistemas de tracing contam nanossegundos. A documentação chama todos eles de "o timestamp".

Conte os dígitos. Para qualquer data perto do presente, o comprimento entrega:

Esses comprimentos são estáveis por uma vida inteira. Um timestamp em segundos tem 10 dígitos desde 9 de setembro de 2001 e continua assim até 2286.

Os dois jeitos de errar não são igualmente visíveis. Passe milissegundos para algo que espera segundos e você vai parar quase 57.000 anos no futuro, o que alguém percebe dentro de uma hora. Passe segundos para algo que espera milissegundos e você vai parar em janeiro de 1970: new Date(1789776000) em JavaScript é 21 de janeiro de 1970, não setembro de 2026. Essa é uma resposta errada com cara de plausível, que sobe caladinha para o topo de toda lista ordenada e nunca lança erro. Se uma data no seu app mostra 1970, você errou por um fator de 1000.

Um timestamp Unix tem fuso horário?

Não, embora muito código seja escrito como se tivesse. O número é definido em relação ao UTC, mas não carrega um fuso do jeito que uma data formatada carrega. Ele nomeia um instante. O fuso é aplicado na hora de exibir, e é por isso que o mesmo timestamp mostra 09:00 em Londres e 17:00 em Tóquio e as duas telas estão certas.

O estrago acontece no sentido contrário. Alguém lê os dígitos de um relógio de parede local, converte sem informar o offset e guarda o resultado. O instante guardado passa a estar errado pelo tamanho do offset, e o tamanho do erro muda duas vezes por ano quando o horário de verão mexe nos relógios. Se o valor veio do calendário de uma pessoa e não do relógio de uma máquina, guarde ao lado dele o nome do fuso — Europe/Madrid, não +01:00. Um offset é um fato sobre uma data; um fuso é uma regra.

Onde você vai esbarrar em um

• Tokens. Os campos exp, iat e nbf de um JWT são segundos Unix, e é por isso que o que tem dentro de um JWT parece uma parede de números de dez dígitos.
• O shell. date +%s imprime o timestamp atual em segundos no Linux e no macOS.
• Bancos de dados. O FROM_UNIXTIME() do MySQL e o to_timestamp() do PostgreSQL recebem segundos.
• Planilhas. Excel e Google Sheets contam dias a partir de outro zero, então a conversão é =A1/86400+25569, formatado como data. O resultado é UTC.
• Identificadores. O UUID versão 7 carrega um timestamp de 48 bits em milissegundos nos seus primeiros seis bytes, que é justamente a razão de ser dele: os IDs se ordenam por data de criação.

O que quebra: 2038, datas negativas e segundos bissextos

2038. Um contador de 32 bits com sinal chega ao limite em 2.147.483.647 segundos, que são 03:14:07 UTC de 19 de janeiro de 2038. Um segundo depois ele dá a volta para um número negativo e a data passa a ser dezembro de 1901. Seu notebook está bem — o tempo de 64 bits cobre cerca de 292 bilhões de anos em cada direção — mas ainda há valores de 32 bits em firmware embarcado, em formatos de arquivo antigos e em colunas de banco de dados. O tipo TIMESTAMP do MySQL é limitado exatamente àquele instante de 2038 enquanto o DATETIME não é, então a data final de uma hipoteca ou o vencimento de um certificado guardados na coluna errada já estão quebrados hoje.

Valores negativos. Uma data de nascimento em 1965 é um timestamp negativo perfeitamente válido, e mesmo assim muito software recusa do mesmo jeito: colunas sem sinal, algumas bibliotecas de data e muitas APIs rejeitam qualquer coisa abaixo de zero. Teste datas anteriores a 1970 em vez de supor que funcionam.

Segundos bissextos. O POSIX define todo dia como exatamente 86.400 segundos, então os 27 segundos bissextos inseridos no tempo civil entre 1972 e o último deles, em 31 de dezembro de 2016, simplesmente não aparecem na contagem. A vantagem é que converter um timestamp em data é aritmética sem tabela de consulta. O custo é que um timestamp Unix não consegue nomear um segundo bissexto de jeito nenhum, e sistemas diferentes discordam sobre o que acontece durante um.

Precisão. Um timestamp em segundos não consegue distinguir dois eventos no mesmo segundo. Se você está ordenando eventos, isso importa, e é o motivo de sempre para recorrer aos milissegundos.

Quando um timestamp é a resposta errada

Use um para qualquer coisa que aconteceu: linhas de log, campos de data de criação, expiração de token, timestamps de cache. Não use um para uma data sem hora — um aniversário, a data de uma fatura, um feriado. Guardar "14 de julho" como timestamp te obriga a escolher uma meia-noite em algum fuso, e vai ser o dia errado para alguém. Ali o tipo certo é uma string YYYY-MM-DD.

O mesmo vale para durações. Subtrair dois timestamps dá segundos, e transformar segundos em "dois meses e quatro dias" exige regras de calendário que o timestamp jogou fora de propósito. Para esse tipo de pergunta uma calculadora de diferença entre datas é o caminho mais curto, e contar os dias entre duas datas explica por que a resposta depende de qual ponta você inclui.

Última atualização 19 de setembro de 2026