Introdução - Notas Fiscais
Emita notas fiscais de serviço pela API
O Asaas permite que empresas emitam Notas Fiscais de Serviço (NFS-e) pela API.
A nota pode ser vinculada a uma cobrança, a um parcelamento ou emitida de forma avulsa para um cliente.
Antes de emitir uma nota fiscal é necessário preencher as informações fiscais na sua conta. Confira aqui como realizar essa configuração.
Como funciona
A emissão via API segue esta sequência:
%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
A["Listar configurações municipais"] --> B["Configurar informações fiscais"]
B --> C["Identificar o serviço municipal"]
C --> D["Agendar a nota fiscal"]
D --> E["Receber Webhook"]
E --> F["Atualizar o resultado da emissão"]
classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px
classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px
class A inicio
class B,C,D,E validacao
class F sucesso
linkStyle default stroke:#94A3B8,stroke-width:2px
1. Consulte as exigências do município
Antes de configurar os dados fiscais, consulte quais informações a prefeitura exige:
GET /v3/fiscalInfo/municipalOptionsAs exigências variam conforme o município da conta e podem incluir forma de autenticação, inscrição municipal, regime especial de tributação e outros dados.
Listar configurações municipais
2. Configure as informações fiscais
Utilize o resultado da etapa anterior para cadastrar ou atualizar os dados fiscais da conta:
POST /v3/fiscalInfoEnvie somente os dados aplicáveis às exigências retornadas para o município.
Criar e atualizar informações fiscais
Para entender o preenchimento dessa etapa, consulte Configurar informações fiscais.
3. Identifique o serviço municipal
Quando a prefeitura disponibilizar uma lista de serviços, consulte:
GET /v3/fiscalInfo/servicesUtilize o id retornado como municipalServiceId ao agendar a nota.
Quando a prefeitura não disponibilizar essa listagem, informe o serviço manualmente por municipalServiceCode.
Contas que emitem pelo Portal Nacional também devem informar o código do serviço manualmente, pois a listagem de serviços municipais não fica disponível nesse cenário.
4. Agende a nota fiscal
Depois de configurar os dados fiscais e identificar o serviço, crie a nota:
POST /v3/invoicesDefina a origem da NFS-e com pelo menos um destes campos:
| Campo | Utilize quando |
|---|---|
payment | A nota estiver vinculada a uma cobrança |
installment | A nota estiver vinculada a um parcelamento |
customer | A nota for avulsa |
A data de emissão é definida em effectiveDate.
Consulte o endpoint Agendar nota fiscal.
Para exemplos de payload e regras de preenchimento do serviço, consulte Emitindo notas fiscais de serviço.
5. Acompanhe a emissão por Webhooks
O agendamento não significa que a NFS-e já foi autorizada pela prefeitura.
Acompanhe o resultado por Webhooks em vez de consultar repetidamente a nota pela API.
Para concluir o fluxo, trate principalmente:
| Evento | Ação |
|---|---|
INVOICE_AUTHORIZED | Confirme a emissão e atualize a nota no seu sistema |
INVOICE_ERROR | Registre a falha e trate a causa antes de uma nova tentativa |
Consulte todos os eventos para notas fiscais.
Resultado esperado
A integração está concluída quando seu sistema recebe o resultado do processamento e atualiza o estado da NFS-e.
No fluxo de sucesso, INVOICE_AUTHORIZED confirma que a nota foi emitida.
Teste no Sandbox
As operações de configuração e emissão de notas fiscais estão disponíveis no Sandbox.
A emissão também depende das regras, credenciais e integrações disponíveis para o município utilizado no teste.
Consulte o que pode ser testado no Sandbox.
Exemplo completo
Para executar a jornada completa com exemplos de requisição, consulte o Recipe:
Fluxo completo para emissão de Nota Fiscal via API.
Próximos passos
Updated 5 days ago