Invoices FAQ

Find answers to common questions about configuring, issuing and tracking Service Invoices (NFS-e) through the API.

What do I need to configure before issuing an NFS-e?

First, configure the account's tax information according to the municipality's requirements.

Before saving the configuration, check:

GET /v3/fiscalInfo/municipalOptions

The response returns the data required by the city hall, such as the authentication method and municipality-specific rules.

Configure the tax information.

How do I check whether the account already has a tax configuration?

Call:

GET /v3/fiscalInfo

The response returns the account's current tax configuration.

If no configuration has been registered yet, the API returns HTTP 404.

See the Retrieve tax information endpoint.

Does the NFS-e need to be linked to a charge?

No.

When scheduling an invoice, provide at least one of the following origins:

See the Schedule invoice endpoint.

Should I use municipalServiceId or municipalServiceCode?

It depends on the municipality.

When the city hall makes the list of services available through the API, call:

GET /v3/fiscalInfo/services

Use the returned id in municipalServiceId.

If the city hall does not provide the list, obtain the service code and send it in municipalServiceCode.

See the List municipal services endpoint.

How do I provide the service when the account uses the National Portal?

The National Portal does not provide the list of municipal services through the GET /v3/fiscalInfo/services endpoint.

In this scenario:

• obtain the code that corresponds to the service;
• send it in municipalServiceCode;
• do not use municipalServiceId.

See how to issue service invoices.

Can a scheduled invoice already be considered issued?

No.

Scheduling creates the invoice and starts the processing flow according to effectiveDate. Consider the NFS-e issued when it reaches the AUTHORIZED status.

Use Webhooks to track this change.

The event:

INVOICE_AUTHORIZED

confirms the authorization of the invoice.

In case of failure, handle:

INVOICE_ERROR

See the invoice events.

Do I need to query the API continuously to know whether the invoice was issued?

No.

Use Webhooks as the main mechanism to track issuance, cancellation and failures.

Use GET requests for one-off retrieval, reconciliation, or when you need to confirm the current state of an invoice.

See the invoice events.

Can I change an invoice after scheduling it?

Yes, as long as it has not been issued yet.

The update endpoint accepts invoices with the following statuses:

• SCHEDULED;
• ERROR.

Use:

PUT /v3/invoices/{id}

After the invoice is definitively issued, its data can no longer be changed through this endpoint.

See the Update invoice endpoint.

Can I bring forward the issuance of a scheduled invoice?

Yes.

If the invoice already exists and has a future effectiveDate, use:

POST /v3/invoices/{id}/authorize

This endpoint does not create a new invoice. It brings forward the processing of an invoice that is already scheduled.

See the Issue an invoice endpoint.

How does NFS-e cancellation work?

Request the cancellation through:

POST /v3/invoices/{id}/cancel

The result depends on the city hall's rules and on the current state of the invoice. Not all municipalities allow automatic cancellation through the integration.

After the request, mainly track:

• INVOICE_PROCESSING_CANCELLATION;
• INVOICE_CANCELED;
• INVOICE_CANCELLATION_DENIED.

Prefer Webhooks to track the result.

See the Cancel an invoice endpoint.

Can I issue invoices automatically for subscriptions?

Yes.

Automatic issuance is configured per subscription and lets you define when the invoices for recurring charges should be issued.

Configure automatic invoice issuance for subscriptions.

When do I need to worry about PIS/COFINS?

The rules depend on the tax regime and the issuance model used by the account.

For scenarios affected by NT-007, read the specific guide before defining pisCofinsTaxStatus, operationPis, operationCofins and withholdings.

Configure PIS/COFINS withholding and tax status.

What changes with the Tax Reform?

The Tax Reform adds new tax information to the taxes object when issuing an NFS-e, including IBS/CBS data and, for real estate services, the operationTypeCode, referencedInvoiceAccessKeyList and realEstateInfo fields.

When your operation is covered, prepare your integration to send these fields with the applicable classifications.

Adapt your integration to the Tax Reform.

Where can I find complete request examples?

Use the Recipes to run examples of tax configuration, service identification and NFS-e issuance.

See the Recipes.

For complete contracts of fields, responses and parameters, use the API Reference.

Next steps

• Configure the tax information
• Issue service invoices
• Track invoice events
• Configure automatic issuance for subscriptions
• See the Recipes