Um agente de suporte em um escritório, olhando para um chamado aberto às "3:47 AM", não tem ideia se isso é tarde para o cliente ou o meio do expediente dele. Registros de horário sem fuso horário são quase inúteis quando os clientes de uma empresa estão espalhados por vários continentes, e uma empresa de software com centrais de suporte em três regiões enfrentava isso o tempo todo. Os agentes abriam chamados, verificavam o país de cobrança do cliente e então pesquisavam manualmente se aquele país estava adiantado ou atrasado, errando com frequência suficiente para que "desculpe incomodar tão cedo" virasse piada recorrente no escritório.
A empresa substituiu o palpite por duas chamadas feitas quando um chamado chega. Primeiro, /v1/ip lê o endereço IP do visitante e retorna país, região, cidade e coordenadas, junto com um campo de fuso horário diretamente na mesma resposta. Para a maioria dos chamados, esse campo sozinho bastava. Para o número menor de casos em que mais precisão importava, como agendar um retorno de ligação, as coordenadas dessa consulta eram enviadas para /v1/timezone, que retorna o nome do fuso horário IANA e o deslocamento UTC atual daquele ponto exato, opcionalmente calculado para um momento específico, e não para agora.
O nome IANA importa mais do que parece. Um deslocamento UTC bruto muda com regras de horário de verão que variam por país e às vezes por região dentro de um país, então armazenar "UTC+2" no cadastro de um cliente fica errado, sem ninguém perceber, duas vezes por ano. Armazenar "Europe/Warsaw" significa que o deslocamento é sempre calculado corretamente para a data em que um chamado ou retorno estiver agendado, porque o banco de dados de fusos horários que o determina acompanha essas mudanças de regra à medida que acontecem.
A mudança visível foi uma pequena linha no topo de cada chamado: o horário local do cliente, naquele momento, ao lado do nome dele. Os agentes pararam de perguntar "já está tarde aí?" e passaram a abrir as mensagens com um "boa tarde" correto. O roteamento dos chamados também melhorou, depois que a fila passou a ordenar pelos clientes que estavam dentro do horário comercial na própria região, e não pela central de suporte que por acaso estava com equipe disponível.
Nada disso exigiu um banco de dados de correspondências entre país e fuso horário mantido à mão, que era a solução improvisada que a empresa usava antes e que quebrava toda vez que o IP de um cliente apontava para um país grande com vários fusos. Ler o fuso horário diretamente a partir das coordenadas eliminou toda essa categoria de erro.
O volume era baixo, uma consulta por novo chamado, bem dentro das 2.500 requisições gratuitas por dia incluídas na chave da empresa. A ferramenta de suporte sozinha nunca chegou perto de precisar de crédito pré-pago, embora a mesma chave atendesse outras partes do produto que precisavam.
O tratamento de fusos horários é um daqueles detalhes que os clientes só percebem quando está errado. Acertá-lo, discretamente, em segundo plano em cada chamado, é uma correção pequena com um efeito desproporcional na imagem que uma equipe de suporte transmite. A documentação dos dois endpoints está em /docs/ipv4-lookup/ e /docs/timezone-lookup/.