Timestamp Unix: como converter data e hora em código

O que é um timestamp Unix

É um número inteiro que conta os segundos desde a "época Unix": 1 de janeiro de 1970, meia-noite em UTC. O número 0 é esse instante, 1700000000 é 14 de novembro de 2023 às 22:13:20 UTC, e números negativos representam datas anteriores a 1970.

Como o valor é o mesmo em qualquer lugar do mundo, ele é ótimo para guardar e trocar datas entre sistemas. O fuso horário só entra na hora de mostrar a data para uma pessoa. Para conferir um valor rapidamente, use o conversor de timestamp.

Segundos ou milissegundos?

Essa é a confusão mais comum. O Unix tradicional, o Python (time.time()) e o PHP (time()) trabalham em segundos, com 10 dígitos para datas atuais. O JavaScript (Date.now()) trabalha em milissegundos, com 13 dígitos.

• Um valor em milissegundos lido como segundos cai em um ano na casa dos 50 mil, uma data absurda.
• Um valor em segundos lido como milissegundos cai em janeiro de 1970.
• Para APIs, confira a documentação: há serviços que enviam segundos e outros que enviam milissegundos no mesmo campo de nome parecido.

Converter em JavaScript

O Date guarda milissegundos, então divida por 1000 para obter segundos e multiplique por 1000 na volta. A função emSegundos usa o tamanho do número para adivinhar a unidade, o que funciona para datas entre 1973 e o ano 5138, mas continua sendo uma suposição.

// Segundos desde 1970-01-01 00:00:00 UTC. Informe o fuso na data (Z ou -03:00).
function paraTimestamp(iso) {
  return Math.floor(new Date(iso).getTime() / 1000);
}

function deTimestamp(segundos) {
  return new Date(segundos * 1000).toISOString().replace('.000Z', 'Z');
}

// 10 dígitos costumam ser segundos e 13 costumam ser milissegundos
function emSegundos(valor) {
  return Math.abs(valor) >= 1e11 ? Math.floor(valor / 1000) : valor;
}

Converter em Python

Em Python, um datetime sem fuso ("ingênuo") é interpretado no fuso da máquina, e o mesmo código dá resultados diferentes em outro servidor. Por isso a função abaixo recusa datas sem fuso, e a volta usa sempre UTC.

from datetime import datetime, timezone


def para_timestamp(iso: str) -> int:
    dt = datetime.fromisoformat(iso.replace("Z", "+00:00"))
    if dt.tzinfo is None:
        raise ValueError("Informe o fuso, por exemplo 2026-01-01T00:00:00Z")
    return int(dt.timestamp())


def de_timestamp(segundos: int) -> str:
    dt = datetime.fromtimestamp(segundos, tz=timezone.utc)
    return dt.isoformat().replace("+00:00", "Z")

Converter em PHP

O DateTimeImmutable lê o fuso da própria data. Se a data vier sem fuso, o PHP usa o configurado no servidor, então mantenha o fuso explícito nos dados.

<?php
// Informe o fuso na data (Z ou -03:00). Sem fuso, o PHP usa o fuso configurado no servidor.
function paraTimestamp(string $iso): int
{
    return (new DateTimeImmutable($iso))->getTimestamp();
}

function deTimestamp(int $segundos): string
{
    return gmdate('Y-m-d\TH:i:s\Z', $segundos);
}

Cuidados

• Guarde datas em UTC ou como timestamp, e converta para o fuso de Brasília (UTC-3) só na exibição.
• O timestamp ignora segundos bissextos: o dia Unix sempre tem 86400 segundos.
• Em sistemas com inteiro de 32 bits, o timestamp estoura em 19 de janeiro de 2038 (2147483647). Use 64 bits em campos novos.
• Para comparar datas, compare os timestamps. Comparar textos de datas só funciona no formato ISO e com o mesmo fuso.

O conversor de timestamp mostra o mesmo instante em UTC e no seu fuso, o que ajuda a depurar diferenças de horário.