Issuing service invoices

After configuring the account tax information, identify the service provided and schedule the Service Invoice (NFS-e).

The invoice can be linked to a charge or an installment, or issued on its own for a customer.

Before you start

Confirm that the account tax information has already been configured according to the municipality requirements.

Configure the tax information.

How it works

How you fill in the service depends on whether the municipal list is available.

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["List municipal services"] --> B{"Does the city hall return services?"}

    B --> Sim(("Yes"))
    B --> Nao(("No"))

    Sim --> C["Use municipalServiceId"]
    Nao --> D["Use municipalServiceCode"]

    C --> E["Schedule the NFS-e"]
    D --> E

    E --> F["Receive Webhook"]
    F --> G["Update the result"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,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

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px

    class A inicio
    class B decisao
    class C,D,E,F validacao
    class G sucesso

    class Sim respostaSim
    class Nao respostaNao

    linkStyle default stroke:#94A3B8,stroke-width:2px
    linkStyle 1 stroke:#22C55E,stroke-width:4px
    linkStyle 2 stroke:#EF4444,stroke-width:4px

1. Identify the municipal service

Query the services available for the municipality:

GET /v3/fiscalInfo/services

See the List municipal services endpoint.

The query accepts:

• offset, to set the start of the listing;
• limit, with a maximum of 100 records per request;
• description, to find a service by name or description.

When you find the service, use the returned id as municipalServiceId.

When there is a list of services

If the listing returns, for example, the service with code 1.01 and ID 203561, send:

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

Do not repeat the code in municipalServiceCode when using municipalServiceId.

When there is no list of services

Get the service code from the city hall or your accountant and send it manually:

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

When scheduling, provide municipalServiceId or municipalServiceCode, depending on what the city hall provides.

2. Schedule the invoice

Send:

POST /v3/invoices

See the Schedule invoice endpoint.

Example:

{
  "payment": "pay_637959110194",
  "serviceDescription": "Invoice for Bill 101940. \nDescription of Services: SYSTEMS ANALYSIS AND DEVELOPMENT",
  "observations": "Monthly, for the work done in June.",
  "value": 300,
  "deductions": 0,
  "effectiveDate": "2023-07-03",
  "municipalServiceId": "21234",
  "municipalServiceName": "Systems analysis and development",
  "taxes": {
    "retainIss": false,
    "iss": 3,
    "cofins": 3,
    "csll": 1,
    "inss": 0,
    "ir": 1.5,
    "pis": 0.65
  }
}

Fill in the taxes object according to the account tax regime and tax status.

For Regime Normal accounts that issue through the National Portal, also see Retention and tax status configurations for PIS/COFINS.

Define the invoice origin

Provide at least one of these fields:

The scheduled issue date is defined by effectiveDate.

Expected result

After scheduling, the API creates the invoice and starts the issuing flow according to effectiveDate.

Do not treat scheduling as confirmation of issuance. Wait for the processing update.

3. Track issuance via Webhooks

Use Webhooks to track invoice status changes instead of repeatedly querying the resource through the API.

For the issuing flow, mainly handle:

• INVOICE_CREATED;
• INVOICE_SYNCHRONIZED;
• INVOICE_AUTHORIZED;
• INVOICE_ERROR.

INVOICE_AUTHORIZED confirms the NFS-e was issued. In case of failure, INVOICE_ERROR lets you handle the cause before a new attempt.

Issue a scheduled invoice early

If the invoice has a future effectiveDate and needs to be issued before that date, use:

POST /v3/invoices/{id}/authorize

See the Issue an invoice endpoint.

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

Issuing through the National Portal

Accounts that use the National Portal do not receive the list of municipal services through the API.

When querying the services, the current flow may return:

{
  "errors": [
    {
      "code": "error",
      "description": "The municipal service code is not enabled for this account."
    }
  ]
}

In this scenario:

1. get the service code from the National Portal or your accountant;
2. provide this value in municipalServiceCode;
3. do not use municipalServiceId.

Example:

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

Invoices for subscriptions

To automatically issue NFS-e for the charges generated by a subscription, configure the issuing rule on the subscription itself.

Configure automatic invoice issuing for subscriptions.

Practical examples

• List municipal services before issuing an Invoice
• Schedule an Invoice linked to a charge
• Run the complete flow for issuing an Invoice via API

Next steps

• Track invoice events
• Configure automatic issuing for subscriptions
• Configure PIS/COFINS retention and tax status
• Adapt your integration to the Tax Reform