Guide

Compreendendo os formatos de carimbo de data/hora

Introdução

Os carimbos de data e hora vêm em vários formatos e precisões. Compreender esses formatos é crucial para desenvolvedores que trabalham com dados de tempo, APIs, bancos de dados e sistemas distribuídos.

Resumo rápido: carimbos de data/hora Unix (segundos, milissegundos, microssegundos, nanossegundos), strings ISO 8601 e formatos RFC 3339 são os mais comuns. Cada um serve a propósitos diferentes no desenvolvimento de software.

Formatos de carimbo de data/hora Unix

Época Unix (horário POSIX)

O carimbo de data/hora Unix representa o tempo como número de segundos/milissegundos desde 1º de janeiro de 1970, 00:00:00 UTC.

Unix Epoch Reference:
  Start Date: January 1, 1970, 00:00:00 UTC
  Current: January 1, 2026, 00:00:00 UTC
  Timestamp: 1735689600 (seconds)

Níveis de precisão

Precisão	Exemplo	Magnitude	Uso Comum
Segundos	`1735689600`	10 dígitos	Sistemas Unix/Linux
Milissegundos	`17356896000000`	13 dígitos	JavaScript, APIs da Web
Microssegundos	`173568960000000000`	16 dígitos	Tempo de alta precisão
Nanossegundos	`173568960000000000000`	19 dígitos	Computação científica

Exemplos de código: diferentes precisões

// JavaScript uses milliseconds by default
const msTimestamp = Date.now(); // 17356896000000
const secTimestamp = Math.floor(Date.now() / 1000); // 1735689600
const nsTimestamp = Date.now() * 1000000; // 173568960000000000000

console.log('Milliseconds:', msTimestamp);
console.log('Seconds:', secTimestamp);
console.log('Nanoseconds:', nsTimestamp);

from datetime import datetime
import time

# Python supports multiple precisions
now = datetime.now(datetime.timezone.utc)
sec_timestamp = int(now.timestamp())
ms_timestamp = int(now.timestamp() * 1000)
us_timestamp = int(now.timestamp() * 1000000)
ns_timestamp = int(now.timestamp() * 1000000000)

print(f'Seconds: {sec_timestamp}')
print(f'Milliseconds: {ms_timestamp}')
print(f'Microseconds: {us_timestamp}')
print(f'Nanoseconds: {ns_timestamp}')

import java.time.Instant;

// Java supports multiple precisions
Instant now = Instant.now();
long secTimestamp = now.getEpochSecond(); // 1735689600
long msTimestamp = now.toEpochMilli(); // 17356896000000
int nsTimestamp = now.getNano(); // Nanoseconds within second

System.out.println("Seconds: " + secTimestamp);
System.out.println("Milliseconds: " + msTimestamp);
System.out.println("Nanoseconds: " + nsTimestamp);

Formato ISO 8601

Definição

ISO 8601 é um padrão internacional para representar datas e horas. É o formato mais utilizado para armazenar e trocar carimbos de data/hora.

Variantes de formato

Basic ISO 8601 Formats:
  1. Calendar Date: 2026-01-01
  2. Date and Time: 2026-01-01T12:00:00
  3. With Time Zone: 2026-01-01T12:00:00+08:00
  4. UTC (Z notation): 2026-01-01T12:00:00Z
  5. With Fractional Seconds: 2026-01-01T12:00:00.123Z
  6. With Milliseconds: 2026-01-01T12:00:00.123Z
  7. With Nanoseconds: 2026-01-01T12:00:00.123456789Z

Dividindo a ISO 8601

Format: YYYY-MM-DDThh:mm:ss.sssTZD

Components:
  YYYY - Four-digit year (2026)
  MM - Two-digit month (01)
  DD - Two-digit day (01)
  T - Separator between date and time
  hh - Two-digit hour (00-23)
  mm - Two-digit minute (00-59)
  ss - Two-digit second (00-59)
  sss - Fractional seconds (optional)
  TZD - Time zone designator (Z, +08:00, -05:00)

Exemplos de código: ISO 8601

// JavaScript has built-in ISO 8601 support
const now = new Date();
const isoString = now.toISOString(); // "2026-01-01T12:00:00.000Z"

// Parse ISO 8601
const date = new Date('2026-01-01T12:00:00Z');

console.log('ISO 8601:', isoString);
console.log('Parsed:', date.toISOString());

from datetime import datetime, timezone

# Generate ISO 8601
now_utc = datetime.now(timezone.utc)
iso_string = now_utc.isoformat() # "2026-01-01T12:00:00+00:00"

# Parse ISO 8601
parsed_date = datetime.fromisoformat('2026-01-01T12:00:00+00:00')

print(f'ISO 8601: {iso_string}')
print(f'Parsed: {parsed_date.isoformat()}')

import java.time.Instant;
import java.time.format.DateTimeFormatter;

// Generate ISO 8601
Instant now = Instant.now();
String isoString = now.toString(); // "2026-01-01T12:00:00:00Z"

// Parse ISO 8601
Instant parsed = Instant.parse("2026-01-01T12:00:00:00Z");

System.out.println("ISO 8601: " + isoString);
System.out.println("Parsed: " + parsed);

Formato RFC 3339

Definição

RFC 3339 é um subconjunto da ISO 8601 projetado especificamente para protocolos de Internet e padrões de e-mail.

Diferenças da ISO 8601

Recurso	ISO 8601	RFC 3339
Formato	Múltiplas variantes	Formato fixo
Fuso horário	Pode usar deslocamento ou Z	Pode usar deslocamento ou Z
Aplicativos	Finalidade geral	Protocolos de Internet (HTTP, E-mail)
Segundos fracionários	Opcional	Opcional
Exemplo	`2026-01-01T12:00:00+08:00`	`2026-01-01T12:00:00+08:00`

Observação: A RFC 3339 é quase idêntica à ISO 8601. Na prática, elas são usadas de forma intercambiável para aplicativos de Internet.

Exemplos de código: RFC 3339

// RFC 3339 is similar to ISO 8601
const now = new Date();
const rfc3339String = now.toISOString(); // "2026-01-01T12:00:00.000Z"

// RFC 3339 commonly used in HTTP headers
const httpDate = now.toUTCString(); // "Wed, 01 Jan 2026 12:00:00 GMT"

console.log('RFC 3339:', rfc3339String);
console.log('HTTP Date:', httpDate);

from datetime import datetime, timezone
import email.utils

# Generate RFC 3339 (same as ISO 8601)
now_utc = datetime.now(timezone.utc)
rfc3339_string = now_utc.isoformat() # "2026-01-01T12:00:00+00:00"

# Generate HTTP date format
http_date = email.utils.format_datetime(now_utc)

print(f'RFC 3339: {rfc3339_string}')
print(f'HTTP Date: {http_date}')

Conversão de formato

Carimbo de data e hora Unix ↔ ISO 8601

// Unix to ISO 8601
function unixToIso(unixTimestamp, precision = 'ms') {
  let ts = unixTimestamp;
  if (precision === 's') {
    ts = unixTimestamp * 1000;
  } else if (precision === 'us') {
    ts = unixTimestamp / 1000;
  } else if (precision === 'ns') {
    ts = unixTimestamp / 1000;
  } else if (precision === 'ns') {
    ts = unixTimestamp / 1000000;
  }
  return new Date(ts).toISOString();
}

// ISO 8601 to Unix
function isoToUnix(isoString) {
  return Math.floor(new Date(isoString).getTime() / 1000);
}

// Examples
const unixTs = 1735689600;
const isoStr = unixToIso(unixTs); // "2026-01-01T00:00:00.000Z"
const backToUnix = isoToUnix(isoStr); // 1735689600

console.log('Unix → ISO:', isoStr);
console.log('ISO → Unix:', backToUnix);

from datetime import datetime, timezone

def unix_to_iso(unix_timestamp, precision='s'):
    """Convert Unix timestamp to ISO 8601 string"""
    ts = unix_timestamp
    if precision == 's':
        ts = unix_timestamp
    elif precision == 'ms':
        ts = unix_timestamp / 1000
    elif precision == 'us':
        ts = unix_timestamp / 1000
    elif precision == 'ns':
        ts = unix_timestamp / 1000000
    elif precision == 'ns':
        ts = unix_timestamp / 1000000000

    dt = datetime.fromtimestamp(ts, timezone.utc)
    return dt.isoformat()

def iso_to_unix(iso_string):
    """Convert ISO 8601 string to Unix timestamp"""
    dt = datetime.fromisoformat(iso_string)
    return int(dt.timestamp())

# Examples
unix_ts = 1735689600
iso_str = unix_to_iso(unix_ts)  # "2026-01-01T00:00:00+00:00"
back_to_unix = iso_to_unix(iso_str)  # 1735689600

print(f'Unix → ISO: {iso_str}')
print(f'ISO → Unix: {back_to_unix}')

Detecção de precisão

Detectando precisão de carimbo de data/hora Unix

function detectPrecision(timestamp) {
  const str = timestamp.toString();

  if (str.length === 10) {
    return 'seconds';
  } else if (str.length === 13) {
    return 'milliseconds';
  } else if (str.length === 16) {
    return 'microseconds';
  } else if (str.length === 19) {
    return 'nanoseconds';
  }

  return 'unknown';
}

// Examples
console.log(detectPrecision(1735689600)); // "seconds"
console.log(detectPrecision(17356896000000)); // "milliseconds"
console.log(detectPrecision(173568960000000000)); // "microseconds"
console.log(detectPrecision(173568960000000000000)); // "nanoseconds"

def detect_precision(timestamp):
    """Detect Unix timestamp precision"""
    str_ts = str(int(timestamp))

    if len(str_ts) == 10:
        return 'seconds'
    elif len(str_ts) == 13:
        return 'milliseconds'
    elif len(str_ts) == 16:
        return 'microseconds'
    elif len(str_ts) == 19:
        return 'nanoseconds'

    return 'unknown'

# Examples
print(detect_precision(1735689600))  # "seconds"
print(detect_precision(173568960000000))  # "milliseconds"
print(detect_precision(173568960000000000))  # "microseconds"
print(detect_precision(173568960000000000000))  # "nanoseconds"

Tabela de comparação

Carimbo de data e hora Unix vs ISO 8601 vs RFC 3339

Aspecto	Carimbo de data e hora Unix	ISO 8601	RFC 3339
Formato	Número (inteiro/flutuante)	Corda	Corda
Legível por humanos	Não	Sim	Sim
Informações sobre fuso horário	Não (UTC implícito)	Sim (opcional)	Sim (opcional)
Precisão	Configurável	Configurável	Configurável
Tamanho de armazenamento	4-8 bytes	20-30 bytes	20-30 bytes
Suporte a banco de dados	Universais	Universais	Universais
Uso Comum	Carimbos de data e hora do sistema	APIs, JSON, bancos de dados	HTTP, e-mail, APIs
Exemplo	`1735689600`	`2026-01-01T12:00:00:00Z`	`2026-01-01T12:00:00:00Z`

Recomendação: Use carimbos de data/hora Unix para armazenamento interno e cálculos. Use ISO 8601/RFC 3339 para APIs, troca de dados e formatos legíveis por humanos.

Melhores práticas

Armazenamento

Use carimbos de data/hora Unix em bancos de dados para armazenamento e indexação eficientes
Use ISO 8601 para APIs externas e troca de dados
Sempre inclua fusos horários ao exibir aos usuários
Formato do documento nos comentários do esquema do banco de dados

-- Best practice: Store Unix timestamp in database
CREATE TABLE events (
  id INT PRIMARY KEY,
  event_timestamp BIGINT,  -- Unix timestamp in milliseconds
  description TEXT,
  created_at TIMESTAMP WITHOUT TIME ZONE DEFAULT NOW()
);

Respostas da API

Use ISO 8601 para corpos de resposta de API
Incluir carimbo de data/hora Unix para acesso programático
Especifique o fuso horário claramente nas respostas

{
  "event": {
    "id": 123,
    "timestamp": 173568960000000,
    "iso8601": "2026-01-01T12:00:00:00Z",
    "timezone": "UTC",
    "human_readable": "January 1, 2026 at 12:00:00 AM UTC"
  }
}

Tratamento de erros

Valide o formato antes de analisar
Controle de segundos bissextos em aplicações de alta precisão
Degradação elegante para formatos desconhecidos

// Validate ISO 8601 format
function isValidISO8601(str) {
  const isoRegex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2}:\d{2})?$/;
  return isoRegex.test(str);
}

// Handle parsing errors
function safeParseISO8601(str) {
  try {
    return new Date(str);
  } catch (error) {
    console.error('Invalid ISO 8601 format:', str);
    return new Date(); // Fallback to current time
  }
}

Armadilhas Comuns

Armadilha 1: presumir que o timestamp do Unix é sempre em segundos

// ❌ Wrong: Always dividing by 1000
const timestamp = Date.now();
const wrongDate = new Date(timestamp / 1000); // Incorrect division

// ✅ Right: Check precision first
const date = new Date(timestamp); // Date accepts milliseconds directly

Armadilha 2: Ignorar fusos horários

// ❌ Wrong: Creating local time without timezone
const localTime = new Date('2026-01-01T12:00:00'); // Ambiguous

// ✅ Right: Specify timezone explicitly
const utcTime = new Date('2026-01-01T12:00:00Z'); // Clear UTC
const tokyoTime = new Date('2026-01-01T12:00:00+09:00'); // Tokyo time

Armadilha 3: Misturar formatos

// ❌ Wrong: Inconsistent formats in API
{
  "timestamp": 1735689600,
  "date": "01/01/2026",
  "time": "12:00 PM",
  "datetime": "2026-01-01 12:00"
}

// ✅ Right: Consistent ISO 8601 format
{
  "timestamp": 1735689600,
  "iso8601": "2026-01-01T12:00:00:00Z",
  "timezone": "UTC"
}

Ferramentas relacionadas

Unix Timestamp Converter - Converta entre carimbos de data e hora Unix e datas com detecção automática de precisão
Conversor ISO 8601 - Converter de/para o formato ISO 8601
Conversor RFC 3339 - Trabalhar com formato de carimbo de data/hora RFC 3339
Current Timestamp - Obtenha a hora atual em vários formatos e precisões
Validador de carimbo de data/hora - Valide e detecte formatos de carimbo de data/hora

Perguntas frequentes

P: Qual é a diferença entre ISO 8601 e RFC 3339?

R: RFC 3339 é um subconjunto da ISO 8601 projetado para protocolos de Internet. Eles são quase idênticos na prática, mas o RFC 3339 tem regras de formato mais rígidas.

P: Como posso saber se um carimbo de data/hora Unix está em segundos ou milissegundos?

R: Dígitos de contagem: 10 dígitos = segundos, 13 dígitos = milissegundos. Você também pode verificar o ano (segundos = 1970+, milissegundos = 1970+).

P: Que precisão devo usar para minha aplicação?

R: Use milissegundos para aplicativos Web gerais (padrão JavaScript), segundos para eficiência de armazenamento de banco de dados ou microssegundos/nanossegundos para temporização de alta precisão.

P: A ISO 8601 suporta fusos horários?

R: Sim, a ISO 8601 suporta deslocamentos de fuso horário (+08:00) e notação Z para UTC.

P: Como lidar com fusos horários com carimbos de data/hora Unix?

R: Os carimbos de data/hora Unix são sempre UTC. Converta para o horário local somente ao exibir aos usuários usando suas configurações de fuso horário.

P: Qual é o valor máximo do timestamp do Unix?

R: Para sistemas de 64 bits: 19 de janeiro de 2038 (problema do ano 2038) não é um problema. O máximo teórico é bilhões de anos no futuro.