Datas e horários

A API usa três tipos de valores de data e hora, e cada um deve ser lido de um jeito. Misturá-los é a causa mais comum de "a viagem aparece um dia antes".

Tipo	Exemplo	Onde aparece	Como ler
Instante em UTC	2026-09-18T09:41:52.000000Z	created_at, updated_at	Converta para o fuso de quem vai ler.
Data de calendário	2026-11-13	starts_on, ends_on e os parâmetros de filtro	Use como está. Não converta.
Dia e hora do roteiro	2026-11-14T10:30:00	datetime, nas atividades do roteiro	Use como está. Não converta.

Instantes em UTC

Campos como created_at e updated_at marcam um momento exato e vêm no formato ISO 8601, sempre em UTC (o Z no final indica isso):

2026-09-18T09:41:52.000000Z

Para exibir, converta para o fuso da pessoa. As bibliotecas de data da sua linguagem fazem isso.

Datas de viagem

O início e o fim de uma viagem são datas de calendário: "a viagem começa em 13 de novembro". Não há um horário nem um fuso associado. Por isso a API oferece dois formatos:

Campo	Exemplo	Recomendação
starts_on e ends_on	2026-11-13	Use estes. É a data exata, no formato AAAA-MM-DD.
start_date e end_date	2026-11-13T00:00:00.000000Z	Mantidos por compatibilidade.

Os campos start_date e end_date são a mesma data escrita como se fosse um instante em UTC (meia-noite). Se você os converter para o fuso de Brasília, obtém o dia anterior às 21h, e a viagem "começa" um dia antes:

// Errado: em um computador no horário de Brasília, mostra 12/11/2026
new Date('2026-11-13T00:00:00.000000Z').toLocaleDateString('pt-BR');

// Certo: use a data pronta e não a converta
const [ano, mes, dia] = travel.starts_on.split('-');
console.log(`${dia}/${mes}/${ano}`); // 13/11/2026

Cuidado com new Date('2026-11-13')

Em JavaScript, new Date('2026-11-13') também interpreta a data como meia-noite em UTC e pode exibir o dia anterior. Para exibir uma data de calendário, formate o texto (como no exemplo) ou use uma biblioteca de datas que trabalhe com datas sem fuso.

Dia e hora do roteiro

Cada atividade do roteiro tem o campo datetime, como 2026-11-14T10:30:00. É o dia e a hora marcados no roteiro ("passeio de barco às 10h30 do dia 14") e vale no local da viagem. Ele vem sem fuso e sem Z de propósito: não o converta.

// Certo: exiba o valor como ele veio
const [data, hora] = roadmap.datetime.split('T');
console.log(data, hora.slice(0, 5)); // 2026-11-14 10:30

Datas nos filtros

Os parâmetros de data dos filtros usam datas de calendário no formato AAAA-MM-DD, com limites inclusivos. Quando você não informa start_date_from, a API usa a data de hoje no horário de Brasília (America/Sao_Paulo) para listar apenas viagens futuras.

Resumo

• Para exibir uma data de viagem, use starts_on e ends_on.
• Para exibir a hora de uma atividade, use datetime como veio.
• Para saber quando um registro foi criado ou alterado, use created_at e updated_at e converta para o fuso do leitor.