Issuing service invoices

To issue an invoice, you must call the "Schedule Invoice" endpoint. But first, let's check the ID of the municipal services.

List Municipal Services

GET /v3/invoices/municipalServices
Check out the complete reference for this endpoint.

The list of municipal services can be used to consult information about the service that must be sent in the generation of the invoice.

The description field contains the code and description of the service and may also include the CNAE code, presented in the following format: CNAE | Code - Description.

A maximum of 500 services are returned in each request. If the desired service is not returned, use the description filter in the request.

📘

• Depending on your city hall, the CNAE code may not be returned.
• If your city hall does not provide a list of services, no result will be returned.

If you have the municipal service ID, just send it in the request.

Schedule an Invoice

POST /v3/invoices
Check out the complete reference for this endpoint.

{
  "payment": "pay_637959110194",
  "serviceDescription": "Invoice for Invoice 101940. \nService Description: ANALYSIS AND DEVELOPMENT OF SYSTEMS",
  "observations": "Monthly for the works of June.",
  "value": 300,
  "deductions": 0,
  "effectiveDate": "2023-07-03",
  "municipalServiceId": "21234",
  "municipalServiceName": "Analysis and development of systems",
  "taxes": {
    "retainIss": false,
    "iss": 3,
    "cofins": 3,
    "csll": 1,
    "inss": 0,
    "ir": 1.5,
    "pis": 0.65
  }
}

📘

The possible statuses of an invoice are:

SCHEDULED - Scheduled

SYNCHRONIZED - Sent to city hall

AUTHORIZED - Issued

PROCESSING_CANCELLATION - Processing cancellation

CANCELED - Canceled

CANCELLATION_DENIED - Cancellation denied

ERROR - Error in issuance

The Invoice can be linked to a charge, installment, or can be generated separately.

If the Invoice originates from an existing charge, the payment attribute must be informed. The same applies to installments, in which case, the installment attribute must be informed. To generate a separate Invoice, the customer attribute must be informed.

In the call to schedule invoices, among various attributes, there are three fundamental ones for the invoice to be issued successfully: municipalServiceId, municipalServiceCode, municipalServiceName.

And it's very important that they are correctly informed. The municipalServiceId and municipalServiceCode aim to inform the service code for which the invoice is being issued. For example, the service 1.01 - Analysis and development of systems.

In our API, we work with IDs to identify, and the services work the same way. When listing the municipal services, a list with various services will be returned, as in the example below:

{  
      "id": "203561",  
      "description": "1.01 - Analysis and development of systems",  
      "issTax": 2  
}

It can be observed that the code 1.01 is represented by the ID 203561. In these cases, the municipalServiceId is this. And as you already have the code ID, there's no need to duplicate the information, risking the invoice coming out wrong by entering the code again in municipalServiceCode. So, the client should only send:

{
  ...,
  "municipalServiceId": "203561",
	"municipalServiceCode": null,
	"municipalServiceName" : "1.01 - Analysis and development of systems"
}

However, not all cities return these listings. There are few, but there are city halls that do not have a service list in the API, and with that, the client will need to check what is the code of their service and insert it manually, like this:

{
  ...,
  "municipalServiceId": null,
	"municipalServiceCode": "1.01",
	"municipalServiceName" : "Analysis and development of systems"
}

We can conclude that, whenever there is a service list, send municipalServiceId. If there isn't, send the municipalServiceCode. In these cases, always send one or the other.

Invoices in subscriptions

For subscriptions, you can configure the automatic issuance of invoices in the subscriptions section.

Issue a scheduled invoice

If the request is successful, the Invoice will be scheduled for issuance on the date informed in the effectiveDate attribute. If the informed date is the current day, within up to 15 minutes after the request, the Invoice will be issued, and you will receive the update through the webhook (if activated).

👍

The Webhook for invoices will send events when the statuses of invoices change or they are created

Check the Webhook for invoices

If you have an invoice scheduled for the future and wish to advance its issuance, you can call the endpoint "Issue an invoice".

POST /v3/invoices/{id}/authorize
Check out the complete reference for this endpoint.