APIs e Integrações do Hotsite

São os serviços externos dos quais o hotsite depende. Saber qual serviço está por trás de cada tela ajuda o atendimento a separar uma falha geral de um problema de um participante só.

O hotsite novo fala com estes serviços:

• API Premify V2: é a principal e é crítica. Dela vêm a campanha, o formulário, login, cadastro, notas, números, saldo, pontos, posições, resgates, stories, convites, jogos da comunidade e ganhadores. Todas as regras de negócio estão nela. Sem a API, o hotsite não funciona.
• ViaCEP: preenche rua, bairro e cidade a partir do CEP. Se falhar, o participante preenche à mão.
• Serviço de consulta de NFC-e: usado só pela leitura do QR Code do cupom. Se falhar, o participante preenche à mão.
• Inteligência artificial (Gemini): sugere os produtos participantes a partir dos itens do cupom. É opcional; sem ela a tela avisa que a identificação automática está indisponível.

Como o hotsite conversa com a API:

• Mensagens de recusa vêm prontas da API, no idioma escolhido pelo participante. O hotsite mostra o texto como veio, sem reescrever. A tela só antecipa algumas recusas (idade, aceite, estado, CNPJ e chave da nota) com a mesma frase da API, para o participante corrigir antes de enviar.
• Limite de acessos por minuto: a API conta os acessos de cada visitante. Quem passa do limite vê "Muitos acessos agora" e precisa aguardar alguns segundos.
• Erro de leitura não vira lista vazia na área do participante: aparece "Não foi possível carregar" e, em erro do servidor, um "Código para o suporte". A exceção é a página pública de ganhadores, que mostra lista vazia se a API falhar.
• Dados públicos da campanha ficam guardados por até 60 segundos no hotsite, o que alivia a API. Dados do participante nunca ficam guardados.
• O hotsite novo não usa mais as rotas do sistema anterior (as antigas chamadas do FluxoBot e do backend legado). Quem ainda usa o sistema anterior é o hotsite legado, que é outro site.

O hotsite é a tela; as regras e os dados estão na API Premify V2. Quando a API recusa algo, o participante lê o motivo exato. Os serviços auxiliares (CEP, leitura do cupom e identificação de produtos) são atalhos: se falharem, o participante segue preenchendo à mão, sem perder a participação.

• Falha: várias telas mostram "Não foi possível carregar" ou "Sem conexão com o servidor" para muitos participantes.
• Possivel causa: API Premify V2 fora do ar ou instável.
• Como orientar: informe que o time técnico está verificando e peça para tentar de novo em alguns minutos.
• Quando escalar: acionar o time de desenvolvimento urgentemente e abrir issue no Jira (projeto DEV) com horário, link e prints.

• Falha: o CEP não preenche o endereço.
• Possivel causa: CEP incompleto, CEP não encontrado no ViaCEP ou ViaCEP fora do ar.
• Como orientar: oriente conferir os 8 dígitos e, se continuar, preencher o endereço à mão.
• Quando escalar: não é falha do hotsite quando o preenchimento manual funciona.

• Falha: a leitura do QR Code falha para todos.
• Possivel causa: serviço de consulta de NFC-e fora do ar.
• Como orientar: oriente preencher manualmente.
• Quando escalar: se durar mais de uma hora, abrir issue no Jira (projeto DEV).

• Falha: "Muitos acessos agora" aparece para muita gente ao mesmo tempo.
• Possivel causa: pico de acessos na campanha ou limite mal ajustado.
• Como orientar: peça para aguardar alguns segundos e tentar de novo.
• Quando escalar: se persistir por vários minutos para muitos participantes, acionar o time de desenvolvimento urgentemente e abrir issue no Jira (projeto DEV).