Instalação e configuração do Nota Fiscal Asaas
Passo a passo para colocar o addon no ar: enviar os arquivos, ligar o WHMCS ao Asaas e deixar as regras fiscais prontas para emitir a primeira NFS-e.
Visão geral
O que este guia cobre — e o que fica para o outro.
Este guia cobre apenas a instalação e a configuração do módulo: enviar os arquivos, ativar o addon, conectar com o Asaas e preparar os cadastros fiscais. Depois de concluir os passos abaixo, use o Guia de Utilização para o dia a dia — emitir notas, acompanhar faturas e consultar logs.
Requisitos
Confirme estes itens antes de começar.
Passo a passo
Siga na ordem — cada etapa depende da anterior.
Enviar os arquivos do módulo
Envie a pasta do addon para o diretório de módulos da sua instalação WHMCS.
modules/addons/asaasnfmpay/ → [WHMCS]/modules/addons/
Ativar o addon no WHMCS
No admin do WHMCS, acesse Configurações › Módulos Addons, localize Nota Fiscal Asaas MP e clique em Ativar.
Licença e API Key do Asaas
Abra as configurações do módulo e preencha as credenciais principais:
- Chave de licença
- Chave ativa do módulo, fornecida na compra.
- API Key do Asaas
- Usada nas chamadas para
api.asaas.com. Gere no painel do Asaas.
Configurar o webhook do Asaas
No painel do Asaas, cadastre a URL de retorno do módulo:
https://SEU-DOMINIO/modules/addons/asaasnfmpay/callback.php
Use no Asaas o mesmo valor definido em Token de autenticação nas configurações do módulo. O callback registra os eventos recebidos, atualiza o status da nota e salva os links de PDF/XML assim que ficam disponíveis.
Definir as regras fiscais
- Taxa do ISS (%)
- Alíquota usada na emissão da NFS-e.
- Taxa de Emissão da NFSe
- Campo opcional, apenas para registrar o custo de emissão.
- Descrição do Serviço na Nota
- Define se a nota usa o número da fatura, o nome dos serviços ou ambos.
- Pasta personalizada do admin
- Preencha só se o seu WHMCS não usa a pasta
/adminpadrão.
Ligar os campos personalizados do cliente
O módulo usa campos personalizados do WHMCS para saber o documento fiscal e a preferência de emissão de cada cliente:
- Modo CPF/CNPJ
- Campo único ou campos separados para CPF e CNPJ.
- Campo CPF/CNPJ, CPF, CNPJ
- Qual campo personalizado guarda o documento do cliente.
- Emitir Nota Fiscal
0Não emitir ·1Emitir após o pagamento ·2Emitir antes do pagamento.- Inscrição Municipal / Estadual
- Quando aplicável ao regime do cliente.
É esse mesmo campo Emitir Nota Fiscal que o módulo lê para decidir, fatura a fatura, se emite automaticamente e quando — veja o fluxo completo no Guia de Utilização.
Não é mais necessário pré-cadastrar o cliente no Asaas antes de emitir a primeira nota: se o CPF/CNPJ informado aqui não corresponder a um cliente já existente no Asaas, o módulo cadastra automaticamente com os dados do WHMCS no momento de agendar a NFS-e.
Cadastrar o Serviço Municipal
Em Complementos › Nota Fiscal Asaas MP › Gerenciar Serviço Municipal, cadastre o código NBS e o nome do serviço exatamente como constam no Asaas.
Enquanto nenhum Serviço Municipal estiver cadastrado, a própria tela de configuração do módulo exibe um aviso com atalho direto para este cadastro — e o formulário agora tem um link de ajuda para quem não sabe o que é o código NBS.
Associar produtos e serviços
Em Associar Produtos/Serviços, vincule cada produto do WHMCS a um serviço municipal cadastrado. Marque um item como principal (default) — ele será usado em cobranças sem vínculo direto com produto ou serviço.
Configurar o envio de e-mail
Para enviar o PDF da NFS-e por e-mail, defina os dados SMTP:
Depois, crie ou revise no WHMCS o template de e-mail Nota Fiscal Eletrônica de Serviço. O módulo adiciona campos de merge para número da nota, link do PDF e link do XML.
Ativar a automação
- Sincronização de notas fiscais
- Controla a rotina de envio/sincronização executada pelo cron.
- Formas de Pagamentos
- IDs dos gateways autorizados a emitir NF, separados por vírgula.
- Emissão Automática da NF
- Liga ou desliga as rotinas automáticas.
- Dias antes/depois do pagamento
- Agenda a emissão conforme a regra fiscal desejada.
Sem o cron do WHMCS em execução, nem a emissão automática nem a sincronização acontecem — confirme isso antes de liberar o módulo para uso.
Permissões e área do cliente
Revise a permissão de acesso do grupo administrativo que poderá usar o addon. Se quiser que os clientes vejam as próprias notas, ative Exibir Nota Fiscal para o Cliente — isso libera um menu de Nota Fiscal na área do cliente, com os links de PDF e XML.
Atualizando de uma versão anterior
Faça isso antes de sobrescrever os arquivos.
- Faça backup dos arquivos do módulo e do banco de dados do WHMCS — especialmente da tabela
mod_nfasaasmpay. - Nas configurações atuais do addon, copie a chave de licença, a API Key do Asaas, o token de autenticação e demais dados relevantes.
- Envie os novos arquivos do módulo, substituindo os existentes.
- Acesse o admin do WHMCS, revise todas as configurações e clique em Salvar — isso garante a criação automática de eventuais tabelas novas no banco.
- Após a primeira execução do cron, consulte os logs para confirmar que tudo está funcionando.
Checklist final
Antes de liberar o módulo para uso.
- Licença, API Key e token de autenticação preenchidos e salvos
- Webhook cadastrado no Asaas apontando para
callback.php - Pelo menos um Serviço Municipal cadastrado e um produto marcado como principal
- Campos personalizados de documento e de preferência de emissão configurados
- SMTP configurado, se for enviar o PDF por e-mail
- Cron do WHMCS confirmadamente em execução