Skip to main content
POST
Create your tax issuer
The CNPJ, legal name, address and phone of the organization are taken from its registration in Portão 3 and registered with the tax provider, together with the service data you send. Two configurations are created: nfseHomologationConfigurations for the TEST (homologation) environment, where documents have no fiscal value, and nfseProductionConfigurations for the LIVE (production) environment. Each has its own RPS numbering. Then upload your digital certificate, which cities generally require to issue invoices. When isSimplesNacional is false, the taxConfiguration of the live configuration is required and must carry taxClassification and operationIndicatorCode. The test configuration is not checked. An organization has one active tax issuer: creating another answers 409. One you deactivated can be replaced by a new one. If the tax provider rejects the request, the error is returned with the provider’s error code and a status of 400, 409, 422 or 502.

Path Parameters

realmId
string<uuid>
required

ID of your realm.

Format: UUID

organizationId
string<uuid>
required

ID of the organization.

Format: UUID

Body

application/json
specialTaxCode
string
required

Code of the special taxation regime of the city where your organization is registered: the id of one of the regimes GET /taxCode/{specialTaxCode} lists for that city. One or two characters.

Required string length: 1 - 2
Example:

"1"

municipalServiceCode
string
required

Municipal service code, as your city hall defines it for the service you provide. Up to 4 characters. Used on every invoice that does not send its own.

Required string length: 1 - 4
Example:

"0107"

cnae
string
required

CNAE subclass code of your main activity. It must be an existing CNAE code, otherwise the request fails with CNAE_NOT_FOUND. Used on every invoice that does not send its own.

Required string length: 1 - 10
Example:

"6201501"

issTax
number
required

ISS (municipal service tax) rate in percent: 2.5 means 2.5%. Rounded to 2 decimal places. Used on every invoice that does not send its own.

Example:

2.5

serviceDescription
string
required

Description of the service you provide. Up to 1500 characters.

Required string length: 1 - 1500
Example:

"Licenciamento de software como serviço (SaaS)"

hasCulturalIncentive
boolean
required

Whether your organization is a cultural incentivizer (incentivador cultural).

Example:

false

isSimplesNacional
boolean
required

Whether your organization is under the Simples Nacional tax regime. When false, the live (production) taxConfiguration must carry taxClassification and operationIndicatorCode, otherwise the request fails with TAX_CONFIGURATION_INCOMPLETE.

Example:

true

nfseHomologationConfigurations
object
required

Configuration of the test (homologation) environment: documents issued here have no fiscal value.

nfseProductionConfigurations
object
required

Configuration of the live (production) environment: documents issued here are legally valid.

serviceListItem
string

Item of the federal service list (LC 116/2003) that describes your service, such as 1.07. Up to 8 characters. Optional here, but required when you update the issuer. Used on every invoice that does not send its own.

Maximum string length: 8
Example:

"1.07"

Response

No Content. The operation succeeded and the response has no body.