Documentação Técnica do Baita

Resumo executivo

• Como ler esta documentaçãoObjetivo, origem e convenções da Documentação Técnica Consolidada do Projeto Baita, que substitui o PDF de 08/07/2026.Ler tópico
• Escopo do Projeto BaitaPanorama de tudo que existe hoje no Baita: pagamentos, integrações, parceiros, sorteios, relatórios e canais de entrada.Ler tópico

Contexto de negócio

• Contexto de negócio do BaitaTrês modelos de negócio simultâneos (assinatura paga, base GZH e códigos de acesso) e as regras que atravessam todos os fluxos.Ler tópico
• Whitelabels e IDs do BaitaOs dois IDs de whitelabel que representam o Baita, o clube RBS de origem do catálogo e como agrupá-los em cada repositório.Ler tópico

Mecanismos por repositório

• Como o Baita é identificado no código (gates)Não há flag no schema: tudo é bespoke, gated por env ou por lista de UUIDs. Os 6 mecanismos do urbis-api e as convenções de Manager e Club.Ler tópico

Base de assinantes e cadastro

• BaitaIntegration — verificação de assinante GZHEndpoint, contrato, tratamento de erros e o bug histórico de normalização subscriber → isSubscriber, corrigido em produção.Ler tópico
• Nova Vida — enriquecimento cadastralPrefill de cadastro exclusivo do Baita, token criptografado por whitelabel e uso resiliente no Saque e Pague.Ler tópico
• Exclusões confirmadas — o que não é BaitaInfoline e a citação de Baratão em template de e-mail: por que ambos não fazem parte do escopo do projeto.Ler tópico

Marketing e eventos

• Salesforce Marketing Cloud — Data ExtensionsAuth OAuth2, migração para Data Extension única, payload, bugs corrigidos e o padrão fire-and-forget sem retry.Ler tópico
• Metryca — rastreamento de leads e renovaçõesEvento de lead, o novo evento de renovação disparado em 3 pontos e o casamento com o lead capturado no front.Ler tópico

Parceiros e pagamentos

• NFe.io — nota fiscal de serviçoOnde a emissão de NFS-e está ativa hoje e por que ela segue comentada no webhook PIX.Ler tópico
• Saque e Pague — assinatura em dinheiroTerceira forma de pagamento do Baita: endpoints, autenticação por API key, concorrência com advisory lock e ciclo de vida.Ler tópico
• Baratão Combustíveis — parceiro de posto de gasolinaAutenticação federada por JWT, webhook de compra, onboarding com cupons no Clube e a correção de segurança da accessKey.Ler tópico

Funil de cadastro

• Duas portas de entrada: /assinar e /cadastroDiferença entre o funil exclusivo do Baita e o fluxo unificado config-driven, com a configuração aplicada ao clube.Ler tópico
• Reestruturação do fluxo Baita RBSHeader com 3 estados, seletor "já é cliente?", cadastro inline no modal de código e a separação dos componentes de pagamento.Ler tópico

Planos e origem

• Planos exclusivos ocultosRegra de visibilidade de planos no Baita e os 3 casos explícitos de resolveBaitaPlansFilter.Ler tópico
• Rastreamento de origem PDV (origin)Como o parâmetro ?pdv= vira comissão: gravação em User.origin, propagação pelo metadata da Pagar.me e uso nos relatórios.Ler tópico

Conformidade e UX

• Lead capture — captura de leads parciaisComo o funil salva nome e e-mail antes da conclusão para permitir remarketing de quem abandona o cadastro.Ler tópico
• Endereço colapsado no cadastro (ADR-0006)Campo único somente-leitura no step de endereço e as duas válvulas de escape que impedem o usuário de travar.Ler tópico
• Confirmação de dados cadastrais antes de sorteio federalExigência regulatória da SPA aplicada a sorteios federais e como ela afeta o modal de sorteio do Baita.Ler tópico

PIX, cartão e webhooks

• PIX via Pagar.me e o webhook de pagamentoOrdem avulsa em vez de recorrência, criação de usuário só na confirmação, idempotência e o gap de HMAC.Ler tópico
• Webhook de invoices de cartãoO endpoint de recorrência de cartão, sua idempotência explícita e o problema dos +30 dias fixos.Ler tópico

Relatórios e operações

• Relatórios fiscais e unificadosEndpoints que cruzam Pagar.me com dados locais para apuração financeira mensal, com exportação em Excel.Ler tópico
• Reativação manual na Data ExtensionEndpoint administrativo criado para corrigir dessincronizações causadas pelo padrão fire-and-forget sem retry.Ler tópico

Jobs e crons

• Jobs e crons de assinaturaRotinas que expiram PIX/cash, reconciliam cartão, renovam token Nova Vida e expiram access codes — e a divergência de branch.Ler tópico

Elegibilidade e bilhetes

• Regra de elegibilidade mensal de sorteioCada compra ou renovação dá direito apenas ao sorteio do mês correspondente, com derivação diferente por forma de pagamento.Ler tópico
• Bilhete único por sorteio (conformidade regulatória)Cada usuário recebe um único número de 5 dígitos válido para todos os prêmios, ativado por tipo de sorteio e não por UUID.Ler tópico
• Geração automática de bilhete (planejado)PRD que propõe eliminar o clique manual "Participar" — não implementado, com pré-requisitos ainda pendentes.Ler tópico
• Endpoint dedicado de bilhete no onboardingComo o número da sorte é entregue logo após cadastro ou ativação de código, sem clique manual nesse ponto.Ler tópico

Apuração oficial

• Apuração Oficial de Sorteios no ManagerWorkflow guiado em 4 etapas, modos bidirectional e upward, reservas de aproximação e exportação de planilha via S3/CDN.Ler tópico

Configuração no Manager

• PIX exclusivo e configuração de planos no ManagerPor que o método PIX só aparece para o Baita no formulário de planos e o que some quando ele é selecionado.Ler tópico
• "Códigos de Acesso" no Manager — pausadoItem de menu exclusivo do Baita desativado na navegação e a branch histórica com QR Code pronta para reativar.Ler tópico

PDV e access codes

• Access codes e canal PDVGeração máquina-a-máquina, ativação pelo usuário com preservação de tag e cron de expiração em 30 dias.Ler tópico

Pareamento de catálogo

• Pareamento RBS → Baita (WLPairing)Replicação unidirecional, best-effort e idempotente do catálogo do clube RBS para o Baita.Ler tópico

Riscos ativos

• 🔴 Branch local com regressão pronta para ser mescladaO branch fix/gzh-flow-baita reintroduz o bug que classifica assinantes GZH legítimos como não encontrados.Ler tópico
• 🔴 Webhooks de pagamento sem validação de assinaturaDois webhooks públicos da Pagar.me sem HMAC, mitigados apenas por idempotência, e o padrão correto já existente na base.Ler tópico
• 🟡 +30 dias fixos em vez de addMonths no webhook de invoiceDivergência de cálculo de vencimento que afeta a elegibilidade de sorteio em bordas de mês.Ler tópico
• 🟡 Divergência main × develop no urbis-api72 commits em develop que main não tem e 46 no sentido oposto — alinhe antes de assumir o que está em produção.Ler tópico
• Débitos já conhecidos desde o PDF anteriorCinco débitos que continuam válidos: nome de plano frágil, example.env incompleto, UUIDs hardcoded, idempotência e logs sensíveis.Ler tópico

Variáveis de ambiente

• Variáveis de ambiente (checklist consolidado)Todas as envs BAITA_*, SAQUE_PAGUE_*, BARATAO_* e afins, com a finalidade de cada uma.Ler tópico

Apêndice e histórico

• Apêndice — nomenclatura e discrepâncias entre repositóriosComo o mesmo conceito é nomeado em urbis-api, urbis-manager e urbis-club, e por que "Baita RBS" não é um terceiro clube.Ler tópico