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
A partir daqui, o restante da configuração não fica mais na tela nativa do WHMCS usada no passo anterior — acesse Complementos › Nota Fiscal Asaas MP › Configuração Sistema, bloco Emissão e valores:
- 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.
- Informação personalizada na nota fiscal
- Texto livre, adicionado em todas as NF emitidas.
Pasta personalizada do admin e Token de autenticação também estão nessa mesma tela, no bloco Credenciais e Asaas — junto com Chave de licença e API Key, que continuam sincronizadas com a tela nativa do passo 3.
Ligar os campos personalizados do cliente
Ainda em Configuração Sistema, nos blocos Emissão automática e Documento do cliente (CPF/CNPJ). 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, acesse Complementos › Nota Fiscal Asaas MP › SMTP e preencha o formulário — os dados ficam gravados no banco, não em arquivo:
Antes de sair da tela, use o botão Testar Configuração: ele envia um e-mail de teste real para o endereço informado, usando os dados do formulário mesmo que ainda não tenham sido salvos — confirme host, porta, usuário e senha ali mesmo, sem depender da próxima emissão automática.
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
Também em Configuração Sistema, bloco Emissão automática:
- Sincronização de notas fiscais
- Controla a rotina de envio/sincronização executada pelo cron.
- Formas de Pagamentos permitidas
- Um checkbox por gateway de pagamento cadastrado no WHMCS — marque os que devem gerar NF. Pelo menos um precisa ficar marcado.
- Permitir emissão automática quando o cron rodar
- Liga ou desliga as rotinas automáticas.
- Dias antes/depois do pagamento
- Agenda a emissão conforme a regra fiscal desejada.
- Notificações do Asaas ao cliente
- Permite ou não que a Asaas notifique o cliente diretamente sobre a cobrança/nota.
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.
IBS/CBS — Reforma Tributária Novidade v7.2
Passo opcional. Em Complementos › Nota Fiscal Asaas MP › IBS/CBS, preencha os 5 campos exigidos pela Reforma Tributária, caso sua empresa esteja obrigada a informá-los — consulte seu contador para confirmar:
- Código NBS
- Código da Nomenclatura Brasileira de Serviços aplicável à operação.
- Código de Tributação Nacional
- Código de Tributação Nacional do serviço.
- Código de Situação Tributária do IBS e da CBS
- Código de Situação Tributária (CST) do IBS e da CBS.
- Classificação Tributária do IBS e da CBS
- Código de Classificação Tributária do IBS e da CBS.
- Código Indicador de Operação
- Código indicador da natureza da operação.
Os campos não são obrigatórios, mas se preencher um, precisa preencher todos os cinco. Quando preenchidos, os valores são enviados à Asaas dentro do bloco ibsCbs ao agendar cada NFS-e; quando vazios, a nota é emitida normalmente, sem esse bloco.
Cada campo tem um botão Listar... que abre, em nova aba, a lista oficial de códigos válidos consultada ao vivo na Asaas — com filtro por código/descrição, seletor de itens por página (10/25/50/100) e paginação completa. Use para encontrar o código certo antes de preencher o campo.
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.
Esta versão corrige um bug que podia gerar notas fiscais duplicadas para a mesma fatura. Se a instalação já rodava antes da 7.2, acesse Notas Duplicadas por Cliente/Dia (no painel do addon) para identificar clientes com mais de uma nota emitida no mesmo dia, e use o Cancelamento em Lote (por Nº) ou a Cancelar Notas sem Emissão na Prefeitura para corrigir o que for necessário. Veja o Guia de Utilização para o passo a passo de cada ferramenta.
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 - Regras fiscais e Formas de Pagamento revisadas em Configuração Sistema
- 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
- IBS/CBS preenchido, se sua empresa estiver obrigada pela Reforma Tributária
- Cron do WHMCS confirmadamente em execução