Os sete erros que produzem uma data errada
Um conversor epoch faz aritmética simples, por isso quando a saída está errada a causa quase nunca é a matemática — é a entrada. Um timestamp não traz rótulo a dizer se está em segundos ou milissegundos, em UTC ou local, nem qual a sua precisão, e toda conversão errada vem de adivinhar mal um desses pontos. A pista mais rápida é o ano resultante: uma data perto de 1970 ou a milhares de anos no futuro é uma confusão de unidade, e uma data certa mas desfasada de um número redondo de horas é um erro de fuso. A tabela abaixo é o guia de campo; as secções seguintes explicam a fundo os erros de unidade e de fuso e mostram como verificar uma conversão no código.
| Erro | O que vês | Causa | Correção |
|---|---|---|---|
| Segundos lidos como milissegundos | A data cai em 1970 | O Date e o Date.now() do JS esperam ms; passaste segundos de 10 dígitos | Multiplicar os segundos por 1000 |
| Milissegundos lidos como segundos | Data a milhares de anos no futuro | Valor de 13 dígitos passado a uma função em segundos | Dividir primeiro por 1000 |
| UTC mostrado como hora local | Dia certo, relógio desfasado pelo teu offset | O conversor escolheu por omissão outro fuso | Colocar o conversor em UTC |
| Hora local copiada sem o seu offset | Desfasada horas noutra máquina | Uma hora de relógio de parede guardada sem fuso | Guardar o UTC mais o fuso horário |
| Hora de parede ambígua (horário de verão) | Desfasada exatamente uma hora perto de uma mudança | Uma hora local que ocorre duas vezes ou nunca | Converter a partir do UTC; fixar o fuso IANA |
| Micro/nanossegundos lidos como segundos | Data longe no futuro (16 ou 19 dígitos) | Valor de base de dados ou de tracing em µs ou ns | Dividir por 1.000.000 (µs) ou 1.000.000.000 (ns) |
| Confiar na precisão apresentada | Parte de subsegundo descartada em silêncio | O conversor truncou os milissegundos | Confirmar a unidade que a API de destino documenta |
O que faz um conversor epoch
Um conversor epoch transforma timestamps numéricos em datas legíveis e volta a converter datas humanas em timestamps epoch. Um bom conversor trata segundos Unix, milissegundos Unix, saída UTC, saída em fuso local e cadeias ISO 8601, e torna a unidade óbvia antes de copiares um valor para código, uma base de dados ou um pedido de API. Conversor epoch, conversor de hora Unix, conversor de timestamp Unix e calculadora de epoch Unix descrevem o mesmo trabalho: traduzir entre uma contagem de segundos (ou milissegundos) desde 1 de janeiro de 1970 UTC e uma data que um humano consiga ler. O conversor raramente é o problema — normalmente é a entrada.
Os erros de unidade: segundos, milissegundos, micro, nano
O erro de conversão de longe mais comum é uma confusão de unidade, e tem uma assinatura: a data cai em 1970, ou a milhares de anos. O JavaScript é onde mais morde, porque tanto o construtor Date como o Date.now() trabalham em milissegundos enquanto a maioria das APIs, bases de dados e o comando Unix date trabalham em segundos. Passa um valor em segundos de 10 dígitos a new Date() sem multiplicar por 1000 e aterras 53 anos cedo demais. Ao contrário — alimentar uma função em segundos com milissegundos de 13 dígitos — atira a data para longe no futuro. As fontes de maior precisão pioram isto: as bases de dados emitem muitas vezes microssegundos de 16 dígitos e os sistemas de tracing nanossegundos de 19 dígitos, e ambos parecem um valor Unix válido até se descodificarem no milénio errado.
- 10 dígitos → segundos (p. ex. 1700000000); 13 → milissegundos; 16 → microssegundos; 19 → nanossegundos
- JavaScript: new Date(seconds * 1000), ou new Date(ms) diretamente
- Microssegundos → dividir por 1.000.000 antes de converter; nanossegundos → por 1.000.000.000
- Verificação de bom senso: o resultado deve ser uma data credível na década atual
Os erros de fuso horário: UTC vs local e horário de verão
Uma vez correta a unidade, os erros restantes são de fuso horário, e também partilham uma assinatura: a data está certa mas o relógio está desfasado de um número inteiro de horas. Um timestamp Unix é um único instante sem fuso próprio; o offset só é aplicado ao formatar o instante. Assim, dois conversores com fusos diferentes mostram horas diferentes para o mesmo número — nenhum está errado, apenas mostram vistas locais diferentes. A armadilha é copiar uma hora local de relógio de parede sem registar de que fuso vem, ou converter uma hora que cai numa mudança de horário de verão, onde uma hora local pode ocorrer duas vezes ou nenhuma. Quando um resultado está desfasado exatamente uma hora, suspeita do horário de verão antes de suspeitar do conversor.
- Comparar valores em UTC; aplicar um fuso local apenas no momento de os mostrar
- Nunca guardar uma hora local sem guardar também o seu fuso IANA ou offset UTC
- Em torno de uma mudança de horário de verão, derivar o instante do UTC, não de uma hora local ambígua
Escolhe primeiro a direção
A maioria das tarefas de timestamp vai numa de duas direções: epoch para data, ou data para epoch. Decidir primeiro a direção previne a causa mais comum de dados de teste errados e payloads de API quebrados — converter o valor certo no sentido errado.
- Epoch para data: cola 1700000000 e lê a data UTC ou local
- Data para epoch: escolhe 2026-01-01 00:00:00 UTC e obtém 1767225600
- Confirma se o destino espera segundos ou milissegundos antes de copiar o resultado
O que verificar antes de copiar um valor convertido
Um conversor só pode ser tão correto quanto a entrada for inequívoca. Antes de copiar um timestamp para um teste, um cron, uma migração ou um pedido de API, confirma a unidade, o fuso e a precisão esperada. A verificação mais rápida é o ano resultante: uma data perto de 1970 ou longe no futuro quase sempre assinala uma confusão de unidade e não um erro do conversor.
- O sistema recetor espera segundos ou milissegundos?
- A data apresentada está em UTC ou em hora local?
- O timestamp representa um instante ou uma data de calendário local?
- A coluna da base de dados guarda datetime nativo, segundos Unix ou milissegundos Unix?
- O resultado está perto de 1970 ou longe no futuro, o que costuma assinalar uma confusão de unidade?
Verificar uma conversão no código
Quando um valor convertido importa — uma migração, um limite de faturação, um agendamento cron — não confies numa única ferramenta. Volta a derivar o mesmo instante no teu próprio runtime e confirma que ambos concordam em UTC. Cada uma destas linhas imprime uma cadeia ISO 8601 inequívoca com sufixo Z, por isso não há adivinhação de fuso local para comparar.
- JavaScript: new Date(1700000000 * 1000).toISOString() // '2023-11-14T22:13:20.000Z'
- Python: datetime.fromtimestamp(1700000000, tz=timezone.utc).isoformat()
- Shell (GNU): date -u -d @1700000000 +'%Y-%m-%dT%H:%M:%SZ'
- Se a ferramenta e o teu runtime divergirem, a suspeita é a unidade ou o fuso da entrada — não o conversor
Exemplo prático: um instante, três representações
Toma o instante 2026-01-01 00:00:00 UTC. Como segundos Unix é 1767225600; como milissegundos Unix é 1767225600000; como ISO 8601 é 2026-01-01T00:00:00Z. Os três descrevem o mesmo momento — só diferem o formato e a unidade. O instante nunca traz um fuso próprio; Nova Iorque mostraria esse mesmo valor como 2025-12-31 19:00:00, porque o offset é aplicado na apresentação, não guardado no número.
Artigos relacionados
FAQ
- Porque é que a minha data convertida cai em 1970?
- Quase sempre porque segundos foram lidos como milissegundos. O Date e o Date.now() do JavaScript usam milissegundos, por isso passar um valor em segundos de 10 dígitos cai em janeiro de 1970. Multiplica primeiro os segundos por 1000.
- Porque é que a minha hora convertida está desfasada exatamente uma hora?
- É um erro de fuso horário ou de horário de verão, não um erro de cálculo. O conversor aplicou outro fuso, ou a hora local caiu numa mudança de horário de verão. Coloca o conversor em UTC para ver o instante canónico e depois aplica o fuso que realmente queres.
- Qual é o melhor formato de conversor epoch para copiar?
- Para código, copia segundos ou milissegundos Unix conforme o que a API de destino documenta. Para humanos, copia ISO 8601 com um Z ou um deslocamento de fuso explícito para que o instante seja inequívoco.
- Um conversor epoch é o mesmo que um conversor de hora Unix?
- Para a maioria das pesquisas de programadores, sim. Conversor epoch, conversor de hora Unix, conversor de timestamp Unix e calculadora de epoch Unix convertem todos entre timestamps de epoch Unix e datas legíveis.
- Porque é que os conversores epoch mostram horas locais diferentes?
- Aplicam fusos diferentes. O instante UTC subjacente é idêntico; só muda a apresentação local. Coloca o conversor em UTC para comparar o valor canónico.
- Como sei se o meu número está em segundos ou em milissegundos?
- Conta os dígitos. Um valor moderno de 10 dígitos está em segundos Unix; um de 13 dígitos está em milissegundos Unix. Se um valor de 10 dígitos cair perto de 1970 em JavaScript, foi tratado como milissegundos e tem de ser multiplicado por 1000.