Como converter o tempo Epoch numa data legível
Converter o tempo Epoch numa data são dois passos: descodificar o número como um instante em UTC e depois formatar esse instante no fuso horário de que precisas. Este guia explica o modelo mental, como distinguir segundos de milissegundos e a decisão UTC versus local, e remete-te depois para a receita por linguagem e o conversor de instantes.
Epoch para data são dois passos
Converter um timestamp Epoch numa data legível são sempre os mesmos dois passos: descodificar o número como um instante em UTC e depois formatar esse instante no fuso horário em que o queres mostrar. O próprio número não carrega fuso — é um único momento —, por isso o mesmo valor aparece como uma hora de relógio de parede diferente (às vezes um dia de calendário diferente) consoante o fuso em que o formatas. A tabela abaixo mostra um timestamp apresentado em vários fusos; o resto deste guia cobre a unidade, a escolha do fuso e o código.
| Fuso horário | Data e hora locais para 1700000000 |
|---|---|
| UTC (o instante canónico) | 2023-11-14 22:13:20 · ISO 2023-11-14T22:13:20Z |
| America/New_York | 2023-11-14 17:13:20 (EST) |
| Asia/Tokyo | 2023-11-15 07:13:20 (JST) |
| Australia/Sydney | 2023-11-15 09:13:20 (AEDT) |
O que é o tempo Epoch?
O tempo Epoch (também chamado tempo Unix ou tempo POSIX) é o número de segundos decorridos desde as 00:00:00 UTC de 1 de janeiro de 1970. É o padrão universal para representar instantes na computação. Toda linguagem de programação e sistema operativo o suporta nativamente, o que o torna o formato mais fiável para armazenar e trocar timestamps entre sistemas.
Passo 1 — Reconhecer segundos ou milissegundos
Antes de converter, determina a unidade. Quase sempre se lê pelo número de dígitos, e enganar-se nela é a causa mais comum de uma data errada.
- 10 dígitos (ex.: 1700000000) → segundos desde o epoch Unix
- 13 dígitos (ex.: 1700000000000) → milissegundos desde o epoch Unix
- 16 dígitos → microssegundos; 19 dígitos → nanossegundos
- Na dúvida, verifica se o ano descodificado parece razoável — uma data em 1970 ou num futuro distante significa que a unidade foi mal lida
- O conversor acima deteta a unidade automaticamente
Passo 2 — Descodificar como UTC e depois escolher um fuso
Um timestamp Unix descodifica para um instante exato. Mostrar esse instante em UTC ou num fuso local é uma decisão de apresentação, não uma propriedade do número. Escolhe UTC para tudo o que é orientado a máquinas — logs, APIs, armazenamento em base de dados, comparação entre servidores — e converte para o fuso IANA do utilizador apenas no momento de mostrar uma data a uma pessoa. Identifica sempre um fuso pelo seu nome IANA (America/New_York), nunca por um simples deslocamento, para que o horário de verão seja aplicado por ti.
- Orientado a máquinas (logs, APIs, armazenamento) → mostrar em UTC, ISO 8601 com um Z
- Orientado ao utilizador (prazos, timestamps numa UI) → converter para o fuso IANA do utilizador
- Nunca armazenes uma hora local sem o seu fuso — armazena UTC mais o nome de fuso IANA
A conversão em código
Toda linguagem moderna tem uma função integrada de uma linha que faz os dois passos por ti. O padrão é sempre o mesmo: passa o valor na unidade que a função espera e pede UTC ou um fuso específico. JavaScript e alguns outros estão abaixo; a receita complementar cobre por completo JavaScript, Python, PHP, Java, C#, Go, SQL, Excel e Google Sheets.
- JavaScript: new Date(1700000000 * 1000).toISOString() → "2023-11-14T22:13:20.000Z"
- Python: datetime.fromtimestamp(1700000000, tz=timezone.utc).isoformat()
- Shell: date -u -d @1700000000 (GNU) / date -u -r 1700000000 (BSD, macOS)
- SQL: TO_TIMESTAMP(1700000000) (Postgres), FROM_UNIXTIME(1700000000) (MySQL)
- Regra: passa segundos onde se esperam segundos — só o Date do JavaScript precisa do × 1000
Erros comuns ao converter o tempo Epoch
Os erros mais frequentes ao converter timestamps Unix:
- Esquecer de multiplicar os segundos por 1000 em JavaScript — new Date(1700000000) dá o ano 1970, não 2023
- Usar milissegundos do JavaScript diretamente como segundos numa linguagem de servidor (um erro de 1000×)
- Não especificar um fuso e depender do fuso local do servidor, que varia entre ambientes
- Armazenar timestamps como strings em vez de inteiros, o que quebra comparações e aritmética numéricas
- Usar a obsoleta datetime.utcfromtimestamp() em Python — passa antes tz=timezone.utc a fromtimestamp()
Artigos relacionados
FAQ
- Como converto o tempo Epoch numa data?
- Identifica se o valor está em segundos (10 dígitos) ou milissegundos (13 dígitos) e depois converte-o com a API de datas da tua linguagem — new Date(seconds * 1000) em JavaScript, datetime.fromtimestamp(seconds, tz=timezone.utc) em Python, ou cola-o no conversor acima.
- Porque é que o meu timestamp Epoch se converte para 1970?
- Passaste um valor em segundos a uma função que espera milissegundos, na maioria das vezes o new Date() do JavaScript. Multiplica primeiro por 1000 o valor em segundos de 10 dígitos.
- Devo converter o tempo Epoch para UTC ou para hora local?
- Usa UTC para logs, APIs e comparações entre servidores, e converte para o fuso horário local do utilizador apenas para apresentação. O próprio valor Epoch é neutro quanto ao fuso.
- Como obtenho uma data a partir de um timestamp Unix em JavaScript?
- new Date(seconds * 1000) devolve um objeto Date que podes formatar com toISOString(), toUTCString() ou Intl.DateTimeFormat. A multiplicação é necessária porque o Date do JavaScript espera milissegundos, não segundos.
- Como obtenho uma data a partir de um timestamp Unix em Python?
- Usa datetime.fromtimestamp(seconds, tz=timezone.utc) para um datetime UTC ciente do fuso. Omite o argumento tz para hora local, ou acrescenta .isoformat() para obter uma cadeia ISO 8601.
- O mesmo valor Epoch dá uma data diferente em fusos horários diferentes?
- O instante é o mesmo em toda a parte, mas a data de relógio de parede que mostras depende do fuso — e pode até cair noutro dia de calendário. 1700000000 é 14 de nov. em Nova Iorque, mas 15 de nov. em Tóquio.
- Como converto um timestamp numa data?
- Toda linguagem moderna tem uma função integrada de uma linha. O mais difícil é identificar se o teu timestamp está em segundos (10 dígitos) ou milissegundos (13 dígitos) — acerta na unidade e a conversão em si nunca falha.