Guia de Utilização

Da criação da fatura até a baixa do pagamento, tudo acontece automaticamente por meio de hooks conectados ao ciclo de vida da fatura no WHMCS.

• Fatura criada no WHMCSO módulo cadastra o cliente no Asaas (se necessário) e gera a cobrança em boleto.
• E-mail enviado ao clienteCom botão de pagamento, linha digitável e, opcionalmente, PDF anexado.
• Cliente paga o boletoO Asaas notifica o WHMCS via webhook e a fatura é baixada automaticamente.
• Ou o admin lança o pagamento manualmenteO módulo confirma o recebimento no Asaas para manter os dois sistemas sincronizados.
• Fatura canceladaA cobrança correspondente é removida no Asaas.
• Rotinas diárias de manutençãoSincronizam PDFs, limpam arquivos antigos e removem cobranças vencidas há muito tempo.

Disparada assim que uma fatura é criada, usando o gateway Asaas - BOLETO.

Sempre que uma fatura nova é gerada para um cliente com este gateway selecionado como forma de pagamento, o módulo:

1. Confirma se a licença está ativa e se o gateway está habilitado.
2. Verifica se o cliente já existe no Asaas pelo CPF/CNPJ; se não existir, cadastra automaticamente.
3. Monta os dados da cobrança (valor, vencimento, multa, juros, desconto antecipado, taxa fixa/percentual, se configurados).
4. Verifica se já existe uma cobrança para aquela fatura no Asaas — evita duplicidade.
5. Cria a cobrança e salva localmente a linha digitável, a URL do boleto e o PDF.

O módulo enriquece os templates de e-mail do WHMCS com dados do boleto.

Templates afetados: Invoice Created, Invoice Modified, Invoice Payment Reminder, First/Second/Third Invoice Overdue Notice e Invoice Payment Confirmation.

Merge fields disponíveis

Insira esses merge fields nos templates de e-mail em Setup → Email Templates nos pontos onde o botão/linha digitável deve aparecer.

Na área do cliente, ao visualizar a fatura, o cliente vê o botão “Pagar com Boleto”.

• O botão respeita o valor mínimo configurado — abaixo dele, o cliente vê um aviso pedindo para escolher outra forma de pagamento.
• Taxa fixa e/ou percentual, se configuradas, são exibidas somadas ao valor original antes de abrir o boleto.
• O boleto abre em nova aba, processado por um token de ação com validade curta, específico daquela fatura.

Feita pelo callback (webhook) — não depende de nenhuma ação manual no WHMCS.

Quando o Asaas envia os eventos PAYMENT_RECEIVED ou PAYMENT_CONFIRMED para a URL de callback configurada, o módulo:

1. Valida o token de autenticação do webhook.
2. Localiza a fatura pelo externalReference da cobrança.
3. Marca a fatura como paga no WHMCS.
4. Remove o PDF local do boleto, já que não é mais necessário.

Mantém o Asaas sincronizado quando o admin marca a fatura como paga direto no painel.

Se um administrador marcar uma fatura como Paid diretamente no WHMCS (fora do fluxo do boleto), o módulo identifica a cobrança correspondente no Asaas e a confirma como recebida em dinheiro, evitando que a cobrança fique pendente ou vencida no Asaas enquanto já está quitada no WHMCS.

Cobre reaberturas de fatura e alterações de valor/itens.

Quando uma fatura volta ao status Unpaid ou tem seu total atualizado, o módulo verifica se já existe cobrança no Asaas:

• Se existir e ainda estiver PENDING ou OVERDUE, a cobrança é atualizada (novo valor/vencimento).
• Se não existir, uma nova cobrança é criada no Asaas.

Em ambos os casos, a linha digitável e o PDF são regravados localmente.

Mantém o Asaas alinhado quando uma fatura é cancelada no WHMCS.

Ao cancelar uma fatura desse gateway no WHMCS, o módulo localiza a cobrança correspondente no Asaas e a remove, registra o evento no histórico de transações da fatura e apaga o PDF local do boleto. O status da fatura é atualizado para cancelled mesmo que a cobrança não seja encontrada no Asaas (por exemplo, se já tiver sido removida manualmente por lá).

Consulta em tempo real, sem precisar abrir o painel do Asaas.

Ao abrir uma fatura no admin do WHMCS que usa este gateway, um painel extra mostra o status atual da cobrança no Asaas — PENDENTE, VENCIDO, CONFIRMADO, RECEBIDO, RECEBIDO EM DINHEIRO ou CANCELADO — junto com a data de criação e um link direto para o boleto.

Executadas junto com o cron padrão do WHMCS — nenhuma configuração extra de cron é necessária.

Acessíveis pelos atalhos no rodapé da tela de configuração do gateway.

Logs de transações

{seu-dominio}/modules/gateways/asaasboletompay/logs_report.php

Interface web com todos os eventos registrados pelo módulo (criação de boleto, erros de API, confirmações, cancelamentos etc). Permite filtrar por tipo de log e por período, e apagar todos os registros de uma vez (requer sessão de admin e token de confirmação).

Setar permissões

{seu-dominio}/modules/gateways/asaasboletompay/set_permissions.php

Reaplica as permissões corretas nas pastas do módulo e de hooks — útil depois de uma atualização de arquivos via FTP que tenha resetado permissões.

• O gateway está disponível apenas em português e suporta exclusivamente Real (BRL) como moeda.
• O botão de pagamento foi desenvolvido para o tema padrão do WHMCS (Bootstrap). Em temas muito customizados, confirme que o JavaScript necessário continua funcionando.
• É indispensável configurar o webhook no Asaas — sem ele, nenhuma baixa automática de pagamento ocorre.
• Cancelamentos e alterações de fatura feitos originados pelo próprio callback do Asaas não geram ações duplicadas de volta para o Asaas — o módulo detecta esse contexto automaticamente.