Dia, fuso e horários

Para: Fin · Dev — Conferido em 2026-10-18.

O Dracma usa dois relógios. O relatório de reconciliação conta o dia em UTC. As regras de saque (limite por dia, horário do automático, feriados) contam o dia no fuso da operação. Esta página diz qual relógio vale em cada caso.

O que é

Onde Relógio Detalhe
Relatório GET /v1/reconciliation Dia UTC O dia D cobre 00:00:00Z a 23:59:59Z e abre às 02:00 UTC de D+1 (carência de 2 horas).
Todos os instantes da API (created_at, paid_at, settled_at) UTC RFC 3339 com Z. Veja Convenções HTTP.
Janela diária de saque (windows.day, max_withdrawals_per_day, auto_max_per_day) Fuso da operação Dia civil de 00:00 a 24:00 no fuso.
Janela diária de depósito (deposit_windows.day) Fuso da operação Mesmo dia civil.
Teto agregado do automático por hora e por dia Fuso da operação Hora civil e dia civil local.
Horário do automático e feriados Fuso da operação Veja "Horário do automático" abaixo.
Janelas de 7 e 30 dias, e velocity em minutos Móveis 7 dias = 168 horas, 30 dias = 720 horas, contadas para trás a partir do pedido. Não dependem de fuso.

O fuso da operação é o campo timezone do conjunto de regras (GET /v1/rules). Uma operação nova nasce com America/Sao_Paulo (UTC−03:00).

Quem define o fuso

O Dracma define o fuso ao criar a operação. Para mudá-lo, peça uma mudança de regras: ela passa pela aprovação do painel como qualquer outra mudança (veja Decisão, limites e regras). O campo timezone aceita um nome IANA válido, como America/Sao_Paulo.

Quando usar

Consulte esta página quando:

  • um jogador diz que "o limite do dia ainda não zerou" ou "já zerou";
  • a conta do seu financeiro por dia civil não bate com o relatório do Dracma;
  • você quer saber por que um saque aprovado de madrugada ficou esperando.

Como funciona

  1. O motor de regras converte o instante do pedido para o fuso da operação.
  2. Para as janelas "do dia", ele soma os saques e depósitos desde 00:00 local até 24:00 local, contados pelo instante em que o pedido foi criado.
  3. Para as janelas de 7 e 30 dias, ele olha os últimos 168 e 720 horas, sem olhar o fuso.
  4. Para o horário do automático, ele confere o dia da semana, o feriado e a faixa de horas, também no fuso local.

Exemplo de borda entre os dois relógios

Um jogador na operação com America/Sao_Paulo pede um saque às 22:30 do dia 26 (horário local). Em UTC são 01:30 do dia 27.

Pergunta Resposta
Em que dia civil da operação o saque conta no limite diário? Dia 26 (local).
Em que dia UTC o item withdrawal aparece no relatório? Dia 27, pelo settled_at do pagamento.
Quando você pode baixar o relatório desse item? A partir das 02:00 UTC do dia 28.

Compare o seu livro com o relatório pelo settled_at em UTC, nunca pela sua data local.

Exemplos

PIX 24x7 e horário do automático

O PIX funciona 24 horas por dia, todos os dias. Não existe horário de corte bancário. O que existe é o horário do automático: uma regra da operação que diz quando o Dracma pode liberar saques sem revisão.

Por padrão, uma operação nova tem o automático ligado todos os dias, o dia inteiro, sem calendário de feriados. Os campos que controlam isso estão em GET /v1/rules:

Campo Efeito
auto_hours Faixa from/to em HH:MM no fuso da operação. null significa o dia inteiro. Se from for maior que to, a faixa cruza a meia-noite.
auto_hours_ext.days Dias da semana em que o automático roda: 1 segunda a 7 domingo.
auto_hours_ext.holidays.calendar null (nenhum) ou BR-national (feriados nacionais).
auto_hours_ext.holidays.extra Datas extras AAAA-MM-DD tratadas como feriado.
auto_hours_ext.outside_policy O que fazer com um saque fora do horário: defer ou review.

O que acontece com um saque fora do horário depende de outside_policy:

outside_policy Resultado
defer (padrão) O saque fica approved e espera a próxima abertura. O Dracma reconfere periodicamente e envia quando o horário abre.
review O saque vai para under_review com o motivo OUTSIDE_AUTO_HOURS. Uma pessoa decide.

Feriados nacionais

Com BR-national, o Dracma considera fora do horário nos dias 1º de janeiro, 21 de abril, 1º de maio, 7 de setembro, 12 de outubro, 2 de novembro, 15 de novembro, 20 de novembro, 25 de dezembro e na Sexta-feira Santa. Datas fora dessa lista entram por holidays.extra.

A mudança de qualquer um desses campos segue o fluxo de mudança de regras. Veja Regras (API).

Erros e casos de borda

  • Relatório antes de 02:00 UTC. GET /v1/reconciliation responde 409 day_open com Retry-After. Agende a rotina para depois das 02:00 UTC e não repita em laço.
  • Sem horário comum. O Dracma tem outras verificações internas diárias. Elas rodam em horários próprios, independentes do relatório. Não espere que o relatório abra junto com elas; conte só com as 02:00 UTC de D+1.
  • Saque approved parado fora do horário. Com outside_policy igual a defer, é o esperado. Veja Ciclo do saque.
  • Motor de regras fora na hora do envio. Um saque approved não é enviado sem conferência: ele espera e o Dracma tenta de novo. Nada sai sem passar pelas regras.

Veja também