Guia do administrador · Utilização

Usando o Nota Fiscal Asaas no dia a dia

Como emitir, acompanhar e cancelar notas fiscais depois que o módulo já está instalado e configurado. Este guia não repete a configuração — só o que muda no uso diário.

Módulo addon para WHMCS Versão 7.1

Antes de começar

Este guia assume que a licença, a API Key, o webhook e os campos personalizados já estão configurados. Se ainda não estão, veja primeiro o Guia de Instalação e Configuração — itens como "Formas de Pagamentos" e "Emitir Nota Fiscal", citados abaixo, são definidos por lá.

Onde tudo acontece

Todo o uso diário fica em Complementos › Nota Fiscal Asaas MP.

Emitir NF

Lista faturas elegíveis, com filtros, seleção múltipla e ações de emissão manual ou em lote.

Gerenciar Clientes

Ajusta a preferência de emissão de vários clientes de uma vez.

Serviço Municipal

Cadastro de serviços e associação a produtos do WHMCS.

Notas emitidas

Consulta com filtros, visualização de PDF/XML e cancelamento.

Logs do Sistema

Histórico de webhook, cron, emissão e ações administrativas.

Paginação

Todas as listas têm seletor de linhas por página e indicador de página atual.

Emitir uma nota manualmente

Manual

Pela listagem "Emitir NF".

Abra Complementos › Nota Fiscal Asaas MP › Emitir NF para ver as faturas elegíveis para emissão. A tabela traz Nº da invoice, vencimento, data de pagamento v7.1 (em branco enquanto a fatura não é paga), cliente, valor, status, condição de emissão, gateway e ações. Use os filtros para encontrar o que precisa:

Nº Invoice: Busca pelo número da fatura.
Cliente: Busca por nome, sobrenome ou razão social.
Status Invoice: Situação da fatura no WHMCS: não paga, paga, cancelada, faturada ou em cobrança.
Status Gateway v7.1: Compara a forma de pagamento da fatura com as formas cadastradas em "Formas de Pagamentos": Emite ou Não Emite. Antes chamado apenas de "Gateway".
Gateway v7.1: Lista os nomes reais das formas de pagamento usadas nas faturas (ex.: Cartão de Crédito, Pix, Boleto), sem repetir nomes — filtra pela forma escolhida.
Vencimento (de/até) v7.1: Filtra as faturas cujo vencimento cai dentro do período informado.
Pagamento (de/até) v7.1: Filtra pela data em que a fatura foi paga; faturas ainda não pagas não aparecem nesse filtro.

Cada linha tem as ações disponíveis para aquela fatura — emitir, agendar ou aguardar processamento, conforme o status atual da nota.

Agendar emissão para várias faturas de uma vez

Novidade v7.1

Cada linha da listagem tem um checkbox à esquerda do Nº da invoice, e o cabeçalho da tabela tem um checkbox para marcar todas as faturas visíveis na página de uma vez. Marque as faturas desejadas, escolha a ação em "Com os selecionados" e clique em Agendar Agora.

O módulo processa uma fatura por vez, mostra o progresso e, ao final, resume quantas foram agendadas com sucesso e quais falharam — e por quê — antes de recarregar a página com os mesmos filtros aplicados.

Cliente sem cadastro no Asaas

Ao agendar uma NF, seja individualmente ou em lote, o módulo verifica se o cliente já existe no Asaas pelo CPF/CNPJ; se não existir, ele é cadastrado automaticamente com os dados do WHMCS antes de agendar a nota — sem nenhuma ação manual extra.

Emitir direto pela fatura

Novidade v7.1

Sem sair da tela da fatura, em Faturas › Ver Fatura.

Toda fatura paga ou em aberto passa a exibir um bloco Asaas - Modules Pay com o resumo da situação de emissão:

Cliente: Emite NF Forma de Pagamento: Não Permite Emissão Status da Invoice: Aguardando Pagamento

Os três rótulos acima combinam a preferência do cliente, a forma de pagamento usada na fatura e o status atual dela — exatamente o que decide se a nota pode sair.

Quando a combinação permite emissão, um botão Agendar Emissão aparece na própria tela: confirma o agendamento e dispara a NFS-e sem precisar abrir a listagem "Emitir NF".

Se já existe nota

Quando a fatura já tem uma NF emitida, agendada ou em processo de cancelamento, o bloco troca automaticamente o botão pelo número da nota, o status e a data de emissão.

Como funciona a emissão automática

Automático

Rodando pelos hooks de cron do WHMCS, nesta ordem.

Preferência do cliente

Definida no campo "Emitir Nota Fiscal": não emitir, antes ou depois do pagamento.

Cron executa

O WHMCS dispara as rotinas do módulo no horário programado.

Módulo verifica a fatura

Confere forma de pagamento permitida e status (paga/não paga) contra a regra do cliente.

Agenda e envia

Respeita os dias configurados e envia a NFS-e para a prefeitura pelo Asaas.

Sincroniza status

Atualiza periodicamente até a nota ficar autorizada, via cron e webhook.

Nota disponível

PDF e XML liberados; e-mail com o PDF enviado ao cliente, se essa opção estiver ativa.

Cancelar ou remover um registro

Manual

Cancelar NF

Disponível só quando o status da nota é AUTHORIZED. O botão fica na listagem de notas emitidas e envia o pedido de cancelamento ao Asaas.

Remover registro local

Aparece apenas para registros já CANCELED que nunca chegaram a gerar número de NF nem de RPS — útil para limpar tentativas que não avançaram, sem afetar nenhuma nota realmente emitida.

PDF, XML e reenvio por e-mail

Manual

Em qualquer nota da listagem, use Visualizar para abrir os detalhes, com acesso ao XML, e o botão de Download para o PDF assim que ele estiver disponível.

Se Enviar PDF da NF por E-mail estiver ativo na configuração, o PDF é enviado automaticamente ao cliente usando o template Nota Fiscal Eletrônica de Serviço do WHMCS.

Gerenciar clientes em massa

Administrativo

Em Gerenciar Clientes, ajuste a preferência de emissão (não emitir / emitir antes / emitir depois do pagamento) de vários clientes ao mesmo tempo, sem precisar abrir o perfil de cada um individualmente.

O que o cliente vê

Cliente

Com Exibir Nota Fiscal para o Cliente habilitado, um menu Nota Fiscal aparece na área do cliente, listando as NFS-e emitidas com os links de PDF e XML de cada uma.

Consultar e limpar logs

Administrativo

Em Addons › Nota Fiscal Asaas MP › Logs do Sistema.

Use os logs para investigar qualquer emissão, cancelamento ou execução de cron. É possível:

Filtrar por mensagem, nível, cliente, fatura, contexto e período.
Abrir o registro para ver os dados adicionais gravados em JSON.
Apagar logs antigos por período, para manter a tabela enxuta.

Todo evento de webhook, cron, emissão, cancelamento e ação administrativa passa por aqui — é o primeiro lugar a olhar quando uma nota não sai como esperado.