Skip to content

v10.0.1

Latest
Latest

Choose a tag to compare

View all tags
@Lm-Only Lm-Only released this 01 Aug 17:34
· 73 commits to main since this release
v10.0.1
b0ea542

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.

  6. Editar Tabelo do Bot

  • No arquivo 📂 ./src /menus /tabela-planos-bot.txt é possível editar a tabela de planos do bot
  • OBS: Lembre-se de editar os valores em 📂 ./src/commands/settings.js pois o bot não pode extrair magicamente os preços da tabela em texto.
  • • EXEMPLO
// ./src/comandos/settings.js - Final da linha
export const ALUGUEL_CONFIG = {
   multiGrupos: true,
   planos: [
       {
           nome: 'Plano Bronze 🥉 - 7 dias',
           dias: 7,
           valor: 5,
           ativo: true
       },
       {
           nome: 'Plano prata 🥈 - 15 dias',
           dias: 15,
           valor: 10,
           ativo: true
       },
       {
           nome: 'Plano Ouro 🥇 - 30 dias',
           dias: 30,
           valor: 20,
           ativo: true
       },
       {
           nome: 'Plano VIP 👑 - 60 dias',
           dias: 60,
           valor: 35,
           ativo: true
       },
   ]
}
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>tokenpix <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>tokenpix 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.
  1. 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.

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.

Assets 2
Loading
0 Join discussion