Introduction - Invoices
Issue service invoices through the API
Asaas allows companies to issue Service Invoices (NFS-e) through the API.
The invoice can be linked to a charge, to an installment, or issued as a standalone invoice for a customer.
Before issuing an invoice, you must fill in the tax information in your account. See here how to perform this configuration.
How it works
Issuance via API follows this sequence:
%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
A["List municipal configurations"] --> B["Configure tax information"]
B --> C["Identify the municipal service"]
C --> D["Schedule the invoice"]
D --> E["Receive Webhook"]
E --> F["Update the issuance result"]
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. Check the municipality's requirements
Before configuring the tax information, check which information the city hall requires:
GET /v3/fiscalInfo/municipalOptionsThe requirements vary according to the account's municipality and may include authentication method, municipal registration, special tax regime and other data.
2. Configure the tax information
Use the result of the previous step to register or update the account's tax information:
POST /v3/fiscalInfoSend only the data applicable to the requirements returned for the municipality.
Create and update tax information
To understand how to fill in this step, see Configure tax information.
3. Identify the municipal service
When the city hall provides a list of services, query:
GET /v3/fiscalInfo/servicesUse the returned id as municipalServiceId when scheduling the invoice.
When the city hall does not provide this list, provide the service manually through municipalServiceCode.
Accounts that issue through the National Portal must also provide the service code manually, since the municipal services list is not available in this scenario.
4. Schedule the invoice
After configuring the tax information and identifying the service, create the invoice:
POST /v3/invoicesDefine the origin of the NFS-e with at least one of these fields:
| Field | Use when |
|---|---|
payment | The invoice is linked to a charge |
installment | The invoice is linked to an installment |
customer | The invoice is standalone |
The issue date is defined in effectiveDate.
See the Schedule invoice endpoint.
For payload examples and service filling rules, see Issuing service invoices.
5. Track issuance through Webhooks
Scheduling does not mean the NFS-e has already been authorized by the city hall.
Track the result through Webhooks instead of repeatedly querying the invoice through the API.
To complete the flow, handle mainly:
| Event | Action |
|---|---|
INVOICE_AUTHORIZED | Confirm the issuance and update the invoice in your system |
INVOICE_ERROR | Record the failure and address the cause before a new attempt |
Expected result
The integration is complete when your system receives the processing result and updates the NFS-e status.
In the success flow, INVOICE_AUTHORIZED confirms that the invoice was issued.
Test in Sandbox
Invoice configuration and issuance operations are available in Sandbox.
Issuance also depends on the rules, credentials and integrations available for the municipality used in the test.
See what can be tested in Sandbox.
Complete example
To run the complete journey with request examples, see the Recipe:
Complete flow for issuing an Invoice via API.
Next steps
Updated 14 days ago