Pular para o conteúdo
DevTools/Devs

Segundos ou milissegundos? Como reconhecer e converter um timestamp Unix

O que é um timestamp Unix, como diferenciar segundos de milissegundos pela quantidade de dígitos e como converter em JavaScript, Python e SQL sem errar a data.

Por Felipe YamaokaPublicado em 5 de novembro de 20265 min de leitura

Um número que na verdade é uma data

APIs, bancos de dados, logs e tokens adoram guardar tempo como um número só:

json
{ "createdAt": 1793880000, "updatedAt": 1793880000000 }

Os dois valores representam o mesmo instante: 5 de novembro de 2026 às 12:00 UTC, ou 9:00 no horário de Brasília. O primeiro está em segundos, o segundo em milissegundos. Trocar um pelo outro é um dos bugs de data mais comuns que existem, e o resultado parece absurdo à primeira vista: um pedido criado em janeiro de 1970, ou uma sessão que só expira no ano 58.815.

Este guia explica o que é um timestamp Unix, como diferenciar as unidades de bate-pronto e como converter com segurança nas linguagens do dia a dia.

O que é um timestamp Unix

Um timestamp Unix conta o tempo que passou desde a época Unix: 1º de janeiro de 1970 às 00:00:00 UTC. Zero é esse momento exato, 86400 é um dia depois e números negativos são datas anteriores a 1970, então -86400 é 31 de dezembro de 1969.

Duas propriedades explicam a popularidade:

  • Não tem fuso horário. O número representa o mesmo instante em São Paulo, Lisboa e Tóquio. O fuso só entra quando você transforma o número numa data para alguém ler.
  • É fácil comparar e ordenar. Mais tarde é maior. A diferença entre dois timestamps é uma duração.

A definição original do Unix conta segundos. Várias plataformas, a começar pelo JavaScript, contam milissegundos. Alguns sistemas vão além: o time.time_ns() do Python devolve nanossegundos e muitos bancos guardam microssegundos internamente. Na prática, segundos e milissegundos são os dois que aparecem em JSON.

Um detalhe: o tempo Unix ignora os segundos bissextos. Todo dia conta como exatamente 86.400 segundos. Para quase todo código de aplicação, é exatamente isso que você quer.

Como diferenciar segundos de milissegundos

Para datas próximas de hoje, a quantidade de dígitos entrega:

  • 10 dígitos, como 1793880000: segundos.
  • 13 dígitos, como 1793880000000: milissegundos.

A regra quebra para datas muito distantes, por isso as ferramentas usam um limite. O Conversor de Timestamp Unix deste site trata qualquer valor absoluto a partir de 100.000.000.000 (1e11) como milissegundos e o que estiver abaixo como segundos. O corte é seguro nos dois sentidos: 1e11 segundos seria o ano 5138, e 1e11 milissegundos é março de 1973, então nenhuma data realista em segundos chega a esse tamanho e quase nenhuma data em milissegundos fica abaixo dele.

Na dúvida, converta dos dois jeitos e veja qual faz sentido:

  • 1793880000 lido como segundos: 5 de novembro de 2026, 12:00 UTC.
  • 1793880000 lido como milissegundos: 21 de janeiro de 1970.
  • 1793880000000 lido como milissegundos: 5 de novembro de 2026, 12:00 UTC.
  • 1793880000000 lido como segundos: o ano 58.815.

Uma data em janeiro de 1970 quase sempre significa segundos lidos como milissegundos. Uma data dezenas de milhares de anos à frente significa o contrário.

Convertendo em JavaScript

O Date do JavaScript trabalha com milissegundos, então segundos precisam ser multiplicados por 1000:

js
const seconds = 1793880000;
const date = new Date(seconds * 1000);

date.toISOString(); // "2026-11-05T12:00:00.000Z"

Para o caminho inverso, divida e arredonde para baixo:

js
const nowMs = Date.now();               // milissegundos
const nowSeconds = Math.floor(nowMs / 1000);

Prefira Math.floor a Math.round aqui. Arredondar pode jogar o timestamp meio segundo para o futuro, o que basta para um servidor rigoroso achar que um token foi "emitido no futuro".

Para mostrar a data para uma pessoa, formate no fuso dela com Intl:

js
new Intl.DateTimeFormat("pt-BR", {
  dateStyle: "long",
  timeStyle: "short",
  timeZone: "America/Sao_Paulo",
}).format(new Date(1793880000 * 1000));
// "5 de novembro de 2026 às 09:00"

Convertendo em Python

O datetime do Python trabalha com segundos, com frações para o que for menor. Sempre informe o fuso, senão você ganha uma data "ingênua" no horário local da máquina que roda o código:

python
from datetime import datetime, timezone

datetime.fromtimestamp(1793880000, tz=timezone.utc)
# datetime.datetime(2026, 11, 5, 12, 0, tzinfo=datetime.timezone.utc)

datetime.fromtimestamp(1793880000000 / 1000, tz=timezone.utc)  # a partir de milissegundos

E de volta:

python
int(datetime(2026, 11, 5, 12, 0, tzinfo=timezone.utc).timestamp())
# 1793880000

Convertendo em SQL

Cada banco tem a sua função, e quase todas esperam segundos:

sql
-- PostgreSQL
SELECT to_timestamp(1793880000);
SELECT extract(epoch FROM now())::bigint;

-- MySQL
SELECT FROM_UNIXTIME(1793880000);
SELECT UNIX_TIMESTAMP();

-- SQLite
SELECT datetime(1793880000, 'unixepoch');

Se a coluna guarda milissegundos, divida por 1000 antes de chamar essas funções. No MySQL, lembre também que o FROM_UNIXTIME devolve o horário no fuso da sessão, e não em UTC.

O ano de 2038

Sistemas antigos guardam timestamps em segundos num inteiro de 32 bits com sinal. O maior valor que cabe nele é 2.147.483.647, que corresponde a 19 de janeiro de 2038 às 03:14:07 UTC. Um segundo depois o número estoura e volta para dezembro de 1901. Linguagens e bancos modernos usam números de 64 bits e estão a salvo, mas dispositivos embarcados, formatos de arquivo antigos e colunas INT em bancos de dados ainda podem quebrar. Se você for criar uma tabela hoje, guarde timestamps numa coluna de 64 bits ou use o tipo de data do próprio banco.

Erros comuns

  • Passar segundos para new Date() no JavaScript. O resultado cai em janeiro de 1970.
  • Usar Date.now() onde a API espera segundos, como na claim exp de um JWT. O guia de como ler um JWT mostra como isso faz o token parecer quebrado.
  • Criar datas ingênuas no Python. datetime.fromtimestamp(ts) sem tz depende do fuso local do servidor.
  • Guardar horário local como se fosse timestamp. Um timestamp é sempre UTC. Converta para o horário local só na hora de mostrar.
  • Arredondar para cima. Para passar de milissegundos para segundos, trunque com floor, não com round.
  • Usar colunas de 32 bits para datas que podem passar de 2038.

Resumo

Um timestamp Unix é a quantidade de segundos, ou de milissegundos, desde 1º de janeiro de 1970 em UTC. Dez dígitos costumam ser segundos e treze, milissegundos; na dúvida, converta dos dois jeitos e fique com o que dá uma data plausível. Multiplique ou divida por 1000 na fronteira entre sistemas, mantenha tudo em UTC até mostrar para uma pessoa e guarde timestamps em colunas de 64 bits.

Leia também