Endpoint used to create an invoice and schedule its issuance for the date informed in effectiveDate.

This is the main invoice creation request in the API.

The invoice can be created in three contexts:

• linked to a payment, using payment
• linked to an installment, using installment
• issued as a standalone invoice for a customer, using customer

Invoice guide

Check the invoice guide for more information

This request contains the payment, installment, and customer attributes.

Although they are not individually marked as required, at least one of them must be provided to define the origin of the invoice:

• payment - Invoice linked to a payment
• installment - Invoice linked to an installment
• customer - Standalone invoice linked only to the customer

🚧

Important

At least one of the payment, installment, or customer attributes must be sent in the request.

• Not sending these fields prevents the identification of the invoice origin.
• Each scenario defines how the invoice is linked within the platform.

Main request parameters

• payment - Identifier of the payment linked to the invoice.
• installment - Identifier of the installment linked to the invoice.
• customer - Identifier of the customer when the invoice is standalone.
• serviceDescription - Description of the invoice services.
• observations - Additional invoice observations.
• externalReference - Invoice identifier in your system.
• value - Total invoice amount.
• deductions - Amount of deductions applied to the invoice. This field does not change the total invoice amount, but changes the ISS calculation basis.
• effectiveDate - Date on which the invoice should be issued.
• municipalServiceId - Identifier of the municipal service returned by the services listing.
• municipalServiceCode - Municipal service code informed manually.
• municipalServiceName - Name of the municipal service. If not informed, the system may use municipalServiceCode as identification.
• updatePayment - Indicates whether the linked payment amount should be updated with the deducted invoice taxes.
• taxes - Object containing the invoice taxes.

Important rule about the municipal service

It is mandatory to send one or the other:

• municipalServiceId
• municipalServiceCode

🚧

Important

The way the municipal service is filled depends on the municipality availability.

• When a municipal services list is available, it is recommended to use municipalServiceId.
• When no services list is available, the information must be filled manually using municipalServiceCode.

When the municipality provides a services list, the recommended approach is to use municipalServiceId.

Example:

• the listing returns the service with id = 203561
• this service represents the code 1.01 - Systems analysis and development

In this scenario, the recommended filling is:

{
  "municipalServiceId": "203561",
  "municipalServiceCode": null,
  "municipalServiceName": "1.01 - Systems analysis and development"
}

When the municipality does not provide a services list, the filling must be manual:

{
  "municipalServiceId": null,
  "municipalServiceCode": "1.01",
  "municipalServiceName": "Systems analysis and development"
}

National Portal

When the account uses the National Portal, the API no longer returns the municipal services list.

🚧

Important

In this scenario, the service must be informed manually through municipalServiceCode.

• The municipalServiceId field will no longer be available for use.
• It is recommended to validate the service code beforehand with the municipality or accounting team.

Possible invoice statuses

• SCHEDULED - Invoice scheduled.
• SYNCHRONIZED - Invoice sent to the municipality.
• AUTHORIZED - Invoice successfully issued.
• PROCESSING_CANCELLATION - Cancellation in progress.
• CANCELED - Invoice canceled.
• CANCELLATION_DENIED - Cancellation denied.
• ERROR - Issuance error.

taxes object

The taxes object contains the taxes applied to the invoice.

📘

Retention and tax situations

The taxes.pisCofinsRetentionType and taxes.pisCofinsTaxStatus attributes are mandatory only for companies not enrolled in the Simples Nacional regime that issue invoices through the National Portal.

• For more details about the accepted retention types and tax situations, access the documentation for Retention and tax situation settings.