Companies
Lifecycle of an issuing company on TF Fiscal, how one company serves NF-e, CT-e, DC-e and NFS-e, the tax regime and PIS/COFINS regime, DC-e and NFS-e enablement and the related error codes.
What a company is
A company (empresa) is the legal entity on whose behalf documents are issued: the seller of a marketplace, a carrier, or an integrator issuing for itself. Every company is identified by the empresaId returned by Register company, which is the path variable of every issuance, query and cancellation endpoint.
| Step | Endpoint | Notes |
|---|---|---|
| 1 Register company | POST /openapi/v2/empresas | Returns empresaId, dceHabilitado and nfseHabilitado; a body carrying id updates an existing company |
| 2 Link certificate | POST /openapi/v1/empresas/{empresaId}/certificadoDigital | A1 certificate (.pfx / .p12) and its password; multipart or JSON + Base64 |
| 3 Register webhook | POST /openapi/v1/webhooks | One callback URL per application, shared by every document type |
| 4 Track review | GET /openapi/v2/empresas, GET /openapi/v2/empresas/{empresaId} | List your companies; query review status, rejection reason, enabled documents and certificate summary by empresaId; not billed |
| All at once | POST /openapi/v2/empresas/cadastro-automatico | Just CNPJ, A1 certificate and password; the platform creates the company and links the certificate, replacing steps 1 and 2. Missing fields: Register company with id; status: Query company |
Lifecycle
- Registration: a successful call to Register company places the company in the platform approval queue. Registering the same CNPJ again returns
10003002; reuse the originalempresaIdor send an update withid. - Certificate: link the A1 certificate. The certificate must belong to the company CNPJ (
10003010), be valid (10003011) and differ from the currently active one (10003012); a wrong password returns10003008. A successful upload replaces the previous certificate. - Approval: when automatic approval is enabled for the integrator, the platform compares the registration data with the Brazilian company registry and approves automatically if they match; on a mismatch, when the registry lookup is unavailable, or when there is no record, operations review it manually. Without automatic approval, review is always manual. The company can issue only after operations approve it and the certificate is linked. Issuing before that returns
10004004for NF-e (10019004for DC-e,10017004for CT-e). Follow approval with List companies or Query company:statusAtivameans approved, and withRejeitadathe reason is inmotivoStatus. - Environment: every company has one current environment, test
Homologacaoor productionProducao. Newly registered companies start in test; switching to production is an operations action with no API. The environment value in every issuance request (ambienteEmissaofor NF-e and CT-e,ambientefor DC-e) must match the company's current environment; a mismatch returns10004030(NF-e),10017010(CT-e) or10019010(DC-e). See Environments.
Note: an update (body carrying
id) never resubmits the company for review and never changes its status or environment. The exception is draft or rejected companies, such as those left by automatic registration: without a state registration the update storesinscricaoEstadual, and once the data is complete a draft goes to review automatically; a rejected company only goes back to (manual) review when the update completes a field that was pending.
One company, four document types
The same empresaId, the same certificate and the same webhook serve every document type. What differs is the number series each type needs:
| Document type | Model | Series configured through | Environment field | Not issuable code |
|---|---|---|---|---|
| NF-e | 55 | emissaoNFeProduto.ambienteProducao (sequencialNFe / serieNFe) at registration or on update with id | ambienteEmissao | 10004004 |
| CT-e | 57 | Configured on the platform side; registration has no CT-e block. Without a series, or with several enabled and none chosen, issuance returns 10017007 | ambienteEmissao | 10017004 |
| DC-e | 99 | emissaoDCe.ambienteProducao (tipoEmitente, sequencialDCe / serieDCe, siteMarketplace) at registration or through an update with id | ambiente | 10019004 |
| NFS-e | — | emissaoNFSe (serieDps and the other profile defaults) at registration or through an update with id, or maintained by operations | ambienteEmissao | 10018004 |
emissaoNFeProduto,emissaoDCeandemissaoNFSeare each optional, at least one is required. An NF-e-only company sends the first, a DC-e-only or NFS-e-only company may omit it (no model 55 series is created), and sending more than one enables the corresponding document types. Omitting all three returns 40010001001.- The series and the next number submitted at registration are the ones used for issuance; afterwards the platform manages the sequence.
- On update with
idandemissaoNFeProduto: the series is created if it does not exist, otherwise its next number becomessequencialNFe, and the company's other NF-e series are disabled; without the block the series stay as they are. Moving the next number lower makes SEFAZ reject duplicates, moving it higher skips numbers that are not voided automatically; both are the caller's responsibility. See "Set the NF-e numbering" in Register company. - The same CNPJ may be registered under different integrators; each integrator sets its own series and the platform does not check for overlaps across integrators. When the same CNPJ issues through several integrators, each must use non-overlapping series; otherwise the numbers collide and SEFAZ rejects them.
- CT-e issuance additionally requires the CNPJ to be enabled for CT-e at the state tax authority; without it SEFAZ rejects with
230 - IE do emitente não cadastrada, which the platform cannot resolve.
Tax regime
The tax regime (Código de Regime Tributário, CRT) decides which tax codes an invoice uses and how taxes are calculated. The platform stores the official code 1 to 4 internally; the open API neither takes nor returns that code and expresses the regime with two booleans, optanteSimplesNacional and mei.
| CRT | Official name | Who | optanteSimplesNacional / mei in the company query |
|---|---|---|---|
| 1 | Simples Nacional | Micro or small company (ME / EPP) in Simples Nacional | true / false |
| 2 | Simples Nacional – excesso de sublimite de receita bruta | Simples Nacional member whose revenue exceeds the state and municipal sublimit | true / false |
| 3 | Regime Normal | Company outside Simples Nacional | false / false |
| 4 | Simples Nacional - Microempreendedor individual - MEI | Individual micro-entrepreneur | true / true |
The tax code family follows the regime: on NF-e and NFC-e, CRT 1 / 4 uses a 3-digit CSOSN and CRT 2 / 3 a 2-digit CST; otherwise 10004046 (see NF-e). The regime also decides whether regimeApuracaoSn is required in the NFS-e profile, see below. inscricaoEstadual is mandatory to issue NF-e, CT-e and DC-e: missing it returns 10003006; an NFS-e-only company is not required to carry a state registration.
How the two booleans become a CRT at registration
mei | optanteSimplesNacional | CRT stored |
|---|---|---|
false | false | 3 Regime Normal |
false | true | 1 Simples Nacional |
true | true | 4 MEI |
true | false | 4 MEI: mei takes precedence, no rejection, optanteSimplesNacional is not looked at |
Every MEI is a Simples Nacional member, so send true / true. No combination of the two booleans yields CRT 2; see "Over the sublimit" below.
Changing it later
- The Register company update with
iddoes not change the regime. The only exception is a company from automatic registration with the regime pending confirmation: then the two booleans in the request are stored once. - In the console, the "Tax settings" button on the company detail changes the CRT at any time (1 to 4), whatever the company status, and also clears the pending confirmation. The change reaches issuance within a minute, and referenced tax classes are revalidated under the new regime.
- Query company returns the two booleans from the current CRT; with the regime pending confirmation both are
null.
Over the sublimit (CRT 2)
The open API cannot express CRT 2, and the platform never deduces it. For these companies:
- At registration, send them as Simples Nacional:
optanteSimplesNacional=trueandmei=false; the platform stores CRT 1. - In the console, under "Tax settings", change the regime to Simples Nacional (over limit), which is CRT 2.
- From then on the company query returns
true/false, and resendingtrue/falsein an update withiddoes not turn it back into CRT 1.
With CRT 2, item ICMS uses a 2-digit CST.
Lucro Presumido, Lucro Real and Lucro Arbitrado
These are not tax regimes: they are methods of computing federal income tax, and on the invoice all of them are CRT 3 Regime Normal. The open API neither takes nor returns this information; CNPJ lookup, the company endpoints and automatic registration have no field for it. At issuance it only affects the PIS / COFINS rate for CST 01, which the platform calls the PIS/COFINS regime:
| PIS/COFINS regime | For | PIS | COFINS |
|---|---|---|---|
| Cumulative | Lucro Presumido, Lucro Arbitrado | 0.65 % | 3.00 % |
| Non-cumulative | Lucro Real | 1.65 % | 7.60 % |
The PIS/COFINS regime is set in the console under "Tax settings": Lucro Presumido (cumulative) or Lucro Real (non-cumulative); for Lucro Arbitrado pick cumulative. A CRT 3 company registered through the API starts with no PIS/COFINS regime. NFS-e also uses the PIS/COFINS regime, with rules of its own (see NFS-e); what follows covers NF-e and NFC-e only.
When a CRT 3 company issues NF-e or NFC-e (offline issuance included), the PIS and COFINS rate for CST 01 follows this table:
| In the request or the referenced tax class | Company with a PIS/COFINS regime | Company without a PIS/COFINS regime |
|---|---|---|
aliquota sent | Must equal the statutory rate above; otherwise rejected, 10005008 | The value sent is used |
aliquota omitted | The platform fills in the statutory rate | Rejected, 10005007 |
Saving a tax class runs the same check: with a PIS/COFINS regime set, a CST 01 row whose aliquota differs from the statutory rate returns 10005008. Outside CST 01 the platform does not fill a rate from the regime; nor does it for CRT 1, 2 and 4 companies.
Enabling DC-e
DC-e (model 99) is enabled by the emissaoDCe block:
"emissaoDCe": {"ambienteProducao": {"tipoEmitente": "Marketplace","sequencialDCe": 1,"serieDCe": "1","siteMarketplace": "https://loja.exemplo.com.br"}}
tipoEmitenteisMarketplace(a platform issuing on behalf of non-taxpayer sellers / individuals) orOwnIssuer(a company issuing for itself).Carriercan be registered but issuance is rejected with10019013.siteMarketplaceis required forMarketplace.- A company registered without
emissaoDCeis not enabled for DC-e: registration still succeeds, the response carriesdceHabilitado=falseand issuance returns10019012. Check that field right after registering. - To enable DC-e later, resend the registration payload with
idand theemissaoDCeblock. The model 99 series only moves up:sequencialDCemay raise the next number but never lower it (40010001001), and switchingserieDCewhile the old series is still enabled is refused (40010001001, go through operations).
Enabling NFS-e
NFS-e is enabled by the emissaoNFSe block. Only with it does the company start issuing NFS-e and get its numbering sequence. Only data that does not change from one invoice to the next lives here: service code, CNAE, NBS, ISS rate, withholding and IBS/CBS follow the service being sold and go in the servico block of each issuance.
"emissaoNFSe": {"serieDps": "1","sequencialDps": 1,"regimeApuracaoSn": 1,"regimeEspecialTributacao": 0}
| Field | Type | Required | Description |
|---|---|---|---|
serieDps | string(1-5 digits) | No | DPS / RPS series used when issuing. Every invoice uses this value; the issuance does not take a series of its own. Without this field, 1 |
sequencialDps | integer | No | Number of the next invoice to issue, starting at 1. When migrating from another provider, send the highest number already used plus one so the numbering carries on where it stopped. Without this field, 1. Once the sequence exists, updates do not change it |
regimeApuracaoSn | integer | Required for ME/EPP | How Simples Nacional computes the tax: 1 federal and municipal under SN / 2 federal under SN with a fixed municipal amount / 3 federal under SN with normal municipal. Simples membership comes from the top-level optanteSimplesNacional / mei. Sending it for a non-Simples company is rejected |
regimeEspecialTributacao | integer | No | Whether a special tax treatment applies: 0 none / 1 cooperative act / 2 assessed basis / 3 municipal micro-enterprise / 4 notary and registry / 5 self-employed professional / 6 partnership of professionals. Without this field, 0 |
- The registration response now carries
nfseHabilitado:{ "empresaId": "…", "dceHabilitado": false, "nfseHabilitado": true }. Without the block it isfalseand issuance returns10018005. - On update (a body with
id) sending the block replaces the whole profile: omitted optionals fall back to their defaults; without the block the profile is untouched andnfseHabilitadoreflects the current state. Forcing the municipal standard is an operations action and does not go through this block. - Structural rules rejected at acceptance (400
10001001): ME/EPP withoutregimeApuracaoSn, non-Simples company withregimeApuracaoSn. - An NFS-e-only company may omit
emissaoNFeProduto(no model 55 series is created) and is not required to carryinscricaoEstadual. - The São Paulo municipal registration (CCM) is taken from the top-level
inscricaoMunicipaland is not repeated in this block.
Related error codes
| codigo | HTTP | Scenario | Action |
|---|---|---|---|
10003002 | 400 | CNPJ already registered | The company exists: use the original empresaId or update with id |
10003000 | 404 | empresaId does not exist or does not belong to this application | Check the empresaId |
10003006 | 400 | Registration data missing the IE | Provide inscricaoEstadual |
10003010 / 10003011 / 10003012 | 400 | Certificate CNPJ mismatch / expired / identical to the current one | Use the correct certificate |
10003035 | 400 | Invalid Base64 or certificate above 1MB (JSON shape) | Fix the encoding or the file |
10003008 | 400 | Certificate password mismatch | Check the password |
10003004 | 400 | Registration: city / state cannot be resolved to an IBGE code | Check the UF and city name |
10004004 | 400 | Company not issuable (not yet approved or certificate not ready) | Wait for approval / link the certificate |
10004030 | 400 | ambienteEmissao does not match the company's current environment | Submit under the company environment or ask operations to switch it |
10001001 | 400 | Field validation failed, or registration / update contract error (all three configuration blocks missing, update changing cnpj / municipality, lowering the DC-e series cursor, switching series, emissaoNFSe structural rules not met) | Fix per mensagem |
The full list is in Error codes.
