Agenda PRO: fuso horário do portal, do agendamento e do lembrete
Esta fonte é do aplicativo Agenda PRO. Agenda e Agenda PRO são dois aplicativos diferentes: nada aqui vale para a Agenda comum.
A REGRA QUE RESOLVE A MAIORIA DOS CHAMADOS
A data e a hora que o cliente escolhe são gravadas exatamente como ele escolheu. Não existe conversão que desloque o horário do agendamento. O que o Agenda PRO faz, quando o agendamento vem do portal, é preencher duas colunas extras: a data e hora convertidas para UTC e a data e hora no fuso detectado do cliente. Essas colunas são adicionais. Elas não substituem a data e a hora do compromisso.
Então "o cliente marcou 14h e entrou 13h" não é efeito da conversão de fuso do agendamento. O valor gravado é o escolhido. A diferença de uma hora aparece em quem lê e em quem envia: no fuso em que a sessão do portal está operando, que vem do cadastro da loja, e no deslocamento de fuso usado para calcular o lembrete. É nesses dois pontos que você deve olhar.
QUANDO O FUSO DO CLIENTE É DETECTADO
Só quando o agendamento vem do portal. O sistema considera portal quando existe sessão do portal, quando os dados enviados já trazem o campo de fuso do cliente, ou quando o formulário enviou esse campo. Agendamento criado por dentro do aplicativo, pela sua equipe, não passa por essa detecção e não recebe fuso do cliente.
A CASCATA DE DESCOBERTA DO FUSO, NA ORDEM
Toda a cascata roda no servidor, a partir do que o navegador informa no pedido. São sete etapas:
Primeira, o fuso que veio junto com o formulário. Segunda, o parâmetro tz no endereço. Terceira, o fuso que ficou guardado na sessão. Quarta, um palpite pelo idioma declarado pelo navegador. Quinta, um palpite grosseiro pela identificação do navegador. Sexta, o reconhecimento de acesso local ou de rede interna, que devolve America/Sao_Paulo. Sétima e última, America/Sao_Paulo como padrão.
O palpite por idioma usa uma lista fechada de 23 códigos. É esta, completa: en-US, en-us, en_US e es-US viram America/New_York; pt-BR, pt-br e pt_BR viram America/Sao_Paulo; es-ES vira Europe/Madrid; fr-FR vira Europe/Paris; de-DE vira Europe/Berlin; it-IT vira Europe/Rome; en-GB vira Europe/London; en-CA e fr-CA viram America/Toronto; es-MX vira America/Mexico_City; es-AR vira America/Argentina/Buenos_Aires; es-CL vira America/Santiago; es-CO vira America/Bogota; ja-JP vira Asia/Tokyo; zh-CN vira Asia/Shanghai; ko-KR vira Asia/Seoul; ru-RU vira Europe/Moscow; ar-SA vira Asia/Riyadh. Se o código exato não estiver na lista, o sistema tenta casar só pelo prefixo do idioma e usa o primeiro que bater.
O palpite pela identificação do navegador também é lista fechada, com sete casos: US vira America/New_York, BR vira America/Sao_Paulo, MX vira America/Mexico_City, AR vira America/Argentina/Buenos_Aires, GB ou UK viram Europe/London, DE vira Europe/Berlin e FR vira Europe/Paris. É um palpite por texto, não é localização.
A PÁGINA QUE GRAVA O FUSO NA SESSÃO DO PORTAL
O portal tem um endereço que recebe o fuso detectado e guarda na sessão. Ele aceita uma lista fechada de dez fusos, e apenas estes: America/Sao_Paulo, America/Manaus, America/New_York, America/Chicago, America/Denver, America/Los_Angeles, UTC, Europe/London, Europe/Paris e Europe/Moscow. Qualquer fuso fora desses dez é trocado por America/Sao_Paulo, e a resposta mesmo assim é de sucesso, informando o fuso já substituído.
Existe também um endereço do portal que faz a detecção pelo lado do servidor, usando exatamente a cascata acima, e guarda o resultado na sessão. Quando não consegue detectar nada, ele guarda America/Sao_Paulo e responde que usou o padrão do Brasil.
Ponto importante para o suporte: o fuso guardado por esses dois endereços não é reaproveitado em nenhum outro ponto do Agenda PRO — nem na gravação do agendamento, nem no cálculo do lembrete. Não prometa que salvar o fuso por esse caminho corrige exibição ou horário de envio. Se o caso for esse, colete os dados e encaminhe para verificação.
O FUSO DA LOJA
Quando o cliente entra no portal, a sessão dele recebe o fuso cadastrado na LOJA, e o sistema passa a operar nesse fuso. Esse campo é do cadastro de loja do ERP, não do Agenda PRO: ele é preenchido a partir da cidade da loja e, quando fica vazio, o ERP grava America/Sao_Paulo. Quem responde por esse campo é a fonte do cadastro de lojas. Se o fuso da loja estiver errado, toda a exibição do portal sai deslocada, mesmo com o agendamento gravado certo.
COMO O LEMBRETE CALCULA A HORA DE ENVIO
O lembrete não usa o fuso detectado do cliente. Ele usa o deslocamento de fuso gravado na configuração da loja do Agenda PRO. Quando esse deslocamento está vazio ou em branco, o sistema assume -03:00.
O cálculo é direto: a data e a hora do agendamento são lidas nesse deslocamento; a hora de envio é essa data e hora com a antecedência configurada aplicada (por padrão, uma hora antes); e a data limite é a própria data e hora do agendamento. O lembrete é gravado guardando o deslocamento usado, e quando o envio vai para a fila o mesmo fuso segue junto com a tarefa agendada. Vale tanto para o agendamento feito no portal quanto para o feito pela equipe no painel.
Os avisos de confirmação e de alteração são diferentes: eles são para envio imediato, e a hora de envio é o instante atual convertido para UTC.
Se o texto do lembrete estiver vazio, o agendamento na fila não acontece e o lembrete fica registrado com o erro pedindo que você configure o texto do lembrete na configuração da loja.
O QUE COSTUMA DAR ERRADO E O QUE CONFERIR
O cliente de fora do Brasil vê horário de São Paulo. Confira primeiro o fuso do cadastro da loja: é ele que a sessão do portal usa. Vale saber também que a gravação de fuso do portal só aceita os dez fusos da lista e troca os demais por America/Sao_Paulo sem avisar.
O lembrete chegou uma hora antes ou uma hora depois do esperado. Confira o deslocamento de fuso na configuração da loja — vazio faz o cálculo assumir -03:00 — e depois a antecedência configurada, que nem sempre é a que se imagina.
O agendamento foi criado pela equipe, por dentro do aplicativo, e o cliente reclama do horário do lembrete. Agendamento que não vem do portal não recebe fuso do cliente, e o lembrete continua saindo pelo deslocamento da loja.
O navegador do cliente está num idioma fora da lista de 23. A cascata cai no palpite grosseiro e, se ele também não bater, no padrão America/Sao_Paulo.
O horário aparece diferente entre o portal e a tela interna. Antes de tratar como erro, confirme qual é o fuso do cadastro da loja: é ele que manda na sessão do portal.
O QUE NÃO EXISTE
Não existe tela para o cliente final escolher o fuso dele. O que existe é a detecção automática descrita acima, feita no servidor a partir do que o navegador informa.
Não existe descoberta de fuso por localização real do cliente. A etapa que olha o endereço de rede só reconhece acesso local ou de rede interna e devolve America/Sao_Paulo; para qualquer outro acesso ela não devolve nada e a cascata segue adiante.
O QUE SEPARAR PARA O SUPORTE
Diga se o agendamento veio do portal ou foi criado por dentro do aplicativo. Informe a data e a hora que o cliente escolheu e a data e a hora que apareceram. Informe o fuso do cadastro da loja e o deslocamento de fuso e a antecedência gravados na configuração da loja no Agenda PRO. Para lembrete, informe o canal (SMS ou e-mail) e a hora em que a mensagem chegou.
Nunca envie token, chave ou senha em anexo ou no texto do chamado. Se você já colou alguma credencial em algum lugar, gere outra no portal do parceiro.