Usando o Nota Fiscal Asaas no dia a dia

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.2 (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.2

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.2

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.2

Filtra as faturas cujo vencimento cai dentro do período informado.

Pagamento (de/até) v7.2

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.

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.

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

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".

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.

Agrupa as notas ativas por cliente e data de emissão, destacando quem recebeu mais de uma nota no mesmo dia — o cenário típico de uma reemissão indevida. Cada grupo lista as notas com um checkbox; a mais antiga do grupo já vem desmarcada (presumível válida) e as demais marcadas. Revise, informe o motivo e cancele as selecionadas direto dali.

Informe o número da NF inicial, o final e uma observação (motivo do cancelamento — obrigatório). O módulo busca na Asaas todas as notas autorizadas nessa faixa de número, mostra uma prévia com o valor total e, após confirmação, solicita o cancelamento de cada uma na Asaas e na prefeitura.

Localiza, direto na Asaas, notas fiscais com erro de processamento/recusa da prefeitura (status ERROR) que nunca chegaram a ter número — nem no campo devolvido pela Asaas, nem no histórico local (verificação reforçada, já que a Asaas pode não devolver mais o número de uma nota que foi autorizada e depois entrou em erro). Notas agendadas ou já canceladas não entram na busca. A busca só roda depois que você clica em Filtrar (não carrega sozinha ao abrir a tela). Filtre por fatura, cliente ou período e confirme para cancelar na Asaas (a nota nunca chegou à prefeitura, então o cancelamento acontece só do lado da Asaas) e limpar o registro local.

Nem todo município do Brasil tem cancelamento automático de NFS-e integrado com a Asaas. Nesses casos, ao tentar cancelar, a nota volta com uma mensagem do tipo "[cidade] ainda não tem essa funcionalidade disponível" — não é uma falha do módulo, é uma limitação daquela prefeitura específica, e tentar de novo do mesmo jeito não resolve.

Quando isso acontece, ao final do processamento em lote o módulo pergunta se você quer cancelar somente na Asaas — só para as notas que caíram nessa situação. Esse modo desfaz o vínculo na Asaas (por exemplo, deixando de bloquear a emissão de uma nova nota para a mesma fatura) mas não notifica nem cancela o documento junto à prefeitura.

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.

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.

Os 5 campos da Reforma Tributária (Código NBS, Código de Tributação Nacional, Código de Situação Tributária, Classificação Tributária e Código Indicador de Operação) são preenchidos nessa tela e enviados à Asaas dentro do bloco ibsCbs ao agendar cada NFS-e. Não são obrigatórios, mas se preencher um, os cinco precisam estar preenchidos.

Cada campo tem um botão Listar... que abre, em nova aba, a lista oficial de códigos consultada ao vivo na Asaas para aquele campo. A tela de listagem traz:

Filtros

Por código e/ou descrição (e também por situação tributária vinculada, na lista de Classificação Tributária) — os mesmos filtros aceitos pela API da Asaas, então a busca vale para a base inteira, não só para a página carregada.

Itens por página

10, 25, 50 ou 100 por página.

Paginação

Primeira, anterior, próxima e última página, com indicador de página atual e total de resultados.

Use essas listas para conferir o código certo antes de preencher o campo correspondente — evita erro de digitação e código inválido na hora de emitir a NFS-e.

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.

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

1. Filtrar por mensagem, nível, cliente, fatura, contexto e período.
2. Abrir o registro para ver os dados adicionais gravados em JSON.
3. 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.