v10.0.1

[Lm-Only]

Release — Sistema de Aluguel por PIX, Renovação e Aprovação de Entrada em Grupos

Esta versão consolida o sistema de aluguel do bot com pagamento por PIX automático e manual, renovação de planos, controle de grupos, prevenção de duplicidade e suporte completo para grupos que exigem aprovação de entrada por administrador.

O fluxo foi estruturado para reduzir ações manuais, preservar os dados após reinicializações e evitar que um grupo incorreto seja associado a um pagamento.

---

Principais recursos

• Pagamento automático por Mercado Pago PIX.
• Pagamento manual por chave PIX, com liberação pelo responsável.
• Envio automático de instruções ao cliente após a confirmação do pagamento.
• Entrada automática no grupo pelo link de convite.
• Suporte para grupos com a opção “Aprovar novas solicitações” ativada.
• Ativação automática do modo aluguel ao entrar no grupo.
• Registro e atualização automática do vencimento do aluguel.
• Renovação de grupos vencidos.
• Soma de dias quando o mesmo cliente compra novamente para um grupo ativo.
• Bloqueio de grupos já vinculados a outro cliente.
• Persistência de pagamentos, links, planos e solicitações pendentes.
• Tratamento de reinicializações sem perder solicitações de aprovação em andamento.
• Liberação temporária de mensagens privadas somente para clientes que estão concluindo o aluguel.

---

Configuração inicial

Antes de disponibilizar o sistema aos clientes, confirme os seguintes pontos:

1. O número do dono deve estar configurado corretamente nas configurações do bot.

2. O prefixo dos comandos deve estar definido. Todos os exemplos deste guia usam <prefixo>.
   Se o prefixo for !, por exemplo, <prefixo>plano 1 será !plano 1.

3. O bot deve estar conectado ao WhatsApp e com acesso à internet.

4. Para o funcionamento completo dentro dos grupos, é recomendado que o bot seja administrador.

5. Escolha pelo menos uma modalidade de pagamento:

   • Mercado Pago PIX automático;
   • Chave PIX manual;
   • Ou as duas opções, conforme a configuração da instalação.

---

Configuração do Mercado Pago PIX automático

O Mercado Pago permite criar cobranças PIX e confirmar os pagamentos automaticamente.

Definir token do Mercado Pago

Somente o dono do bot deve usar:

<prefixo>settokenmp <seu_access_token>

Exemplo:

!settokenmp APP_USR-0000000000000000-000000-00000000000000000000000000000000

Após configurar o token, os clientes poderão selecionar um plano e receber uma cobrança PIX gerada automaticamente.

Desativar Mercado Pago automático

Para desativar o sistema automático, use:

<prefixo>settokenmp 0

Também são aceitos valores como padrao, padrão e default.

Ao desativar o token, as cobranças automáticas pendentes armazenadas localmente são canceladas. Isso não remove a chave PIX manual, caso ela esteja configurada.

---

Configuração da chave PIX manual

A chave PIX manual é indicada quando o responsável deseja conferir cada pagamento antes de liberar o cliente.

Definir chave PIX

Use:

<prefixo>chavepix <sua_chave_pix>

Exemplo:

!chavepix email@exemplo.com

A chave pode ser CPF, CNPJ, telefone, e-mail ou chave aleatória.

Remover chave PIX manual

Use:

<prefixo>chavepix 0

Depois de removida, o pagamento manual deixa de ficar disponível até uma nova chave ser configurada.

---

Fluxo de pagamento automático

1. O cliente consulta os planos disponíveis com:

   <prefixo>planos

   Também podem existir atalhos como <prefixo>precos, <prefixo>alugar ou <prefixo>aluga.

2. O cliente escolhe o plano:

   <prefixo>plano <número_do_plano>

   Exemplo:

   !plano 1

3. O bot gera a cobrança PIX e envia os dados para pagamento.

4. O sistema verifica os pagamentos aprovados automaticamente em intervalos regulares.

5. Quando o pagamento é confirmado:

   • o responsável recebe uma notificação;
   • o cliente recebe a confirmação;
   • o cliente é autorizado temporariamente a conversar com o bot no privado;
   • o bot pede o link de convite do grupo.

6. O cliente envia o link do grupo no privado.

7. O bot valida o link, entra no grupo, ativa o aluguel e registra o vencimento.

8. O responsável recebe uma nova notificação informando:

   • cliente;
   • plano contratado;
   • valor;
   • grupo ativado;
   • data de vencimento.

---

Fluxo de pagamento manual por chave PIX

1. O cliente escolhe um plano normalmente:

   <prefixo>plano <número_do_plano>

2. O bot envia:

   • a chave PIX configurada;
   • orientações de pagamento;
   • um link pronto para o cliente entrar em contato com o responsável;
   • informações do plano escolhido.

3. O cliente realiza o pagamento e envia o comprovante ao responsável.

4. Depois de conferir o pagamento, o responsável libera o cliente com:

   <prefixo>liberar <número_do_cliente>

   Exemplo:

   !liberar 5583999999999

5. O cliente recebe a confirmação e a solicitação do link de convite do grupo.

6. O cliente envia o link no privado.

7. O bot entra no grupo, ativa o aluguel e registra o plano.

Também podem ser utilizados os comandos equivalentes:

• <prefixo>autorizarlink <número>
• <prefixo>liberarlink <número>
• <prefixo>confirmarpix <número>
• <prefixo>confirmar-pagamento <número>

A liberação manual é importante porque o bot não ativa o aluguel apenas pelo envio de um comprovante. A confirmação continua sob controle do responsável.

---

Como enviar o link do grupo

Depois que o pagamento for aprovado ou liberado, o cliente deve enviar o link de convite diretamente no privado do bot.

Formato aceito:

https://chat.whatsapp.com/SeuCodigoDoGrupo

O link pode estar acompanhado de texto. O bot identifica automaticamente o endereço do convite.

Antes de solicitar a entrada, o sistema valida o link e obtém as informações do grupo. Isso evita associar um pagamento a um grupo inválido ou inexistente.

---

Grupos com aprovação de entrada

Esta versão oferece suporte para grupos que possuem a opção “Aprovar novas solicitações” ativada.

Anteriormente, quando o bot solicitava entrada em um grupo desse tipo, o WhatsApp podia retornar um identificador indefinido. Isso fazia o sistema interpretar a solicitação como falha, mesmo que o administrador ainda pudesse aprovar o bot depois.

Agora o comportamento é o seguinte:

1. O cliente envia o link do grupo.

2. O bot consulta as informações do convite antes de solicitar a entrada.

3. O sistema salva de forma persistente:

   • número do cliente;
   • plano escolhido;
   • código do convite;
   • ID real esperado do grupo;
   • nome do grupo;
   • data da solicitação.

4. O bot envia a solicitação de entrada ao grupo.

5. Caso o grupo exija aprovação, o cliente recebe uma mensagem informando que a solicitação foi enviada.

6. O cliente não precisa reenviar o link.

7. O administrador do grupo aprova a entrada do bot.

8. Assim que o WhatsApp informa que o bot foi adicionado, o sistema compara o ID recebido com o ID salvo anteriormente.

9. Se o grupo for o mesmo:

   • o modo aluguel é ativado;
   • o plano é registrado;
   • o vencimento é calculado;
   • o cliente recebe a confirmação;
   • o responsável recebe a notificação;
   • a solicitação pendente é removida.

10. Caso o bot seja adicionado em outro grupo sem relação com uma solicitação de aluguel, nenhuma ativação é realizada.

O sistema não faz consultas contínuas aos grupos. A ativação depende dos eventos recebidos pelo WhatsApp, preservando o desempenho do bot.

As solicitações pendentes continuam registradas mesmo se o bot for reiniciado antes da aprovação. O arquivo de persistência utilizado é pix-aguardando-aprovacao.json.

---

Ativação automática do aluguel

Quando a entrada no grupo é confirmada, o sistema:

1. Cria as configurações padrão do grupo, caso ainda não existam.

2. Ativa o modo aluguel nas configurações do grupo.

3. Registra o grupo como ativo no sistema de aluguel.

4. Salva:

   • ID do grupo;
   • cliente responsável;
   • nome do grupo;
   • plano contratado;
   • data de contratação;
   • vencimento;
   • status do aluguel.

5. Envia a confirmação ao cliente.

6. Envia uma notificação detalhada ao dono do bot.

O cliente não precisa ser adicionado manualmente à lista premium para utilizar os recursos previstos no aluguel. O sistema reconhece o cliente pelo vínculo de aluguel registrado.

---

Regras para evitar grupos duplicados

O mesmo grupo não é registrado duas vezes para o mesmo cliente.

Quando um cliente envia novamente o link de um grupo já vinculado ao seu aluguel, o sistema analisa a situação:

Grupo ativo do mesmo cliente

Os dias do novo plano são somados ao vencimento atual.

Exemplo:

• grupo expira em 10 de agosto;
• cliente compra mais 7 dias;
• o novo vencimento será 17 de agosto.

O plano não reinicia a partir do dia da compra quando ainda existe tempo ativo.

Grupo vencido do mesmo cliente

O aluguel é reativado a partir do momento atual.

Exemplo:

• grupo venceu em 1 de agosto;
• cliente renova em 5 de agosto por 7 dias;
• o novo vencimento será calculado a partir de 5 de agosto.

Grupo vinculado a outro cliente

O sistema bloqueia a ativação.

Isso impede que um segundo cliente utilize o mesmo grupo para sobrescrever ou aproveitar o aluguel de outra pessoa.

---

Renovação de aluguel

O cliente pode consultar e renovar grupos vencidos com:

<prefixo>renovarbot

Também são aceitos:

• <prefixo>renovar
• <prefixo>renovar-bot
• <prefixo>renovar_bot

O fluxo funciona assim:

1. O bot procura grupos vencidos vinculados ao cliente.

2. Se não houver grupos vencidos, informa que não existe renovação pendente.

3. Se houver apenas um grupo vencido, ele é selecionado automaticamente.

4. Se houver mais de um grupo vencido, o cliente escolhe qual deseja renovar.

5. O cliente escolhe um novo plano.

6. O pagamento é processado pelo método configurado.

7. Após a confirmação:

   • o grupo é reativado;
   • o modo aluguel é mantido;
   • o vencimento é recalculado;
   • o cliente recebe a confirmação;
   • o responsável é avisado.

A renovação não exige que o cliente envie novamente o link do grupo, desde que o registro original ainda esteja disponível.

---

Comandos disponíveis para clientes

Comando	Função
<prefixo>alugar	Exibe ou inicia o fluxo de aluguel.
<prefixo>aluga	Atalho para o fluxo de aluguel.
<prefixo>planos	Mostra os planos disponíveis.
<prefixo>precos	Mostra valores e opções de plano.
<prefixo>plano <número>	Seleciona um plano e inicia o pagamento.
<prefixo>grupos	Consulta informações dos grupos de aluguel.
<prefixo>meusgrupos	Consulta os grupos vinculados ao cliente.
<prefixo>meu-aluguel	Consulta o aluguel atual.
<prefixo>renovarbot	Inicia a renovação de grupos vencidos.

Os comandos de aluguel podem ser usados no privado mesmo quando a proteção contra mensagens privadas estiver ativa.

Durante a etapa de envio do link, o cliente recebe uma liberação temporária no privado. Após a ativação do grupo, essa liberação é removida automaticamente.

---

Comandos disponíveis para o responsável

Comando	Função
<prefixo>settokenmp <token>	Define o token do Mercado Pago.
<prefixo>settokenmp 0	Desativa o Mercado Pago automático.
<prefixo>chavepix <chave>	Define a chave PIX manual.
<prefixo>chavepix 0	Remove a chave PIX manual.
<prefixo>liberar <número>	Libera o cliente após conferir o PIX manual.
<prefixo>autorizarlink <número>	Alternativa para liberar o cliente.
<prefixo>confirmarpix <número>	Alternativa para confirmar o pagamento manual.

Os comandos de configuração e liberação devem ser usados apenas pelo dono ou por administradores autorizados.

---

Persistência e reinicializações

O sistema salva os dados necessários para continuar funcionando após reinicializações, incluindo:

• cobranças automáticas pendentes;
• pagamentos manuais aguardando conferência;
• clientes aguardando o envio do link;
• planos associados aos clientes;
• grupos selecionados para renovação;
• solicitações de entrada aguardando aprovação de administrador.

Ao reiniciar o bot:

• cobranças automáticas continuam sendo verificadas;
• clientes que ainda precisam enviar o link permanecem autorizados no privado;
• pagamentos manuais continuam disponíveis para liberação;
• solicitações de entrada em grupos com aprovação continuam registradas;
• a aprovação posterior de um administrador ainda ativa o aluguel automaticamente.

Não apague os arquivos de dados persistentes durante atualizações, a menos que queira remover intencionalmente os registros existentes.

---

Atualização manual

Para instalações que utilizam um script de atualização, confirme que o script cria o arquivo de solicitações pendentes caso ele ainda não exista.

O conteúdo inicial deve ser:

[]

A atualização deve preservar os dados existentes. O arquivo não deve ser sobrescrito com uma lista vazia em instalações que já possuem solicitações aguardando aprovação.

Depois de atualizar os arquivos do sistema, reinicie o processo do bot.

---

Situações conhecidas e mensagens esperadas

Link expirado ou inválido

O bot informa que não foi possível verificar ou entrar no grupo.

Solução: gere um novo link de convite e envie novamente.

Bot banido do grupo

O WhatsApp pode retornar erro de autorização.

Solução: remova o banimento do bot ou use outro grupo.

Grupo atingiu o limite de participantes

O bot informa que não consegue entrar porque o grupo atingiu o limite.

Solução: libere uma vaga antes de enviar um novo link.

Grupo exige aprovação

O bot informa que a solicitação foi enviada.

Solução: o administrador deve aprovar a entrada do bot. Não é necessário enviar o link novamente.

Cliente envia outro link enquanto já existe uma aprovação pendente

O sistema bloqueia a troca automática para evitar que o pagamento seja associado ao grupo errado.

Solução: aguarde a aprovação atual ou peça ao responsável para avaliar o caso.

Pagamento manual ainda não foi liberado

O cliente deve enviar o comprovante ao responsável e aguardar a confirmação.

Solução: o responsável deve usar <prefixo>liberar <número_do_cliente> após conferir o pagamento.

Cliente não possui plano associado

Isso pode ocorrer se os dados antigos forem removidos manualmente.

Solução: o cliente deve entrar em contato com o suporte ou iniciar novamente o processo de compra.

---

Recomendações de operação

1. Configure corretamente o número do dono antes de ativar o pagamento manual.

2. Nunca compartilhe o token do Mercado Pago em grupos ou conversas públicas.

3. Mantenha o bot como administrador nos grupos alugados.

4. Oriente os clientes a enviar links válidos e recentes.

5. Em grupos com aprovação de entrada, instrua os administradores a aprovarem o bot após o cliente enviar o link.

6. Não remova os arquivos de persistência durante atualizações normais.

7. Use a renovação para grupos vencidos em vez de criar um novo aluguel desnecessário.

8. Verifique periodicamente os grupos alugados e os vencimentos pelo comando <prefixo>grupos.

9. Utilize a chave PIX manual somente quando houver conferência humana do pagamento.

10. Mantenha a chave PIX, o token Mercado Pago e os números de responsáveis atualizados.

---

This discussion was created from the release v10.0.1.