Companies
Register company
Registers the issuing company (or updates it when the body carries `id`) and returns the `empresaId` used by every later endpoint.
/openapi/v2/empresastoken, timestamp and sign signature headers, see Authentication.Submit the seller company data; the response carries the empresaId, the path variable of every later endpoint. The emissaoNFeProduto, emissaoNFeConsumidor, emissaoDCe and emissaoNFSe blocks are each optional, at least one is required: send the block of each document type the company will issue; omitting all of them returns 400 10001001. A body carrying id is treated as an update, see the section below.
Request body
id*Required for update. | string | Company identifier |
cnpj* | string | Company CNPJ |
inscricaoMunicipal | string | Municipal registration |
inscricaoEstadual*Required for NF-e / NFC-e / DC-e. | string | State registration |
razaoSocial* | string | Legal name |
nomeFantasia | string | Trade name |
optanteSimplesNacional* | bool | Simples member |
mei* | bool | Individual micro-entrepreneur |
email* | string | Contact e-mail |
telefoneComercial* | string | Business phone |
* | object | Company address |
*At least one of emissaoNFeProduto / emissaoNFeConsumidor / emissaoDCe / emissaoNFSe. | object | NF-e configuration |
*At least one of emissaoNFeProduto / emissaoNFeConsumidor / emissaoDCe / emissaoNFSe. | object | NFC-e configuration |
*At least one of emissaoNFeProduto / emissaoNFeConsumidor / emissaoDCe / emissaoNFSe. | object | DC-e configuration |
*At least one of emissaoNFeProduto / emissaoNFeConsumidor / emissaoDCe / emissaoNFSe. | object | NFS-e configuration |
* Required field
empresaId | string | Company identifier |
dceHabilitado | bool | DC-e enabled |
nfseHabilitado | bool | NFS-e enabled |
nfceHabilitado | bool | NFC-e enabled |
- Registration enters the platform approval queue; the company issues only after operations approve it and the certificate is linked (Link certificate). Issuing before that returns
10004004(NF-e) or10019004(DC-e). Check progress with platform operations. - After registration the company is in the certification environment: integrate with
ambienteEmissao=Homologacao(NF-e) /ambiente=Homologacao(DC-e). Switching to production is an operations action with no API; sendingProducaobefore the switch returns10004030(NF-e) or10019012(DC-e). See Environments. - The tax regime comes from
meiandoptanteSimplesNacional; there is no field of its own.
Send the configuration block of each document type the company will issue. The company data is always the same; each scenario below shows only what changes.
NF-e only
The most common case. inscricaoEstadual required.
{"cnpj": "14422279000106","inscricaoEstadual": "999999","razaoSocial": "Empresa teste LTDA","optanteSimplesNacional": true,"mei": false,"email": "empresa-teste@exemplo.com.br","telefoneComercial": "6122222222","endereco": { "pais": "Brasil", "uf": "MG", "cidade": "Belo Horizonte", "logradouro": "Rua Teste", "numero": "999", "bairro": "Bairro Teste", "cep": "85100000" },"emissaoNFeProduto": { "ambienteProducao": { "sequencialNFe": 1, "serieNFe": "10" } }}
inscricaoEstadual* | string | State registration |
* | object | NF-e configuration |
* Required field
NF-e and NFC-e
A shop that sells over the counter and also invoices companies. The NFC-e series is separate from the NF-e series. inscricaoEstadual required.
{"cnpj": "14422279000106","inscricaoEstadual": "999999","razaoSocial": "Empresa teste LTDA","optanteSimplesNacional": true,"mei": false,"email": "empresa-teste@exemplo.com.br","telefoneComercial": "6122222222","endereco": { "pais": "Brasil", "uf": "MG", "cidade": "Belo Horizonte", "logradouro": "Rua Teste", "numero": "999", "bairro": "Bairro Teste", "cep": "85100000" },"emissaoNFeProduto": { "ambienteProducao": { "sequencialNFe": 1, "serieNFe": "10" } },"emissaoNFeConsumidor": { "ambienteProducao": { "sequencialNFe": 1, "serieNFe": "1" } }}
inscricaoEstadual* | string | State registration |
* | object | NFC-e configuration |
* Required field
NFS-e only
Service company without state registration. inscricaoMunicipal is the city-hall registration; in São Paulo it is the CCM.
{"cnpj": "14422279000106","inscricaoMunicipal": "999999","razaoSocial": "Servicos teste LTDA","optanteSimplesNacional": true,"mei": false,"email": "servicos-teste@exemplo.com.br","telefoneComercial": "1133334444","endereco": { "pais": "Brasil", "uf": "SP", "cidade": "Sao Paulo", "logradouro": "Av. Paulista", "numero": "1000", "bairro": "Bela Vista", "cep": "01310100" },"emissaoNFSe": { "serieDps": "1", "sequencialDps": 1, "regimeApuracaoSn": 1 }}
inscricaoMunicipal | string | Municipal registration |
* | object | NFS-e configuration |
* Required field
NF-e and DC-e as a marketplace
Platform issuing DC-e for third parties. siteMarketplace is required; Carrier can be registered but does not issue.
{"cnpj": "14422279000106","inscricaoEstadual": "999999","razaoSocial": "Empresa teste LTDA","optanteSimplesNacional": true,"mei": false,"email": "empresa-teste@exemplo.com.br","telefoneComercial": "6122222222","endereco": { "pais": "Brasil", "uf": "MG", "cidade": "Belo Horizonte", "logradouro": "Rua Teste", "numero": "999", "bairro": "Bairro Teste", "cep": "85100000" },"emissaoNFeProduto": { "ambienteProducao": { "sequencialNFe": 1, "serieNFe": "10" } },"emissaoDCe": { "ambienteProducao": { "tipoEmitente": "Marketplace", "sequencialDCe": 1, "serieDCe": "1", "siteMarketplace": "https://loja.exemplo.com.br" } }}
* | object | DC-e configuration |
* Required field
The same endpoint with id in the body is an update: resend the registration payload with id added, since the other fields are still validated with the registration rules. It does not update cnpj, razaoSocial, inscricaoEstadual, inscricaoMunicipal, tax regime (change it in the console, under "Tax settings") or environment. Without emissaoNFeProduto the NF-e series stay as they are; with it, see "Set the NF-e numbering" below. Changing municipality (uf / cidade) returns 400 10001001 and goes through operations. An update does not resubmit the company for approval nor change its status; the response is the same as at registration.
Automatically registered companies. For companies created by Register company automatically the update also completes pending fields: if the company is a draft or rejected and has no state registration yet, inscricaoEstadual is stored; if the tax regime is pending confirmation, mei and optanteSimplesNacional set the regime (without that pending flag the regime is still not updated); a draft whose data becomes complete goes to review automatically; a rejected company only goes back to review, manually, when the update completes a field that was pending (this applies to any draft or rejected company of this account, including those created in the console). What is missing appears in camposPendentes of Query company.
Set the NF-e numbering
For companies without an NF-e series (such as those from automatic registration) or that change series or next number. If the serieNFe has no series yet, it is created with sequencialNFe as the next number; if it exists, the next number becomes sequencialNFe and a disabled series is enabled again. The company's other NF-e series are disabled, so issuance uses only this one.
sequencialNFe may go lower or higher, and the caller is responsible: lower issues numbers already used again and SEFAZ rejects them as duplicates; higher leaves the numbers in between skipped, and they are not voided automatically (void them yourself if needed). Numbers from earlier issuances that were not authorized and are lower than sequencialNFe are still used first. Above 999999999 returns 400 10001001.
{"id": "1934811222334455","cnpj": "14422279000106","inscricaoEstadual": "999999","razaoSocial": "Empresa teste LTDA","optanteSimplesNacional": true,"mei": false,"email": "empresa-teste@exemplo.com.br","telefoneComercial": "6122222222","endereco": { "pais": "Brasil", "uf": "MG", "cidade": "Belo Horizonte", "logradouro": "Rua Teste", "numero": "999", "bairro": "Bairro Teste", "cep": "85100000" },"emissaoNFeProduto": { "ambienteProducao": { "sequencialNFe": 1501, "serieNFe": "10" } }}
id* | string | Company identifier |
* | object | NF-e configuration |
* Required field
Enable DC-e later
Company registered without emissaoDCe. If no DC-e series is enabled yet, one is created from sequencialDCe / serieDCe.
{"id": "1934811222334455","cnpj": "14422279000106","inscricaoEstadual": "999999","razaoSocial": "Empresa teste LTDA","optanteSimplesNacional": true,"mei": false,"email": "empresa-teste@exemplo.com.br","telefoneComercial": "6122222222","endereco": { "pais": "Brasil", "uf": "MG", "cidade": "Belo Horizonte", "logradouro": "Rua Teste", "numero": "999", "bairro": "Bairro Teste", "cep": "85100000" },"emissaoDCe": { "ambienteProducao": { "tipoEmitente": "OwnIssuer", "sequencialDCe": 1, "serieDCe": "1" } }}
id* | string | Company identifier |
* | object | DC-e configuration |
* Required field
Raise the next DC-e number
Same series, sequencialDCe higher than the current next number. Equal to the current one changes nothing; lower returns 400 10001001. Skipped numbers are never issued. Changing serieDCe while the old one is enabled also returns 400 10001001.
{"id": "1934811222334455","cnpj": "14422279000106","inscricaoEstadual": "999999","razaoSocial": "Empresa teste LTDA","optanteSimplesNacional": true,"mei": false,"email": "empresa-teste@exemplo.com.br","telefoneComercial": "6122222222","endereco": { "pais": "Brasil", "uf": "MG", "cidade": "Belo Horizonte", "logradouro": "Rua Teste", "numero": "999", "bairro": "Bairro Teste", "cep": "85100000" },"emissaoDCe": { "ambienteProducao": { "tipoEmitente": "OwnIssuer", "sequencialDCe": 500, "serieDCe": "1" } }}
id* | string | Company identifier |
* | object | DC-e configuration |
* Required field
Fix contact details and address
Only nomeFantasia, email, telefoneComercial and the address fields within the same municipality change. Empty fields do not clear the stored value.
{"id": "1934811222334455","cnpj": "14422279000106","inscricaoEstadual": "999999","razaoSocial": "Empresa teste LTDA","nomeFantasia": "Loja Teste","optanteSimplesNacional": true,"mei": false,"email": "financeiro@exemplo.com.br","telefoneComercial": "3133334444","endereco": { "pais": "Brasil", "uf": "MG", "cidade": "Belo Horizonte", "logradouro": "Rua Nova", "numero": "10", "complemento": "Sala 2", "bairro": "Centro", "cep": "30110000" }}
id* | string | Company identifier |
nomeFantasia | string | Trade name |
email | string | Contact e-mail |
telefoneComercial | string | Business phone |
* | object | Address |
* Required field
Create or replace the NFS-e profile
Sending emissaoNFSe replaces the whole profile; omitted fields fall back to defaults. An existing series is not changed: sequencialDps only applies when the series does not exist yet.
{"id": "1934811222334455","cnpj": "14422279000106","inscricaoEstadual": "999999","razaoSocial": "Empresa teste LTDA","optanteSimplesNacional": true,"mei": false,"email": "empresa-teste@exemplo.com.br","telefoneComercial": "6122222222","endereco": { "pais": "Brasil", "uf": "MG", "cidade": "Belo Horizonte", "logradouro": "Rua Teste", "numero": "999", "bairro": "Bairro Teste", "cep": "85100000" },"emissaoNFSe": { "serieDps": "1", "sequencialDps": 120, "regimeApuracaoSn": 1, "regimeEspecialTributacao": 0 }}
id* | string | Company identifier |
* | object | NFS-e configuration |
* Required field
mei + optanteSimplesNacionalCompany tax regime
There is no field of its own: the regime comes from combining the two booleans and is stored as a CRT. mei=true takes precedence. No combination yields CRT 2 (over the sublimit), which is set in the console; Lucro Presumido, Real or Arbitrado are all CRT 3. See "Tax regime" in Companies.
| Values | Meaning |
|---|---|
| mei=true | CRT 4, MEI, individual micro-entrepreneur; optanteSimplesNacional is ignored; emissaoNFSe.regimeApuracaoSn is not needed |
| mei=false, optanteSimplesNacional=true | CRT 1, Simples Nacional, ME or EPP; a company over the sublimit also sends this; with emissaoNFSe requires regimeApuracaoSn |
| mei=false, optanteSimplesNacional=false | CRT 3, Regime Normal, including Lucro Presumido, Real or Arbitrado; emissaoNFSe.regimeApuracaoSn must not be sent |
endereco.ufCompany state
| Values | Meaning |
|---|---|
| AC | Acre |
| AL | Alagoas |
| AP | Amapá |
| AM | Amazonas |
| BA | Bahia |
| CE | Ceará |
| DF | Distrito Federal |
| ES | Espírito Santo |
| GO | Goiás |
| MA | Maranhão |
| MT | Mato Grosso |
| MS | Mato Grosso do Sul |
| MG | Minas Gerais |
| PA | Pará |
| PB | Paraíba |
| PR | Paraná |
| PE | Pernambuco |
| PI | Piauí |
| RJ | Rio de Janeiro |
| RN | Rio Grande do Norte |
| RS | Rio Grande do Sul |
| RO | Rondônia |
| RR | Roraima |
| SC | Santa Catarina |
| SP | São Paulo |
| SE | Sergipe |
| TO | Tocantins |
emissaoDCe.ambienteProducao.tipoEmitenteDC-e issuer type
Case-insensitive.
| Values | Meaning |
|---|---|
| Marketplace | E-commerce platform issuing for third parties; requires siteMarketplace |
| OwnIssuer | Company issuing for itself |
| EmissorProprio | Same as OwnIssuer |
| Carrier | Carrier; registration accepted, issuance refused with 10019013 |
| Transportadora | Same as Carrier |
emissaoNFSe.regimeApuracaoSnSimples Nacional assessment
ME/EPP only: optanteSimplesNacional=true and mei=false.
| Values | Meaning |
|---|---|
| 1 | Federal and municipal taxes under Simples Nacional |
| 2 | Federal under Simples Nacional; ISS as a fixed municipal amount |
| 3 | Federal under Simples Nacional; ISS at the normal municipal rate |
emissaoNFSe.regimeEspecialTributacaoSpecial tax regime
Omitted means 0.
| Values | Meaning |
|---|---|
| 0 | None |
| 1 | Cooperative act |
| 2 | Assessed basis |
| 3 | Municipal micro-enterprise |
| 4 | Notary and registry |
| 5 | Self-employed professional |
| 6 | Partnership of professionals |
| Code | HTTP | |
|---|---|---|
| 10003002 | 400 | CNPJ already registered. The company exists: use the original empresaId or update with id. |
| 10003000 | 404 | Update: id does not exist or does not belong to this application. |
| 10003006 | 400 | Required data missing: inscricaoEstadual for an NF-e / DC-e company, or siteMarketplace with tipoEmitente=Marketplace. The message names the field. |
| 10003004 | 400 | City and state cannot be resolved to an IBGE code. Check endereco.uf and endereco.cidade. |
| 10001001 | 400 | Request field validation failed, one entry per field, or contract error: no configuration block, invalid tipoEmitente, update changing cnpj or municipality, sequencialDCe lower than current, series switch. Fix per mensagem. |
