Emitir notas fiscais automaticamente para assinaturas

Configure a emissão automática de notas fiscais para uma assinatura

Configure uma assinatura para emitir automaticamente NFS-e para as cobranças geradas durante a recorrência.

A emissão seguirá o momento, serviço municipal e regras fiscais definidos na configuração.

Antes de começar

Antes de configurar:

crie a assinatura e armazene seu ID;
confirme que a conta está habilitada para emissão de notas fiscais;
defina o serviço municipal;
valide as informações fiscais e tributárias utilizadas na emissão.

Como funciona

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Criar a assinatura"] --> B["Definir o serviço municipal"]
    B --> C["Definir quando emitir"]
    C --> D["Configurar a emissão automática"]
    D --> E["Asaas gera a cobrança"]
    E --> F["Emitir a nota fiscal"]
    F --> G["Acompanhar por Webhook"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px

    class A inicio
    class B,C,D,E,F validacao
    class G sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

1. Defina o serviço municipal

Quando o município disponibilizar os serviços cadastrados, consulte:

GET /v3/fiscalInfo/services

Utilize o id retornado em municipalServiceId.

Consulte o endpoint Listar serviços municipais.

Caso o município não disponibilize a listagem, obtenha o código do serviço na prefeitura e informe municipalServiceCode.

2. Escolha quando emitir a nota fiscal

O campo effectiveDatePeriod define o momento da emissão:

Valor	Quando emitir
`ON_PAYMENT_CONFIRMATION`	Após a confirmação do pagamento
`ON_PAYMENT_DUE_DATE`	Na data de vencimento
`BEFORE_PAYMENT_DUE_DATE`	Antes do vencimento
`ON_DUE_DATE_MONTH`	No primeiro dia do mês do vencimento
`ON_NEXT_MONTH`	No primeiro dia do mês seguinte ao vencimento

Ao utilizar BEFORE_PAYMENT_DUE_DATE, informe daysBeforeDueDate com um dos valores permitidos:

5, 10, 15, 30 ou 60

Para ON_NEXT_MONTH, receivedOnly pode restringir a emissão às cobranças pagas. Quando não informado, seu valor padrão é false.

3. Crie a configuração

Utilize o ID da assinatura:

POST /v3/subscriptions/{id}/invoiceSettings

Além do período de emissão, informe os dados de serviço municipal e o bloco taxes correspondente à situação fiscal da conta.

Exemplo de regra para emitir somente após o pagamento:

{
  "effectiveDatePeriod": "ON_PAYMENT_CONFIRMATION"
}

Esse trecho representa apenas a regra de emissão. Complete a requisição com os dados fiscais exigidos para sua operação.

Consulte o endpoint Criar configuração para emissão de Notas Fiscais.

Resultado esperado

A configuração ficará vinculada à assinatura.

As novas cobranças geradas pela recorrência passarão a utilizar essas regras para emissão automática das notas fiscais.

Cobranças já existentes somente serão consideradas quando atenderem às condições da configuração.

⚠️
Atenção
Para contas de Regime Normal que emitem NFS-e pelo Portal Nacional, as regras da NT-007 estão vigentes.
Informe taxes.pisCofinsTaxStatus, taxes.operationPis e taxes.operationCofins conforme a situação tributária aplicável. Não envie taxes.pisCofinsRetentionType em novas implementações, pois esse valor é calculado pelo Asaas.
Consulte Configurações de retenção e situação tributária de PIS/COFINS.

4. Acompanhe as notas fiscais

A criação automática da nota não significa que ela foi autorizada pela prefeitura.

Utilize os Webhooks de notas fiscais para acompanhar o processamento, principalmente:

INVOICE_AUTHORIZED: nota fiscal autorizada;
INVOICE_ERROR: falha na emissão.

Consulte os Eventos para notas fiscais.

👍
Recomendado
Utilize Webhooks como mecanismo principal para acompanhar as emissões.
Evite consultas frequentes apenas para verificar mudanças de status. Utilize os endpoints de consulta para recuperação pontual, conciliação ou quando precisar confirmar o estado atual da nota.

Para listar as notas fiscais vinculadas às cobranças da assinatura, utilize:

GET /v3/subscriptions/{id}/invoices

Consulte o endpoint Listar notas fiscais das cobranças de uma assinatura.

Se precisar alterar a configuração

As regras de emissão podem ser atualizadas por:

PUT /v3/subscriptions/{id}/invoiceSettings

Notas fiscais já emitidas não são modificadas. As novas regras passam a valer para próximas cobranças ou cobranças que ainda não possuam nota fiscal criada.

Consulte o endpoint Atualizar configuração para emissão de Notas Fiscais.

Erros comuns

Se a nota fiscal não for emitida, verifique:

se a assinatura possui configuração de emissão;
se a conta está habilitada para emitir notas fiscais;
se o serviço municipal informado é válido;
se effectiveDatePeriod e seus campos dependentes estão corretos;
se os dados obrigatórios de taxes foram informados conforme o regime tributário.

Próximos passos

Updated 4 days ago

What’s Next

Did this page help you?