Um timestamp UNIX é um número, mas seu significado depende da unidade, do ponto de referência e da precisão. Um valor sem unidade pode representar segundos, milissegundos, microssegundos ou nanossegundos. Um texto de data sem fuso também pode representar instantes diferentes.
Este guia explica conversão, UTC, offsets, fusos nomeados, transições sazonais, ISO 8601, segundos bissextos e limites numéricos. Use o UNIX Timestamp Converter para um teste controlado, mas confirme o contrato do sistema antes de publicar um valor.
O que é um timestamp UNIX?
O tempo UNIX conta segundos desde a época UNIX: 1970-01-01 00:00:00 UTC. O valor 0 representa esse instante. Valores positivos representam instantes posteriores. Valores negativos representam instantes anteriores.
O nome “timestamp UNIX” não fixa a unidade de toda API. Muitos sistemas usam segundos inteiros; outros usam milissegundos ou frações. Registre a unidade com o campo e valide limites e sinal.
Um timestamp UNIX depende de fusos horários?
O instante numérico é definido em relação a UTC. Um fuso altera a forma de exibir o mesmo instante, não o valor UNIX correto. A conversão de 2024-01-01T00:00:00Z para um fuso local pode mostrar uma data ou hora diferente.
Um texto sem offset ou fuso nomeado é ambíguo. Não use a configuração local do computador como contrato entre sistemas.
Como distinguir segundos e milissegundos?
A quantidade de dígitos é apenas uma pista. Confirme o contrato da API, do banco ou do arquivo. O valor 1704067200 em segundos representa 2024-01-01T00:00:00Z; em milissegundos, representa outro intervalo.
Inclua a unidade no nome do campo, na documentação e nos testes. Faça exemplos com valores conhecidos e verifique ambos os sentidos da conversão.
Por que JavaScript pode perder precisão de tempo?
JavaScript representa números comuns como IEEE-754 double. Inteiros acima de Number.MAX_SAFE_INTEGER, 9007199254740991, não podem ser representados com precisão inteira garantida. Microssegundos e nanossegundos ampliam rapidamente o valor.
Use BigInt ou uma biblioteca de data adequada quando a precisão exceder inteiros seguros. Não converta um valor grande para Number antes de confirmar o intervalo.
O que diferencia UTC, offsets e fusos nomeados?
UTC é uma escala de referência. Um offset como -03:00 descreve uma diferença fixa em um instante. Um fuso nomeado, como America/Sao_Paulo, inclui regras históricas e transições mantidas por uma base de dados.
Armazenar somente um offset pode perder a regra necessária para eventos futuros. Use um fuso nomeado quando o compromisso depende da hora civil de uma região.
O que acontece nas transições de horário de verão?
Quando o relógio avança, alguns horários locais não existem. Quando recua, alguns horários aparecem duas vezes. Um parser precisa de uma política para lacunas e sobreposições.
Não escolha silenciosamente o primeiro ou o segundo instante quando a hora local for ambígua. Preserve o offset recebido ou peça confirmação.
Como formatar um instante?
Use ISO 8601 com offset ou Z, por exemplo 2024-01-01T00:00:00Z. Para comunicação entre sistemas, prefira uma representação explícita e estável. Para interface, formate no fuso do usuário somente na camada de apresentação.
Não misture data local, timestamp e texto formatado sem indicar qual representa um instante absoluto.
Como segundos bissextos afetam o tempo UNIX?
As implementações UNIX comuns não representam segundos bissextos como uma sequência universal adicional. Sistemas podem repetir, ignorar ou distribuir esse segundo. Não presuma que todos os relógios e bibliotecas têm o mesmo comportamento.
Para aplicações que exigem tempo científico, siga a escala e a biblioteca especificadas pelo domínio. Para APIs comuns, siga o contrato do sistema e teste limites.
Como converter um timestamp UNIX com segurança?
- Identifique a unidade e o intervalo aceitos.
- Preserve o valor como inteiro exato durante a conversão.
- Defina se o texto de entrada contém UTC, offset ou fuso nomeado.
- Teste época, valores negativos, frações e limites.
- Compare o resultado com uma biblioteca ou valor conhecido.
- Armazene o instante e o fuso civil separadamente quando ambos forem necessários.
O conversor pode ajudar a verificar uma amostra. Ele não decide qual unidade o seu sistema pretende usar.
O que diferencia horários de arquivo do Windows?
FILETIME do Windows conta intervalos de 100 nanossegundos desde 1601-01-01 UTC. A época é diferente da época UNIX. O Windows Filetime to UNIX Timestamp Converter preserva a relação entre as escalas, mas exige que você confirme ordem de bytes e unidade.
Não trate FILETIME como segundos UNIX. Os valores e limites são diferentes, e APIs do Windows podem impor limites adicionais.
Recomendações para bancos de dados e APIs
Documente unidade, sinal, precisão, escala e fuso. Use tipos inteiros adequados ao intervalo. Preserve o offset de entrada quando a auditoria precisar da representação original, mas armazene o instante absoluto para comparação.
Valide valores no limite do sistema receptor. Não aceite números grandes em ponto flutuante apenas porque o parser os aceitou. Teste serialização, arredondamento e conversões entre linguagens.
Erros comuns em timestamps
Erro 1: Deduzir unidade apenas pelos dígitos
Confirme o contrato. Valores com aparência semelhante podem representar segundos ou milissegundos.
Erro 2: Adicionar offset para alterar o fuso
O mesmo instante tem o mesmo timestamp. Altere apenas a apresentação, usando regras do fuso nomeado.
Erro 3: Usar abreviação como fuso
Abreviações podem ser ambíguas. Use um identificador de fuso mantido e um offset explícito.
Erro 4: Analisar data e hora sem fuso
Uma data local sem zona não identifica um instante. Informe o fuso antes de converter.
Erro 5: Ignorar lacunas e sobreposições sazonais
Transições podem tornar um horário inexistente ou duplicado. Defina uma política e registre a escolha.
Erro 6: Converter timestamps grandes com ponto flutuante
Valores fora de inteiros seguros podem perder bits. Use representação inteira exata.
Erro 7: Usar o relógio do cliente para segurança
Relógios podem estar incorretos ou sob controle do usuário. Use uma fonte confiável para expiração, auditoria e autorização.
Lista de verificação
- A unidade está documentada?
- O valor usa UTC, offset ou fuso nomeado?
- O intervalo cabe no tipo numérico?
- A conversão preserva frações necessárias?
- Os testes incluem época, valores negativos e transições?
- O sistema receptor espera a mesma precisão?
- A apresentação local está separada do instante armazenado?
Perguntas frequentes
O tempo UNIX sempre usa segundos?
Não. Segundos são comuns, mas APIs também usam milissegundos, microssegundos e nanossegundos. Confirme a unidade no contrato.
O tempo UNIX contém um fuso horário?
Não. Ele representa um instante relativo à época UTC. O fuso aparece quando você formata esse instante.
Qual fuso o valor 0 usa?
0 é 1970-01-01 00:00:00 UTC. A mesma marca aparece em outra hora civil quando formatada em outro fuso.
Por que meu conversor mostra 1970?
Você pode ter fornecido 0, uma unidade errada ou um valor pequeno. Confira unidade, sinal e ponto de referência.
Por que dois conversores diferem uma hora?
Um pode usar UTC e o outro um fuso local. Também podem aplicar regras históricas diferentes. Compare o offset e o fuso nomeado.
UTC equivale a GMT?
Eles coincidem em muitos usos civis, mas são conceitos diferentes. Use UTC como escala de referência e siga a biblioteca exigida pelo domínio.
Posso armazenar apenas um timestamp UTC para reuniões recorrentes?
Não sempre. Um evento recorrente baseado em hora civil precisa do fuso nomeado e das regras de calendário. Armazene o instante de cada ocorrência quando possível.
Devo usar ISO 8601 ou tempo UNIX?
Use o formato exigido pelo contrato. ISO 8601 comunica unidade e offset de modo legível. UNIX é compacto e útil para interfaces numéricas, desde que a unidade seja explícita.
Regra final de conversão
Trate timestamps como valores com unidade, época e precisão. Trate fusos como regras de apresentação e de calendário. Preserve inteiros exatos, valide limites e documente as decisões antes de compartilhar dados entre sistemas.
Fontes técnicas.
Consulte a teoria da base de fusos da IANA, a lista de fusos da IANA, a especificação RFC 3339, a atualização RFC 9557 e a RFC 9636 para regras de data, hora e zona.
Para detalhes de implementação, consulte a documentação da Microsoft sobre horários de arquivo do Windows, a especificação ECMAScript sobre números e datas e a proposta Temporal sobre ZonedDateTime.