Configure tax information

Suggest Edits

Before issuing an Invoice, it's necessary to define your company's tax settings, such as RPS number, city hall username and password (or certificate), among others.

To start, you need to call the List Municipal Settings endpoint. This endpoint will return the necessary data that your city hall requires, according to the city registered in your CNPJ account.

GET /v3/fiscalInfo/municipalOptions
Check out the complete reference for this endpoint.

As a return, you will have access to fields:

  • authenticationType (enum) - Type of authentication required at the city hall
    • CERTIFICATE - Digital certificate
    • TOKEN - Token
    • USER_AND_PASSWORD - User and password
  • supportsCancellation (boolean) - Whether or not it supports the automatic cancellation of invoices at your city hall
  • usesSpecialTaxRegimes (boolean) - Whether or not it's necessary to inform the special tax regime. If used, inform it in the specialTaxRegime field of Create or update tax information according to the options returned in the list specialTaxRegimesList.
  • usesServiceListItem (boolean) - Whether or not it's necessary to inform the service list item
  • specialTaxRegimesList (array) - Options of special tax regimes
    • label - Name of the special tax regime
    • value - Identifier of the special tax regime
  • municipalInscriptionHelp (string) - Explanation about the format of the municipal inscription
  • specialTaxRegimeHelp (string) - Explanation about the special tax regime
  • serviceListItemHelp (string) - Explanation about the format of the service list item
  • digitalCertificatedHelp (string) - Explanation about the digital certificate
  • accessTokenHelp (string) - Explanation about the token
  • municipalServiceCodeHelp (string) - Explanation about the format of the municipal service code

An example of a return:

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

In the example above, we know that authentication is by username and password and that the city hall does not use a special tax regime. Having this information at hand, we can send the necessary data in the endpoint to create or update tax information.

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

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

If everything is correct with your settings, you are ready to issue invoices.

Updated 15 days ago