Configure tax information

Before issuing a Service Invoice (NFS-e), configure the account's tax information according to the municipality's requirements.

The integration must first check which information the city hall requires and only then send the tax configuration.

How it works

%%{init: {"flowchart": {"nodeSpacing": 18,"rankSpacing": 24,"diagramPadding": 4,"padding": 7}}}%%
flowchart TD
    A["Check municipal requirements"] --> B["Interpret the required fields"]
    B --> C["Configure tax information"]
    C --> D["Retrieve the configuration"]
    D --> E["Validate the account for issuance"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,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

    class A inicio
    class B,C,D validacao
    class E sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

1. Check the municipality's requirements

Make the query:

GET /v3/fiscalInfo/municipalOptions

The response takes into account the municipality registered for the account's CNPJ and indicates which data must be used in the tax configuration.

List municipal configurations

Interpret the required fields

The main fields that influence the configuration are:

Field	How to use it
`authenticationType`	Identifies how the city hall authenticates the issuance
`usesSpecialTaxRegimes`	When `true`, provide `specialTaxRegime`
`specialTaxRegimesList`	Use the `value` corresponding to the applicable regime
`usesServiceListItem`	When `true`, provide `serviceListItem`
`supportsCancellation`	Indicates whether the municipality allows automatic cancellation through the integration

authenticationType can return:

Value	Expected configuration
`USER_AND_PASSWORD`	`username` and `password`
`TOKEN`	`accessToken`
`CERTIFICATE`	`certificateFile` and `certificatePassword`

Do not decide in advance which authentication method will be used. Use the value returned for the account's municipality.

2. Use the city hall's guidance

The query may also return fields with the Help suffix, such as:

municipalInscriptionHelp;
specialTaxRegimeHelp;
serviceListItemHelp;
digitalCertificateHelp;
accessTokenHelp;
municipalServiceCodeHelp.

These fields serve only as filling guidance and must not be sent when configuring the tax information.

🚧
Attention
The Help fields may return null when the city hall has no additional guidance for filling in that information.

Response example:

{
  "authenticationType": "USER_AND_PASSWORD",
  "supportsCancellation": true,
  "usesSpecialTaxRegimes": false,
  "usesServiceListItem": false,
  "specialTaxRegimesList": null,
  "municipalInscriptionHelp": "The company's municipal registration must contain 1 to 8 digits (numbers only).\r\n\r\nValid example: 11356",
  "specialTaxRegimeHelp": null,
  "serviceListItemHelp": null,
  "digitalCertificateHelp": null,
  "accessTokenHelp": null,
  "municipalServiceCodeHelp": "Enter here the municipal service code that identifies the service provided in the invoice. \r\n\r\nIt usually has 4 to 5 digits with formatting.\r\nValid example: 1.01"
}

In this example, the city hall uses username and password authentication and does not require a special tax regime.

3. Configure the tax information

After interpreting the municipal requirements, send:

POST /v3/fiscalInfo

Provide the company's tax information and only the credentials corresponding to the returned authentication method.

Example for USER_AND_PASSWORD:

{
  "email": "[email protected]",
  "municipalInscription": "21779501",
  "simplesNacional": true,
  "cnae": "6209100",
  "rpsSerie": "1",
  "rpsNumber": 1,
  "username": "[email protected]",
  "password": "secret@123"
}

Other fields may be required depending on the municipality, such as specialTaxRegime, serviceListItem, loteNumber, nbsCode or information specific to the National Portal.

Define the default municipality of service provision (optional)

Provide serviceProvisionCityDefaultType to define which city will be used by default in the issued NFS-e: MY_ACCOUNT_CITY, CUSTOMER_CITY or CUSTOMER_CITY_WHEN_ISS_IS_RETAINED.

Example:

{
  "serviceProvisionCityDefaultType": "MY_ACCOUNT_CITY"
}

See the meaning of each value and the validation rules in: Create and update tax information.

4. Validate the configuration

After saving, query:

GET /v3/fiscalInfo

Retrieve tax information

Confirm that the required data was registered correctly before starting issuance.

If no tax configuration exists, this query returns HTTP 404.

Expected result

The tax configuration must be registered and compatible with the requirements returned for the municipality.

With this step completed, proceed to identifying the municipal service and scheduling the NFS-e.

Complete example

To run the configuration with request examples, see:

Configure tax information for Invoice issuance

Next steps

Updated 11 days ago

Did this page help you?