Creates a Service Invoice (NFS-e) and schedules its issuing for the date provided in effectiveDate.

The invoice can be linked to a payment or an installment, or issued on a standalone basis for a customer. Provide at least one of payment, installment or customer to define its origin.

The service must be provided through municipalServiceId or municipalServiceCode, depending on what the city hall supports. For accounts that issue through the National Portal, use municipalServiceCode, because the list of municipal services is not available in this scenario.

If an invoice already scheduled with a future effectiveDate needs to be issued early, use Issue an invoice.

Real estate operations and the Tax Reform

For rental, assignment, leasing, management, or brokerage services involving real estate, the Tax Reform requires additional fields to be filled in within taxes: operationTypeCode, referencedInvoiceAccessKeyList and realEstateInfo. These fields only apply to services with a real estate-related National Tax Code (federalServiceTaxCode); do not provide them for other services.

Operation type (taxes.operationTypeCode)

Can only be provided when the service used on the invoice is configured with a federalServiceTaxCode that starts with 25.05, 15.09, 17.12 or 10.05. For any other code, the field is not accepted.

If the service requires the field and it is not provided, the API returns "Código do tipo de operação deve ser informado para este código de tributação nacional.". If it is provided for a service that does not allow it, the API returns "Código do tipo de operação não pode ser informado para este código de tributação nacional.". Outside the range of 1 to 5, the API returns "Código do tipo de operação inválido. Deve ser um valor entre 1 e 5.". In the response, the field only appears when a value has been provided for the invoice.

Referenced NFS-e key (taxes.referencedInvoiceAccessKeyList)

Required when operationTypeCode is 2 or 3, so that the city hall or the National Portal can link the invoice to the already issued NFS-e related to the same operation. Each key must contain exactly 50 numeric characters, with a minimum of 1 and a maximum of 99 keys per invoice.

If required and missing, the API returns "A chave da NFS-e referenciada deve ser informada para o tipo de operação selecionado.". An invalid format in any item returns "Chave da NFS-e referenciada inválida. Deve conter 50 caracteres numéricos.". Above 99 keys, the API returns "Quantidade de chaves de NFS-e referenciadas excede o limite permitido.".

Real estate data (taxes.realEstateInfo)

Depends on two other fields of the service used on the invoice: the National Tax Code (federalServiceTaxCode) and the operation indicator (taxes.operationIndicatorCode).

If required and missing, the API returns "As informações do imóvel devem ser informadas para o indicador de operação informado.". If not allowed and provided, the API returns "As informações do imóvel não podem ser informadas para este serviço ou indicador de operação.". In the response, the object only appears when there is real estate data associated with the invoice.

Related content

Guides

• Issuing service invoices
• PIS/COFINS withholding and tax situation settings
• Adapting your integration to the Tax Reform

Webhooks

• Events for invoices