Converter timestamp Unix

Um timestamp Unix conta desde 1º de janeiro de 1970. Em segundos, as datas atuais têm dez dígitos; em milissegundos, treze. Essa diferença de tamanho é o que permite deduzir a unidade sem perguntar, e o limiar fica muito longe de qualquer data que alguém vá olhar.

A dedução é sempre informada, porque a falha clássica dessa conversão é acertar em silêncio. Um número em milissegundos lido como segundos dá uma data no ano 55.000 e se percebe; ao contrário dá 1970 e também se percebe. O que não se percebe é uma ferramenta que decide sozinha e não conta.

O número não carrega fuso: ele é um instante absoluto. O fuso aparece na hora de escrever aquilo como data, e daí sai o mal-entendido mais caro dessa conversão — duas pessoas olhando o mesmo timestamp e lendo dias diferentes porque estão em fusos diferentes.

Por isso saem os dois. Em Brasília a diferença para o UTC é de três horas para menos, então um evento das 02:00 UTC ainda é do dia anterior aqui. Quando alguém compara uma linha de log com o que um painel mostra, metade das divergências é exatamente isto.

O horário de verão brasileiro foi extinto em 2019, e desde então o horário de Brasília é UTC−3 o ano inteiro. Isso simplifica tudo o que for de 2019 para cá e não simplifica nada do que veio antes: registros anteriores caem em datas que tinham o adiantamento, e a conversão precisa usar as regras que valiam naquela data e não as de hoje.

É o que esta página faz, porque o banco de fusos do navegador guarda o histórico. A consequência prática aparece em relatórios longos: uma série que atravessa outubro de 2018 tem uma hora que ocorreu duas vezes e uma que não existiu, e um relatório agrupado por horário local mostra isso como um pico e um buraco que não estavam nos dados.

Além de UTC−3, existe UTC−2 em Fernando de Noronha, UTC−4 no Amazonas, em Mato Grosso e em Roraima, e UTC−5 no Acre e no oeste do Amazonas. Um sistema que assuma «horário de Brasília» para o país inteiro erra em duas ou três horas para uma parte real dos usuários.

A hora local mostrada aqui é a do seu próprio navegador, seja ela qual for, e é por isso que ela pode não bater com a de um colega olhando o mesmo número. Se o que você precisa é um valor combinado entre pessoas, use a linha em UTC — é a única das quatro que significa a mesma coisa em todo lugar.

Um timestamp guardado num inteiro de 32 bits com sinal estoura em 19 de janeiro de 2038 e volta para 1901. Soa distante e já não é: qualquer cálculo que olhe vinte anos para a frente — um financiamento, um certificado, um plano de amortização — cruza essa fronteira hoje.

Os sistemas modernos usam 64 bits e não têm o problema. O que sobra são formatos binários antigos, sistemas embarcados e colunas de banco declaradas há muito tempo. É o tipo de falha que não aparece até alguém digitar uma data distante, e aí aparece de uma vez.

A forma `2023-11-14T22:13:20Z` foi pensada para que ordenar como texto ordene também como data. Por isso ela é a indicada em nome de arquivo, em chave e em qualquer lugar onde algo vá ordenar alfabeticamente sem saber que está olhando datas.

O `Z` do fim significa UTC. A ausência dele é uma fonte inesgotável de erro: uma string sem fuso é interpretada por cada sistema com a suposição dele, e dois serviços podem ler o mesmo texto como dois instantes separados por horas. Se você vai escrever uma data, escreva o fuso.

O tempo Unix finge que todo dia tem exatamente 86.400 segundos, o que é falso: foram acrescentados vinte e sete segundos bissextos desde 1972 para compensar a rotação irregular da Terra. O formato simplesmente os ignora.

Para quase todo mundo é a decisão certa, porque é o que faz a aritmética de datas funcionar. Deixa de ser em astronomia, em sistemas de navegação e em algumas medições científicas, onde eles contam de verdade — e nesses lugares não se usa tempo Unix e sim escalas que os contam.

A numeração de semanas ISO define a semana 1 como a que contém a primeira quinta-feira do ano, e as semanas começam na segunda. Daí sai que 1º de janeiro pode cair na semana 52 do ano anterior, e que 31 de dezembro pode já ser semana 1 do seguinte.

Esse detalhe quebra relatório semanal todo mês de janeiro. A regra prática é que o ano da semana nem sempre é o ano da data, e quem agrupa por semana precisa guardar os dois juntos — uma «semana 1» sem ano é ambígua justamente nas datas em que mais se consulta.

O timestamp zero é 1º de janeiro de 1970 às 00:00 UTC, e valores negativos são datas anteriores a isso — perfeitamente representáveis, e é assim que uma data de nascimento de 1955 é guardada. Nem todo sistema aceita o negativo, o que já é motivo suficiente para não guardar datas de nascimento como timestamp.

O que aparece com muito mais frequência é o contrário: uma data de 1970 em produção quase nunca é uma data, é um campo nulo que virou zero em algum lugar da esteira. Se o resultado aqui deu 1º de janeiro de 1970, olhe primeiro para quem gerou o número, não para a conversão.

A linha de tempo relativo — «há três anos», «há onze minutos» — não acrescenta precisão, acrescenta escala. É o que responde de relance se um registro é de hoje de manhã ou do deploy do mês passado, que costuma ser a pergunta real por trás de olhar um timestamp.

Ela é escrita em português pelo formatador que já vem no navegador, então as formas são as brasileiras de verdade e não uma tradução de modelo em inglês. Para a resposta exata existem as outras linhas; esta é para se orientar.

Um timestamp quase nunca vem sozinho: ele é copiado de uma linha de log, de uma linha de banco ou de um payload que carrega ao lado um identificador de usuário. Como a conversão acontece na página, nem o número nem o que vem junto saem do seu aparelho.

Além disso, o seu fuso horário identifica bem mais do que parece, e aqui ele é lido do navegador sem ir a lugar nenhum. A conversão para o horário local é feita pela sua própria máquina, que é a única que precisa saber onde você está.