Manual de integração

Passo a passo para ligar o seu bot do Telegram e a sua conta de recebimento. Assim o cliente compra pelo bot, paga pelo link e entra sozinho no Grupo VIP. Leva uns 20 minutos.

Como tudo se conecta

O cliente só conversa com o bot. O painel faz o resto.

1 · TelegramO cliente envia /start e escolhe um plano

2 · PagamentoO bot manda o link do Mercado Pago ou do PicPay: PIX, saldo ou cartão

3 · ConfirmaçãoO pagamento aprovado inicia a vigência

4 · Grupo VIPO bot envia o convite e aprova a entrada

5 · VencimentoAvisa antes e remove do grupo se não renovar

O que você vai precisar: uma conta no Telegram, uma conta Mercado Pago (pessoa física ou jurídica) com uma chave PIX cadastrada e/ou uma conta PicPay Empresas e acesso ao painel como administrador.

1 Criar o bot do Telegram

O bot é a "loja": é ele que mostra os planos, manda o link de pagamento e controla o grupo.

No Telegram, procure por @BotFather (o perfil oficial tem o selo azul de verificado) e toque em Iniciar.
Envie /newbot.
Escolha o nome que aparece para os clientes, por exemplo VIP da Loja Bella.
Escolha o usuário do bot. Ele precisa terminar em bot, por exemplo lojabella_vip_bot. Será o link t.me/lojabella_vip_bot que você vai divulgar.
O BotFather responde com o token, uma sequência parecida com 7123456789:AAH4k…. Copie o token inteiro.
No painel, abra Integrações → Bot do Telegram, cole o token e clique em Salvar token do bot. Deve aparecer o selo verde @seu_bot.
Opcional (deixa o bot mais profissional), ainda no @BotFather:
- /setuserpic para a foto do bot;
- /setdescription para o texto que aparece antes do cliente tocar em Iniciar;
- /setabouttext para a bio do perfil.

Guarde o token como uma senha. Quem tiver o token controla o bot. Se ele vazar, envie /revoke no @BotFather, gere um novo e salve de novo em Integrações.

Ligar os grupos VIP e grátis

O bot precisa ser administrador para aprovar entradas, remover quem venceu e publicar as postagens.

Grupo VIP: crie um grupo no Telegram. Em Editar → Tipo de grupo, deixe-o Privado.
Em Administradores → Adicionar administrador, procure o seu bot e ligue estas permissões:
- Banir usuários, para remover quem não renovou;
- Convidar usuários via link, para gerar os convites com aprovação;
- Enviar/fixar mensagens, para as postagens agendadas.
Grupo grátis: faça o mesmo. Aqui basta a permissão de enviar mensagens.
No painel, abra Configurações. Os dois grupos aparecem na lista sozinhos. Escolha qual é o Grupo VIP e qual é o Grupo grátis e salve.

Pode ser canal em vez de grupo. Funciona do mesmo jeito: adicione o bot como administrador do canal, com permissão para publicar, convidar e banir.

O grupo não apareceu na lista? Remova o bot do grupo e adicione de novo como administrador, com o painel ligado. O bot só fica sabendo do grupo no momento em que é adicionado.

2 Conectar o Mercado Pago

Com o Mercado Pago, o bot gera um link de pagamento para cada compra (PIX, cartão e outras formas) e o acesso é liberado sozinho quando o pagamento é aprovado.

Entre em mercadopago.com.br/developers com a conta que vai receber o dinheiro.
Clique em Criar aplicação. Dê um nome (ex.: Grupo VIP) e, quando perguntar o tipo de solução, escolha Pagamentos online → Checkout Pro.
Dentro da aplicação, abra Credenciais de produção. Se pedir, preencha os dados do negócio (setor e site; pode usar o link do seu bot https://t.me/seu_bot) para ativá-las.
Copie o Access Token, que começa com APP_USR-.
No painel, abra Integrações → Mercado Pago, cole o Access Token e clique em Salvar Mercado Pago. O painel confere o token com o Mercado Pago antes de salvar.

Para oferecer PIX, cadastre uma chave PIX na conta Mercado Pago (no app: Seu perfil → Pix → Minhas chaves). Sem chave, o link mostra só cartão e outras formas.

Quer testar sem dinheiro de verdade? Use as credenciais de teste da aplicação (o painel mostra o selo teste). Pague com os cartões de teste que o Mercado Pago mostra na documentação. Depois troque pelas credenciais de produção.

Como o dinheiro chega na sua conta do banco

O pagamento cai primeiro no saldo da sua conta Mercado Pago. Daí você transfere para o banco quando quiser.

No app do Mercado Pago, em Seu perfil → Contas bancárias, cadastre a conta do banco que vai receber. Ela precisa estar no mesmo CPF/CNPJ da conta Mercado Pago.
Para sacar: Transferir → Para uma conta bancária (ou via PIX para uma chave sua).
Veja os prazos em Seu negócio → Custos e prazos. Normalmente PIX fica disponível na hora. Cartão segue o prazo de liberação escolhido, e prazos menores têm tarifa maior.

Taxas: São cobradas pelo Mercado Pago e descontadas de cada venda. Confira os valores atuais na sua conta, porque variam por forma de pagamento e prazo.
Comprovantes: Cada venda aparece no painel em Pagamentos, com o número do pagamento do Mercado Pago.

Aviso automático de pagamento (webhook)

Faz o cliente receber o link do grupo segundos depois de pagar. Sem o webhook o sistema também funciona: ele confere os pagamentos pendentes a cada 1 minuto.

O painel precisa estar publicado na internet com HTTPS (ex.: https://vip.seudominio.com.br). Rodando só no seu computador não há endereço público, então fica valendo a conferência a cada minuto.
Em Integrações → Endereço público, informe essa URL e salve. O painel mostra o endereço do webhook, algo como https://vip.seudominio.com.br/webhooks/mercadopago. Clique em Copiar.
No Mercado Pago Developers, dentro da sua aplicação, abra Webhooks → Configurar notificações. Cole a URL em Modo produção, marque o evento Pagamentos e salve.
O Mercado Pago mostra uma assinatura secreta. Copie e cole em Integrações → Assinatura secreta do webhook. Assim o sistema só aceita avisos que vêm de verdade do Mercado Pago.
Use o botão Simular do Mercado Pago para testar. O resultado deve ser 200.

3 Conectar o PicPay

O PicPay é a segunda forma de cobrança automática, ao lado do Mercado Pago. O bot gera um link do PicPay para cada compra. O cliente paga com saldo PicPay, PIX ou cartão, e o acesso é liberado sozinho.

Tipo de integração	O que o cliente vê	Dados do comprador
Link de pagamento recomendado	Página de pagamento do PicPay com saldo, PIX (de qualquer banco) e cartão.	Não pede nada além do Telegram. Tem ambiente de teste (sandbox).
E-commerce Wallet	Checkout da carteira PicPay.	O PicPay exige nome completo, CPF, e-mail e celular. O bot pergunta numa conversa curta e valida o CPF. Não tem sandbox.

Passo a passo (Link de pagamento)

Tenha uma conta PicPay Empresas (CNPJ) e entre no Painel PicPay Empresas.
Para testar primeiro: no menu lateral, abra Integrações. Em Credenciais Sandbox, no cartão Link de pagamento, clique em Gerar. Copie o client_id e o client_secret. O secret aparece uma única vez, então guarde-o num lugar seguro.
No painel do sistema, abra Integrações → PicPay. Escolha Link de pagamento e o ambiente Sandbox, cole o Client ID e o Client Secret e clique em Salvar PicPay. O sistema confere as credenciais no PicPay antes de salvar. Deve aparecer o selo Ativo · sandbox.
Em Configurações → Forma de cobrança no bot, escolha:
- Só PicPay: todo link sai pelo PicPay;
- Deixar o cliente escolher: depois de escolher o plano, o bot pergunta "Como você prefere pagar?" e mostra os botões Mercado Pago e PicPay. Os dois precisam estar configurados;
- Automático: usa o Mercado Pago se estiver configurado, senão o PicPay.
Para receber de verdade: no Painel PicPay Empresas, gere a credencial de produção da integração de link de pagamento. Em Integrações → PicPay do sistema, troque o ambiente para Produção, cole as credenciais novas e salve.

Aviso automático de pagamento (webhook do PicPay)

Sem o aviso, o sistema confere as cobranças PicPay pendentes a cada 1 minuto. Com o aviso, o convite chega em segundos.

O painel precisa estar publicado em HTTPS e a URL pública precisa estar preenchida em Integrações. O PicPay não aceita endereço IP nem URL com parâmetros (?…).
No Painel PicPay Empresas, abra o menu do canto superior direito → Configurações → aba Meu checkout. Ligue URL de notificação e cole https://SEU_DOMINIO/webhooks/picpay (o cartão PicPay em Integrações mostra o endereço pronto, com botão Copiar).
Clique em Salvar alterações. O PicPay gera uma API Key. Copie e cole em Integrações → PicPay → Chave do aviso de pagamento. Assim o sistema recusa avisos que não vêm do PicPay.

Segurança: o aviso do PicPay nunca libera o acesso sozinho. Ele só faz o sistema consultar a cobrança na API do PicPay, e o acesso só é liberado se a cobrança estiver paga e o valor pago for igual ao preço do plano. Se o valor vier menor, a cobrança continua aguardando e aparece o evento valor divergente.

Modo E-commerce Wallet (opcional)

Peça ao PicPay o acesso à API E-commerce (negocios@atendimento.picpay.com) e gere a credencial em Integrações → Gerar Token, no cartão da integração de Checkout.
Em Integrações → PicPay, escolha E-commerce Wallet, cole o Client ID e o Client Secret e salve. Esse modo só existe em produção. Teste com um plano de R$ 1,00 e estorne pelo Painel PicPay.
Na chave do aviso, cole o x-seller-token da sua conta. O PicPay envia o aviso para /webhooks/picpay automaticamente quando a URL pública está configurada.
No bot, na primeira compra pelo PicPay, o cliente informa nome completo (se o Telegram não tiver sobrenome), CPF, e-mail e celular. Se algum dado estiver errado, ele pede de novo. Os dados ficam salvos para as próximas compras. O botão Corrigir meus dados refaz a conversa e /cancelar desiste.

LGPD: o CPF, o e-mail e o telefone ficam no banco do sistema e servem só para a cobrança no PicPay. No painel, o CPF aparece mascarado no detalhe do assinante. Se você não precisa desse modo, use o Link de pagamento, que não pede esses dados.

Sem conta PicPay Empresas?

Alternativa	Como funciona	Liberação do acesso
PIX pelo link do Mercado Pago	O cliente abre o link do Mercado Pago, escolhe PIX e paga com o app do PicPay, que paga qualquer PIX.	Automática
Pagamento manual no PicPay	Sem Mercado Pago e sem PicPay configurados, o bot mostra a sua instrução de pagamento: o seu `@usuario` do PicPay ou a chave PIX. Configure o texto em Configurações → Instrução de pagamento manual.	Você confere e clica em Pagamentos → Aprovar

4 Teste de ponta a ponta

Faça uma compra real de valor baixo antes de divulgar.

Em Integrações, clique em Testar conexões. O Telegram e o Mercado Pago (e/ou o PicPay) devem aparecer em verde.
Em Planos, crie um plano Teste de R$ 1,00 com 1 dia.
Com outra conta do Telegram (ou a sua), abra t.me/seu_bot e envie /start. Os planos devem aparecer.
Escolha o plano Teste e pague o link com PIX. Para testar o PicPay no sandbox, deixe Configurações → Forma de cobrança em Só PicPay. O bot manda o botão Pagar com PicPay, e no painel a cobrança aparece em Pagamentos com a forma PicPay.
Em alguns segundos (com webhook) ou até 1 minuto (sem webhook), o bot avisa Pagamento confirmado e manda o botão Entrar no Grupo VIP.
Toque no botão e peça para entrar. O bot aprova sozinho. No painel, o assinante aparece como Ativo e No grupo ✅.
Para testar a remoção, abra o assinante no painel e clique em Revogar e remover do grupo.
Ao terminar, desative ou exclua o plano Teste em Planos. Se quiser, devolva o valor pelo Mercado Pago ou pelo Painel PicPay Empresas.

Problemas comuns

O que acontece	Causa provável e solução
"Token inválido — confira com o @BotFather"	O token foi copiado pela metade ou foi revogado. Copie de novo no @BotFather (`/mybots → seu bot → API Token`).
O bot não responde ao `/start`	O painel está desligado ou o token não foi salvo. Veja o selo em Integrações. Se a mesma cópia do sistema roda em dois lugares ao mesmo tempo, os dois disputam as mensagens: mantenha só um ligado.
O grupo não aparece em Configurações	Remova o bot do grupo e adicione de novo como administrador, com o painel ligado.
O cliente pagou e não recebeu o link	Veja em Pagamentos se a cobrança ainda está "Aguardando". Confira se o Grupo VIP está escolhido em Configurações. Se preciso, abra o assinante e clique em Reenviar link do grupo.
"Não consegui gerar o link de pagamento"	Access Token errado, de teste no lugar de produção, ou credenciais de produção ainda não ativadas no Mercado Pago.
"Client ID ou Client Secret do PicPay inválido para este ambiente"	Credencial de sandbox com o ambiente em Produção (ou o contrário), credencial de outro produto (ex.: Pix em vez de Link de pagamento) ou secret copiado pela metade. Gere de novo no Painel PicPay Empresas.
Pagou no PicPay e o acesso não liberou	Veja em Pagamentos se ficou "Aguardando" e confira os eventos do assinante. Com valor divergente, o valor pago foi menor que o do plano. Sem webhook, espere até 1 minuto.
O link não mostra a opção PIX	Falta cadastrar uma chave PIX na conta Mercado Pago.
O bot não remove quem venceu	O bot perdeu a permissão de Banir usuários, ou a pessoa é administradora do grupo (administradores não podem ser removidos pelo bot).
O cliente não recebe mensagens do bot	O cliente bloqueou o bot ou nunca enviou `/start`. O Telegram só deixa o bot falar com quem iniciou a conversa.