Guia de Utilização
Como usar o addon no dia a dia: telas do administrador, o fluxo de assinatura do cliente e a página pública de validação por QR Code.
1Dashboard
Tela inicial do módulo. No topo, o título mostra a versão instalada e um indicador se a assinatura do administrador já foi gerada.
Barra de ações
Criar Novo Contrato, Gerar Assinatura, Produtos x Contratos, Cabeçalho PDF, Templates, SMTP - Email, Logs, Fixar Permissões e Ver Requisitos. Os botões que dependem de licença (todos, exceto Logs, Fixar Permissões e Ver Requisitos) ficam desabilitados se a licença não estiver ativa. Criar Novo Contrato também fica desabilitado enquanto a assinatura do admin não existir (ver seção 2).
Cards de resumo
Total de contratos, Pendentes (aguardando assinatura), Assinados (concluídos) e Vencidos — contratos que passaram da validade sem nunca ter sido assinados. Um contrato assinado que só chegou ao fim da vigência continua contando como Assinado, não como Vencido.
Filtros
Busca livre (ID, modelo, serviço ou nome do cliente), Status (Todos/Pendente/Assinado), Data Início, Data Fim e Modelo. O botão Exportar CSV ao lado exporta a lista já com esses mesmos filtros aplicados (ver seção 10).
Tabela de contratos
Colunas: ID, Cliente (link para o resumo do cliente no WHMCS), Modelo, Serviço, Validade, Status pendente assinado vencido e Ações.
| Ação na linha | Quando aparece |
|---|---|
| Visualizar | Sempre — abre a tela de detalhe do contrato |
| Editar | Só em contratos pendente — abre modal de edição |
| Sempre — abre modal de confirmação de envio | |
| Sempre visível — a checagem se a instância existe de verdade só acontece ao clicar (ver seção 6) | |
| Excluir | Sempre — pede confirmação (reforçada se o contrato já estiver assinado, ver seção 7) |
2Criar um novo contrato
No dashboard, clique em Criar Novo Contrato. Preencha:
- Cliente — busca com autocompletar.
- Serviço — carregado por AJAX depois de escolher o cliente.
- Modelo — carrega o texto padrão daquele modelo de contrato (variáveis já preenchidas automaticamente).
- Validade — data de vencimento.
- Segundo signatário (opcional) — marque a caixa "Este contrato precisa de um segundo signatário" para exigir uma segunda assinatura (ver seção 8).
- Texto do contrato — editável antes de salvar.
Variáveis do texto
O texto do modelo aceita: %NOME%, %CPFCNPJ%, %NUMERO%, %ENDERECO%, %SERVICO%, %VALOR%, %CIDADE%, %UF% e %DATA% — todas substituídas automaticamente pelos dados do cliente/serviço no momento da criação.
3Editar um contrato
Disponível só para contratos pendente. Permite ajustar serviço, validade e o texto do contrato (cliente e modelo ficam fixos). Contratos assinado não podem mais ser editados.
4Visualizar contrato e histórico
Clique em Visualizar em qualquer linha para abrir a tela de detalhe: dados do cliente, modelo, serviço, validade, status e — se já assinado — nome do assinante, data e IP, com o PDF final embutido na página. Se o contrato tiver um segundo signatário, o status dele (assinou / aguardando) também aparece aqui.
Bloco "Assinatura por Caneta"
Visível em contratos ainda não assinados. Todo contrato novo já nasce com esse caminho liberado (ver seção 2); o botão Assinar Agora aqui só é necessário para liberar manualmente em contratos criados antes dessa mudança.
Bloco "Assinatura Digital"
Também visível em contratos não assinados. Dois botões:
- Baixar PDF — baixa a minuta (sem assinaturas) para o admin assinar externamente, se for esse o processo interno da empresa.
- Enviar PDF Assinado pelo Admin — upload de um PDF (até 20 MB) já assinado pelo admin fora do sistema. Isso substitui a minuta que o cliente baixa para assinar por fora e reenviar.
Histórico deste Contrato
Card na parte de baixo da tela, listando só os eventos deste contrato específico (criado, editado, enviado por e-mail/WhatsApp, assinado, excluído, etc.) — os mesmos registros da tela de Logs, já filtrados. Tem um atalho para abrir a tela de Logs com esse mesmo filtro aplicado.
5Enviar contrato por e-mail
Botão E-mail no dashboard ou na tela de visualização. O template usado depende do status do contrato no momento do envio:
| Status | Template usado |
|---|---|
| pendente | Contrato Assinatura |
| assinado | Contrato Enviado (com o PDF final anexado) |
| expirado | Contrato Renovação |
Requer SMTP configurado — sem isso, o envio falha e o módulo aponta o problema.
6Enviar contrato por WhatsApp
O botão WhatsApp aparece sempre em todo contrato, mesmo sem a integração configurada. A checagem só acontece quando você clica: o sistema confirma na hora se existe uma instância conectada de verdade (ver guia de instalação).
- Existe: abre o modal de confirmação normalmente; ao confirmar, envia o template correspondente ao status, com um botão "Acessar Painel" que abre direto a área do cliente — contratos assinado vão com o PDF anexado.
- Não existe ou não está configurada: mostra um aviso ("A instância do WhatsApp não existe ou o serviço de WhatsApp NOTIFICAZAPI não está ativo...") em vez de abrir o modal.
7Reenviar para assinatura e excluir
Enviar Novamente para Assinatura
Na tela de visualização — usado quando o PDF de um contrato antigo falhou ou corrompeu. Cria um contrato novo (mesmo texto, serviço e validade, com um novo hash) e avisa o cliente por e-mail que precisa assinar de novo.
Excluir Contrato
Pede confirmação antes de executar. Não apaga o PDF nem o registro em definitivo — o contrato fica marcado como excluído: some do dashboard, da tela de visualização direta e da área do cliente, mas pode ser recuperado pelo suporte se necessário.
8Segundo signatário
Para contratos que precisam de duas assinaturas (ex.: sócio, cônjuge, testemunha), marque a caixa "Este contrato precisa de um segundo signatário" na criação (ver seção 2) e informe nome e e-mail dele. O segundo signatário não precisa ter conta no WHMCS.
- O cliente principal assina normalmente (por caneta ou PDF externo). O contrato continua pendente mesmo depois disso.
- O sistema envia automaticamente um e-mail ao segundo signatário, com um link próprio e único.
- Pelo link, ele revisa o contrato e assina numa página pública simples (nome + desenho da assinatura), sem precisar fazer login em lugar nenhum.
- Assim que ele assina, o PDF final é gerado com as duas assinaturas lado a lado e o contrato passa para assinado.
Na tela de visualização do contrato, o status do segundo signatário aparece junto com o do cliente principal ("Aguardando assinatura" ou "Assinou em ...").
9Lembrete automático antes do vencimento
Configurável na tela de configuração do addon, campo Lembrete Antes do Vencimento (Desativado/1/3/5/7/10/15 dias). Quando ativo, o cron diário do WHMCS avisa automaticamente — por e-mail e, se configurado, WhatsApp — todo contrato pendente cuja validade esteja a N dias ou menos de vencer.
O aviso usa o template Contrato Lembrete (ver seção 12) e é enviado uma única vez por contrato — não repete todo dia dentro da janela.
10Exportar CSV
Botão Exportar CSV, ao lado de "Filtrar"/"Limpar" no dashboard. Baixa um arquivo CSV (ID, Cliente, Modelo, Status, Validade, Data de Assinatura, Assinado Por, Criado em) com a lista de contratos — respeitando os mesmos filtros (busca, status, período, modelo) que estiverem aplicados na tela no momento do clique.
11Produtos x Contratos
Lista todos os produtos/serviços ativos do WHMCS com um seletor de modelo de contrato por linha. Salvar essa tela atualiza de uma vez todos os vínculos — produtos sem modelo selecionado ficam sem geração automática de contrato.
12Templates de mensagem
Quatro templates fixos, cada um em versão e-mail (sempre disponível) e WhatsApp (só com a integração ativa): Contrato Enviado, Contrato Assinatura, Contrato Renovação e Contrato Lembrete (usado pelo lembrete automático, ver seção 9). Cada card tem campos de Assunto e Texto — salvos individualmente.
Variáveis disponíveis no texto
| Variável | Substituída por |
|---|---|
{client_name} | Nome do cliente |
{contract_id} | Número/ID do contrato |
{servico_nome} | Nome do serviço vinculado |
{validade_contrato} | Data de vencimento do contrato |
{link_painel} | URL do painel do cliente (WHMCS) |
{empresa_nome} | Nome da empresa |
13Logs e permissões
Tela Logs — histórico de eventos do módulo (criação, edição, assinatura, expiração, envios e erros). Use para investigar falhas de envio ou geração de PDF. Os filtros incluem Nível, Nº do contrato (pra ver só os eventos de um contrato específico), período e quantidade de registros.
Botão Fixar Permissões — corrige, sob demanda, as permissões das pastas de storage/ quando algum upload ou geração de PDF falhar por permissão.
14Meus Contratos
A página mostra dois blocos:
- Contratos Pendentes/Expirados — aguardando assinatura.
- Contratos Assinados — já concluídos, com data da assinatura e opções de visualizar/baixar.
Com mais de 5 contratos em qualquer um dos blocos, aparece um campo de busca por ID ou serviço, filtrando a tabela na hora.
Todo contrato novo já nasce com as duas colunas de ação liberadas ao mesmo tempo (ver seção 2):
| Coluna | O que oferece |
|---|---|
| Assinatura por Caneta | Botão Assinar Contrato — desenhar a assinatura na tela |
| Assinatura Digital | Botões Baixar PDF e Enviar PDF Assinado — assinar por fora e reenviar |
15Assinar por caneta (desenho na tela)
Clicar em Assinar Contrato abre um modal com:
- O texto completo do contrato, para leitura.
- Campo Nome do Assinante, pré-preenchido com o nome do cliente.
- Um quadro de assinatura onde o cliente desenha com o mouse ou o dedo (touch), com botões Desfazer e Limpar Assinatura.
- Checkbox obrigatório de aceite dos termos do contrato.
- Botão Assinar Contrato, que só libera quando os três itens acima estiverem preenchidos.
Ao confirmar, o sistema salva a assinatura desenhada, gera o PDF final (já com a página de validação e QR Code) e muda o status do contrato para assinado imediatamente.
16Enviar PDF assinado (assinatura externa)
Alternativa ao desenho na tela — usada quando o contrato é assinado fora do sistema (assinatura digital com certificado, por exemplo). Clicar em Enviar PDF Assinado abre um modal com:
- Link para baixar a minuta em PDF.
- Campo Nome do Assinante.
- Upload do arquivo PDF já assinado (até 20 MB, apenas
.pdf). - Checkbox de confirmação de que o arquivo enviado é o contrato assinado.
Ao enviar, o PDF substitui o contrato final oficial, o status muda para assinado e fica registrado que a assinatura veio por upload de PDF (sem imagem de assinatura desenhada).
17Baixar e visualizar contratos
Nos Contratos Assinados, o cliente tem botão Visualizar (abre o PDF final embutido num modal) e link Download (baixa o arquivo). Nos pendentes, o link Baixar Minuta em PDF baixa a minuta — se o admin já tiver enviado uma minuta pré-assinada por ele, é esse arquivo que é baixado; senão, uma minuta em branco é gerada na hora.
18QR Code de validação no PDF
Todo PDF final gerado pelo módulo (contrato assinado ou minuta) termina com uma página de validação contendo:
- Um QR Code apontando para a página pública de validação do sistema.
- O hash SHA-256 de integridade do texto do contrato.
Ao escanear o QR Code (ou abrir o link diretamente), a página exibe:
- Se o contrato está assinado e válido: nome de quem assinou, data/hora da assinatura, IP de origem, o hash SHA-256 e um botão para baixar o PDF.
- Se o contrato ainda está pendente: aviso de que o contrato ainda não foi assinado.
- Se o hash não corresponde a nenhum contrato: aviso de contrato não encontrado.