Por que a data de vencimento nunca deveria depender do fuso horário (e como isso quebra silenciosamente)

# Por que a data de vencimento nunca deveria depender do fuso horário

Se você já cobra clientes de forma recorrente — mensalidade de gestão de tráfego, plano fixo, retainer — provavelmente já viu isso acontecer em *algum* sistema: um boleto ou cobrança que aparece com vencimento em "29" quando devia ser "30", ou um resumo diário por e-mail que mostra a data errada por um dia. Não é falha de digitação. Na maioria das vezes é um bug de fuso horário — e ele é traiçoeiro porque só aparece perto da meia-noite.

O bug que a gente encontrou (e corrigiu) no nosso próprio sistema

No igency, o resumo diário por e-mail (o "digest") estava mostrando o vencimento de pagamentos e tarefas um dia antes do real. A causa: a data de vencimento é salva internamente como meia-noite UTC representando uma data de calendário (por exemplo, "10 de agosto" vira `2026-08-10T00:00:00Z`, sem hora local nenhuma — é só uma data, não um instante). O código do e-mail, porém, convertia essa data para o fuso `America/Sao_Paulo` antes de formatar. Como o Brasil está a 3 horas atrás de UTC (e não tem mais horário de verão), meia-noite UTC vira 21h do dia anterior no horário de Brasília — e a formatação exibia esse dia anterior.

O resultado prático: todo cliente que recebia o resumo diário via WhatsApp/e-mail via nosso digest via o vencimento errado, sempre um dia adiantado. Silencioso, consistente, e fácil de não notar — porque "um dia de diferença" parece só um pequeno atraso, não um bug.

A correção teve que separar dois conceitos que o código tratava como um só: - Datas-calendário (vencimento, data de competência) — nunca devem passar por conversão de fuso. Formatar direto em UTC (`formatDateUTC()`). - Instantes reais (quando um webhook do Stripe chegou, quando um pagamento foi confirmado) — esses sim fazem sentido em horário local, porque representam um momento específico do relógio.

Essa não foi a primeira vez que esse padrão apareceu no nosso código — é a mesma classe de bug que já tínhamos corrigido em outros três pontos do sistema antes. Fuso horário é, sem dúvida, uma das categorias de bug mais recorrentes em qualquer sistema de cobrança — porque o erro só se manifesta perto da virada do dia, e é fácil um teste manual "passar" só por não ter sido rodado às 21h-23h59.

Um segundo caso: recorrência que "encolhe" com o tempo

Outro bug relacionado, também de calendário: nossa rotina de despesas recorrentes lia o dia de recorrência a partir da última ocorrência já gerada. Isso parece razoável até você lembrar que fevereiro tem 28 dias. Uma despesa recorrente ancorada no dia 31 gera, em fevereiro, uma ocorrência no dia 28 (o clamp correto). Só que, se o sistema usa *essa* ocorrência de fevereiro como referência pro próximo mês, o dia 28 vira permanente — março, que tem 31 dias, também fica preso no 28, mesmo sem precisar.

A correção: usar sempre o maior dia-do-mês já visto em qualquer ocorrência da série, nunca a última gerada. Pequena mudança de lógica, grande diferença pra quem depende da data certa pra cobrar ou pagar uma despesa recorrente todo mês.

O que isso significa pra quem gerencia clientes e cobranças

Se você usa (ou está avaliando) qualquer ferramenta pra gestão de clientes e cobrança recorrente, vale perguntar: as datas de vencimento são tratadas como *datas de calendário* ou como *timestamps com fuso*? A diferença parece técnica, mas o efeito é muito prático — é a diferença entre um cliente receber a cobrança certa no dia certo, ou uma notificação de atraso um dia antes da hora.

No igency, depois de mapear esse padrão nos dois casos acima (e nos três anteriores), tratamos qualquer data-de-calendário nova no sistema — vencimento, competência, recorrência — com o mesmo cuidado: nunca passa por conversão de fuso antes de virar texto. É um detalhe pequeno de implementação que evita um problema grande de confiança: ninguém quer explicar pro cliente por que o vencimento "mudou" sozinho.