O Que É um Unix Timestamp? Guia com Exemplos Reais
Um Unix timestamp é o número de segundos que se passaram desde 1º de janeiro de 1970, às 00:00:00 UTC. Esse instante de referência é chamado de Unix Epoch, e qualquer outro momento no tempo pode ser representado como um único número inteiro contando a partir dele. É por isso que você vê valores como 1700000000 espalhados em colunas de banco de dados, respostas de API e arquivos de log.
O que é de fato um Unix timestamp
Na prática, um timestamp Unix é só um contador. Ele começa em zero no instante da Epoch e sobe um a um, segundo a segundo, sem parar. Não existe formatação, não existe fuso horário embutido, não existe nome de mês. É um inteiro puro, e é exatamente essa simplicidade que faz dele o formato padrão para guardar datas em sistemas de computador.
A vantagem sobre uma string de data formatada (tipo “14/11/2023 22:13:20”) é dupla. Primeiro, comparar dois timestamps é uma operação numérica trivial: para saber qual evento aconteceu primeiro, basta ver qual número é menor. Ordenar uma lista de registros por data vira uma ordenação numérica comum, sem precisar de nenhuma lógica de calendário. Segundo, um timestamp não carrega ambiguidade de fuso horário: o número 1700000000 significa o mesmo instante exato em qualquer lugar do planeta, seja em São Paulo, em Tóquio ou em Londres. A confusão só aparece quando você decide exibir esse instante em um relógio de parede específico, e isso é assunto para mais adiante neste artigo.
Exemplo prático: interpretando valores reais de timestamp
Nada como ver o número virando data para o conceito grudar. A tabela abaixo mostra cinco timestamps e a data e hora em UTC que cada um representa:
| Unix timestamp (segundos) | Data e hora em UTC |
|---|---|
| 0 | 1º de janeiro de 1970, 00:00:00 UTC (a própria Epoch) |
| 1000000000 | 9 de setembro de 2001, 01:46:40 UTC |
| 1700000000 | 14 de novembro de 2023, 22:13:20 UTC |
| 2000000000 | 18 de maio de 2033, 03:33:20 UTC |
| 2147483647 | 19 de janeiro de 2038, 03:14:07 UTC |
Repare no salto entre as linhas: cada bilhão de segundos a mais empurra a data uns 11 anos e meio para frente, porque um ano tem aproximadamente 31,5 milhões de segundos. É por isso que 1700000000, um valor bem comum em exemplos de API e em colunas created_at recentes, cai em 14 de novembro de 2023: são 1,7 bilhão de segundos acumulados desde 1970, o equivalente a pouco mais de 53 anos e meio de contagem ininterrupta. O último valor da tabela, 2147483647, não é um número escolhido ao acaso, ele marca o limite de um inteiro de 32 bits com sinal, e você vai ver por que isso importa na seção sobre erros comuns.
Segundos ou milissegundos? Como diferenciar
Esse é o erro clássico que pega até desenvolvedor experiente. Timestamps em segundos, o padrão usado por chamadas de sistema Unix, cron e a grande maioria das ferramentas de linha de comando do Linux, têm hoje 10 dígitos, como 1700000000. Timestamps em milissegundos, que é o que Date.now() do JavaScript e muitas APIs web retornam, têm 13 dígitos para representar o mesmo instante: 1700000000000, ainda 14 de novembro de 2023.
A regra prática é contar os dígitos. Se o valor tem 10 algarismos, provavelmente está em segundos; se tem 13, está em milissegundos. O problema real acontece quando você cola um valor em milissegundos numa ferramenta que espera segundos: o sistema multiplica por mil o que já era o número certo, e a data calculada dispara para um futuro distante, muitas vezes séculos à frente do que você esperava ver na tela.
Convertendo um timestamp em data
Se você está com um número como 1700000000 numa mão e uma dúvida na outra, cole o valor abaixo. A ferramenta detecta sozinha se está em segundos ou milissegundos e mostra a data em UTC, no seu horário local e em formato ISO 8601.
Convertendo uma data em timestamp
O caminho inverso é igualmente comum. Você quer agendar um job de cron para rodar num instante específico, definir a expiração (exp) de um JWT, ou mandar um parâmetro scheduled_at para uma API, e para isso precisa transformar uma data legível, tipo “25 de dezembro de 2024, meia-noite”, num número que o sistema entenda.
Erros comuns e casos especiais
Confundir segundos com milissegundos. Já foi explicado na seção acima, mas vale reforçar: é o erro mais frequente de todos, e o sintoma é sempre o mesmo, uma data calculada absurdamente no futuro. Antes de desconfiar da sua lógica de conversão, conte os dígitos do número original.
O problema do ano 2038. Sistemas que armazenam o timestamp como um inteiro de 32 bits com sinal só conseguem representar até 2147483647, exatamente 19 de janeiro de 2038, às 03:14:07 UTC. Depois desse instante, o contador estoura (overflow) e vira um número negativo, o que quebra qualquer lógica de data que dependa daquele valor, fazendo o sistema “pensar” que está em 1901. Sistemas modernos de 64 bits não têm esse teto: o espaço de representação é astronomicamente maior, então na prática esse limite deixou de ser um problema para a maioria das aplicações novas, mas continua vivo em software legado e em alguns sistemas embarcados.
Achar que o timestamp tem fuso horário. Um Unix timestamp não tem fuso horário nenhum, ele é um instante absoluto no tempo. A confusão nasce na hora de exibir esse número: você pode formatá-lo em UTC ou converter para o horário local de qualquer fuso. Duas pessoas em fusos diferentes olhando para o mesmo timestamp 1700000000 vão ver horários no relógio diferentes entre si (uma pode ver 19h, outra pode ver 22h), mas ambas estão olhando exatamente para o mesmo instante no tempo, não para instantes diferentes.
Esquecer que timestamps negativos existem. Datas anteriores a 1970 são representadas por números negativos. O valor -86400 (86400 é o número de segundos em um dia) corresponde a 31 de dezembro de 1969, um dia antes da Epoch. Nem toda ferramenta ou sistema aceita valores negativos, então vale conferir a documentação antes de tentar representar, por exemplo, uma data de nascimento de alguém nascido antes de 1970.
Perguntas frequentes
O que é um Unix timestamp? É o número de segundos que se passaram desde 1º de janeiro de 1970, 00:00:00 UTC, a chamada Unix Epoch. É a forma universal com que bancos de dados, APIs e a maioria das linguagens de programação armazenam e transmitem pontos no tempo.
Como sei se meu timestamp está em segundos ou milissegundos?
Conte os dígitos. Timestamps em segundos têm hoje 10 dígitos (como 1700000000). Timestamps em milissegundos têm 13 dígitos para o mesmo instante (como 1700000000000). Date.now() do JavaScript retorna milissegundos; a maioria das ferramentas de sistema Unix, cron e bibliotecas de backend em outras linguagens trabalha em segundos.
O que é o problema do ano 2038? É o limite dos sistemas que guardam o timestamp num inteiro de 32 bits com sinal: eles estouram em 19 de janeiro de 2038, às 03:14:07 UTC, e o contador vira um número negativo, quebrando qualquer cálculo de data que dependa dele. Sistemas modernos de 64 bits não têm essa limitação prática.
Dá para converter uma data anterior a 1970? Sim, usando um timestamp negativo. Por exemplo, -86400 representa 31 de dezembro de 1969, exatamente um dia antes da Epoch. Nem todo sistema aceita valores negativos, então é bom checar a documentação da ferramenta ou da API antes de depender disso.
Por que bancos de dados guardam datas como Unix timestamp em vez de uma string formatada?
Porque um inteiro é mais compacto, mais rápido de comparar e ordenar, e não carrega ambiguidade de fuso horário. Duas linhas com created_at em timestamp podem ser ordenadas com uma simples comparação numérica, sem nenhuma lógica de calendário envolvida, e o valor significa o mesmo instante independentemente de onde o servidor do banco de dados está rodando.