Modules Pay · Contratos MPay

Guia de Instalação

Passo a passo para enviar, ativar e configurar o addon Contratos MPay em uma instalação WHMCS, do zero até o primeiro contrato de teste.

15 seções

~20 minutos

PHP 8.1+ · WHMCS

1Visão geral

O que o módulo faz e onde ele fica dentro do WHMCS.

O Contratos MPay é um addon module para WHMCS que permite criar, gerenciar, assinar eletronicamente e disponibilizar contratos de clientes: geração de PDF, assinatura por desenho (caneta) ou por upload de PDF assinado externamente, envio por e-mail e WhatsApp, página pública de validação por QR Code, templates de mensagem e vínculo automático com produtos/serviços do WHMCS.

O diretório final do módulo dentro do WHMCS precisa ficar exatamente assim:

/modules/addons/contratosmpay/

Não renomeie a pasta. O WHMCS e os arquivos internos do módulo (rotas, includes, templates Smarty) dependem do nome exato contratosmpay.

2Requisitos antes de instalar

1WHMCS instalado e funcional, com acesso administrativo.
2Acesso ao FTP, gerenciador de arquivos ou terminal do servidor.
3PHP 8.1 ou superior.
4Banco de dados MySQL/MariaDB compatível com o WHMCS.
5Licença ativa do módulo Contratos MPay (Modules Pay).
6Um campo personalizado de cliente para CPF/CNPJ já criado no WHMCS (Setup > Custom Client Fields) — o módulo não cria esse campo automaticamente.

3Envio dos arquivos

Envie a pasta do módulo para o diretório de addons da instalação:

SEU_WHMCS/modules/addons/contratosmpay/

Conferência da estrutura

Depois do envio, confirme que estes arquivos existem dentro da pasta:

contratosmpay.php — controller principal e telas do admin
functions.php — utilitários, schema do banco, logs, criptografia
hooks.php — rotinas automáticas (cron, menu do cliente, criação por pedido aceito)
mycontratos.php — área do cliente
assinar-segundo.php — página pública de assinatura do segundo signatário (sem login)
NotificaZap.php — integração de envio por WhatsApp
apicontrato.php / download.php — endpoints de visualização e download
lib/ContratoManager.php — geração de PDF e página de validação
sql/install.sql — tabelas criadas na ativação

Cuidado com pasta duplicada. Se os arquivos ficarem em modules/addons/contratosmpay/contratosmpay/ (duas pastas aninhadas), o WHMCS não carrega o addon.

4Ativação no WHMCS

Acesse o painel administrativo do WHMCS.
Vá em Configurações > Addon Modules (Setup > Addon Modules).
Localize Gerenciador de Contratos na lista.
Clique em Activate.
Em seguida, clique em Configure para liberar o acesso aos grupos administrativos desejados (aba de permissões do addon).

A ativação executa sql/install.sql e cria as tabelas:

Tabela	Guarda
`mod_contratosmpay`	Contratos, status, dados de assinatura, caminhos de PDF e validade
`mod_contratosmpay_products`	Vínculo entre produtos/serviços do WHMCS e modelos de contrato
`mod_contratosmpay_logs`	Logs operacionais do módulo
`mod_contratosmpay_templates`	Templates de e-mail e WhatsApp
`mod_contratosmpay_config`	Configuração SMTP

5Configuração inicial

Depois de ativado, abra Addon Modules > Gerenciador de Contratos para preencher os campos da tela de configuração do WHMCS.

Campo	Obrigatório	O que faz
Número da Licença	Sim	Chave recebida da Modules Pay. Sem licença válida o painel administrativo do módulo fica bloqueado.
Campo CPF/CNPJ	Sim	Select com os campos personalizados de cliente já cadastrados no WHMCS — escolha o que guarda o CPF/CNPJ. Esse valor alimenta a variável `%CPFCNPJ%` no texto do contrato.
Período de Validade	Sim	Dropdown (30/60/90/180/365 dias) — prazo padrão usado para calcular a validade de um novo contrato.
Lembrete Antes do Vencimento	Não	Dropdown (Desativado/1/3/5/7/10/15 dias) — quantos dias antes do vencimento o cron avisa (e-mail/WhatsApp) um contrato ainda pendente. Enviado uma única vez por contrato.
Key do Servidor NotificaZap	Não	Preencha só se for enviar contratos por WhatsApp — ver seção WhatsApp.
Assinatura do Admin	Não	Sim/Não — mantenha habilitado quando o PDF final precisar exibir a assinatura do administrador ao lado da do cliente.

A licença precisa estar ativa para liberar o dashboard e as demais telas do módulo — sem isso, os botões de ação ficam desabilitados.

6Permissões de pastas

O módulo grava PDFs, minutas, logos e assinaturas em disco. Confirme permissão de escrita (usuário do PHP/servidor web) nestas pastas:

modules/addons/contratosmpay/storage/assinaturas
modules/addons/contratosmpay/storage/contratos
modules/addons/contratosmpay/storage/contratos/minutas
modules/addons/contratosmpay/storage/logos

Se alguma dessas pastas não existir, o módulo tenta criá-la sozinho (mkdir recursivo) — mas o diretório pai (storage/) precisa ser gravável para isso funcionar.

Atalho de manutenção: o dashboard tem um botão Fixar Permissões que roda fix_permissions.php para corrigir as permissões dessas pastas automaticamente.

Restrinja o acesso depois de usar. fix_permissions.php é uma ferramenta de manutenção controlada — depois de corrigir as permissões, evite deixá-lo acessível publicamente por longos períodos.

7Assinatura do administrador

No dashboard, clique em Gerar Assinatura. Abre um modal com um canvas onde você desenha a assinatura (mouse ou touch), com botões Limpar e Salvar Assinatura. O arquivo é salvo como PNG único em storage/assinaturas/assinatura_admin.png — salvar de novo sempre substitui o mesmo arquivo.

Pré-requisito para criar qualquer contrato. A assinatura do admin precisa existir antes de criar qualquer contrato — o botão Criar Novo Contrato do dashboard fica desabilitado até isso ser feito. Não é mais uma escolha por tipo de assinatura: hoje o cliente é quem decide, na própria área dele, se assina desenhando na tela ou baixando o PDF para assinar por fora (ver Guia de Utilização).

Essa assinatura aparece no PDF final ao lado da assinatura do cliente (ou sozinha, centralizada, se a assinatura do admin estiver desabilitada nas configurações).

8Cabeçalho do PDF

Tela Cabeçalho PDF no dashboard — define como o topo da primeira página do PDF (minuta e contrato final) aparece para o cliente. Duas opções de modo:

Retângulo colorido: cor de fundo e cor do texto (formato hex #RRGGBB), logo, nome da empresa, domínio, e-mail, telefone e Instagram exibidos sobre o retângulo.
Imagem própria: upload de uma arte de cabeçalho pronta (PNG/JPG/GIF, até 4 MB) — só pode ser selecionado depois de enviar pelo menos uma imagem.

Também define a fonte (Times, Helvetica, Courier ou DejaVu Sans) e a cor do texto usados no corpo do contrato. O logo (PNG/JPG/GIF, até 2 MB) é enviado separadamente e fica salvo em storage/logos/.

9Configuração de SMTP

Tela SMTP - Email no dashboard. Preencha host, autenticação (sim/não), usuário, senha, tipo de segurança (TLS/SSL/Nenhum), porta e endereço remetente.

Senha em branco = mantém a atual. Ao editar a configuração depois, o campo de senha aparece sempre vazio por segurança — só é alterada se você digitar um novo valor; deixando em branco, a senha salva anteriormente é preservada.

Sem SMTP configurado, o envio de contratos por e-mail falha (tanto o envio manual pelo admin quanto os disparos automáticos do cron).

10WhatsApp (integração NotificaZap)

O envio de contratos por WhatsApp usa a infraestrutura do produto NotificaZap (Modules Pay), sobre a API UAZAPI. Para habilitar:

Contrate/configure o NotificaZap e conecte o número de WhatsApp da empresa por lá.
Copie a Key do Servidor NotificaZap fornecida (um valor criptografado que, internamente, identifica a instância conectada no formato MPAY-{id}) e cole no campo de mesmo nome na configuração do addon.

O Contratos MPay não gerencia a conexão do WhatsApp — ele só descriptografa essa key, confirma que existe uma instância correspondente já conectada na API (consulta feita com a API Global a cada uso, sem gravar nada no banco) e usa o token daquela instância para enviar as mensagens.

Botão "WhatsApp" some se a instância não existir. Se a key não estiver preenchida, estiver com formato inválido, ou a instância correspondente não estiver conectada na UAZAPI, o botão de envio por WhatsApp simplesmente não aparece no dashboard — não é preciso desabilitar nada manualmente.

Deixe o campo em branco se não for usar envio por WhatsApp — o restante do módulo funciona normalmente sem essa integração.

11Templates e vínculo de produtos

Templates de e-mail e WhatsApp

Tela Templates no dashboard. Existem 4 templates fixos — Contrato Enviado, Contrato Assinatura, Contrato Renovação e Contrato Lembrete (usado pelo lembrete automático antes do vencimento, ver seção 5) — cada um em duas variações: e-mail (sempre disponível) e WhatsApp (só aparece se a integração do passo 10 estiver ativa). Preencha assunto e corpo de cada um; até serem salvos, um texto padrão sugerido é usado. Veja os placeholders disponíveis no Guia de Utilização.

Vincular produtos a modelos de contrato

Tela Produtos x Contratos — lista todos os produtos/serviços ativos do WHMCS; para cada um, selecione o modelo de contrato correspondente (os modelos vêm dos arquivos .txt da pasta templates/ do módulo). Esse vínculo é o que permite a criação automática do contrato quando um pedido daquele produto é aceito (hook AcceptOrder).

Produto sem modelo vinculado simplesmente não gera contrato automático — o admin ainda pode criar um contrato manualmente para o cliente a qualquer momento.

12Área do cliente

Depois de instalado, o módulo adiciona o item Meus Contratos na navegação da área do cliente automaticamente (via hook, sem configuração adicional). Por ali, o cliente visualiza, assina e baixa seus contratos — o fluxo completo está descrito no Guia de Utilização.

modules/addons/contratosmpay/mycontratos.php

Quando um contrato tem um segundo signatário, ele assina por uma página pública separada (sem precisar de conta no WHMCS) — confirme que esta URL fica acessível de fora:

modules/addons/contratosmpay/assinar-segundo.php

13Checklist de validação final

1O addon aparece ativo em Addon Modules.
2A licença foi aceita (sem mensagem de erro no topo do dashboard).
3O campo CPF/CNPJ foi selecionado.
4As pastas de storage/ têm permissão de escrita.
5A assinatura do administrador foi gerada (obrigatória para criar qualquer contrato).
6Pelo menos um template de e-mail (e de WhatsApp, se aplicável) foi salvo.
7Pelo menos um produto foi vinculado a um modelo de contrato.
8Um contrato de teste foi criado e aparece em "Meus Contratos" no client area.
9O PDF final é gerado corretamente depois da assinatura, com a página de validação e o QR Code.

Para auditoria e diagnóstico, acesse a tela de logs a qualquer momento:

addonmodules.php?module=contratosmpay&action=logs

14Atualização de versão

Faça backup dos arquivos do módulo.
Faça backup das tabelas mod_contratosmpay%.
Substitua os arquivos do módulo, mantendo a pasta storage/ intacta (contratos, minutas e assinaturas já gerados).
Acesse o addon no admin — isso roda a validação/ajuste automático do schema do banco.
Revise logs, templates, SMTP e vínculos de produtos após a atualização.

15Suporte

Em caso de dúvida, falha na instalação ou erro de licença, entre em contato com a Modules Pay:

Site: modulespay.com.br
E-mail: contato@modulespay.com.br

Antes de acionar o suporte, tenha em mãos: prints da tela de erro, versão do PHP, versão do WHMCS e os registros relevantes da tela de logs do módulo.