Datas
A API trabalha com dois formatos de data, e só esses dois.
| Tipo | Formato | Exemplo | Onde aparece |
|---|---|---|---|
| Data com hora | ISO 8601, em UTC, sempre com o Z no fim | 2026-10-06T14:00:00.000Z | createdAt, updatedAt, paidAt, canceledAt, expiresAt |
| Data sem hora | AAAA-MM-DD | 2026-10-09 | vencimento do boleto (dueDate), previsão de repasse (expectedOn) |
UTC e o horário do Brasil
Toda data com hora vem em UTC, o horário de referência mundial. O horário de Brasília está
3 horas atrás: 2026-10-06T14:00:00.000Z são 11h00 em Brasília.
A regra prática: guarde e compare em UTC; converta pro horário local só pra mostrar.
const paidAt = new Date('2026-10-06T14:00:00.000Z');
paidAt.toLocaleString('pt-BR', { timeZone: 'America/Sao_Paulo' }); // "06/10/2026, 11:00:00"Cuidado com a virada do dia: uma venda paga às 22h30 de Brasília do dia 6 tem paidAt no dia 7
em UTC (2026-10-07T01:30:00.000Z). Relatório "por dia" precisa converter antes de agrupar.
Mandando datas pra API
Quando você filtra por período (from e to em GET /v2/transactions), mande a data com hora
e com fuso. Data sem hora ou sem fuso é recusada com 400 VALIDATION_ERROR.
| Você manda | Resultado |
|---|---|
2026-10-06T03:00:00.000Z | Aceito (UTC) |
2026-10-06T00:00:00-03:00 | Aceito (o mesmo instante, escrito no horário de Brasília) |
2026-10-06 | Recusado: falta a hora |
2026-10-06T00:00:00 | Recusado: falta o fuso |
Pra pegar "o dia 6 inteiro no horário de Brasília", use from=2026-10-06T00:00:00-03:00 e
to=2026-10-06T23:59:59-03:00. Na URL, lembre de codificar os caracteres especiais.
Datas sem hora
dueDate e expectedOn são dias do calendário, sem fuso: 2026-10-09 é o dia 9, e pronto. Não
transforme em data com hora (o fuso pode jogar pro dia anterior na hora de exibir).