Empresas
Registrar empresa
Cadastra a empresa emitente (ou a atualiza quando o corpo traz `id`) e devolve o `empresaId` usado por todos os demais endpoints.
/openapi/v2/empresastoken, timestamp e sign, veja Autenticação.Envia os dados da empresa do vendedor; a resposta traz o empresaId, variável de caminho de todos os endpoints seguintes. Os blocos emissaoNFeProduto, emissaoNFeConsumidor, emissaoDCe e emissaoNFSe são cada um opcional, mas pelo menos um é obrigatório: envie o bloco de cada tipo de documento que a empresa vai emitir; omitir todos devolve 400 10001001. Um corpo com id é tratado como atualização, veja a seção correspondente abaixo.
Corpo da requisição
id*Obrigatório para atualizar. | string | Identificador da empresa |
cnpj* | string | CNPJ da empresa |
inscricaoMunicipal | string | Inscrição municipal |
inscricaoEstadual*Obrigatória para NF-e / NFC-e / DC-e. | string | Inscrição estadual |
razaoSocial* | string | Razão social |
nomeFantasia | string | Nome fantasia |
optanteSimplesNacional* | bool | Optante do Simples |
mei* | bool | Microempreendedor individual |
email* | string | E-mail de contato |
telefoneComercial* | string | Telefone comercial |
* | object | Endereço da empresa |
*Pelo menos um entre emissaoNFeProduto / emissaoNFeConsumidor / emissaoDCe / emissaoNFSe. | object | Configuração de NF-e |
*Pelo menos um entre emissaoNFeProduto / emissaoNFeConsumidor / emissaoDCe / emissaoNFSe. | object | Configuração de NFC-e |
*Pelo menos um entre emissaoNFeProduto / emissaoNFeConsumidor / emissaoDCe / emissaoNFSe. | object | Configuração de DC-e |
*Pelo menos um entre emissaoNFeProduto / emissaoNFeConsumidor / emissaoDCe / emissaoNFSe. | object | Configuração de NFS-e |
* Campo obrigatório
empresaId | string | Identificador da empresa |
dceHabilitado | bool | DC-e habilitado |
nfseHabilitado | bool | NFS-e habilitado |
nfceHabilitado | bool | NFC-e habilitada |
- O cadastro entra na fila de aprovação da plataforma; a empresa emite somente após a aprovação da operação e a vinculação do certificado (Vincular certificado). Emitir antes devolve
10004004(NF-e) ou10019004(DC-e). Consulte o andamento com a operação da plataforma. - Após o cadastro a empresa fica no ambiente de homologação: integre com
ambienteEmissao=Homologacao(NF-e) /ambiente=Homologacao(DC-e). A troca para produção é uma ação da operação, sem API; enviarProducaoantes da troca devolve10004030(NF-e) ou10019012(DC-e). Veja Ambientes. - O regime tributário vem de
meieoptanteSimplesNacional; não há campo próprio.
Envie o bloco de configuração de cada tipo de documento que a empresa vai emitir. Os dados da empresa são sempre os mesmos; abaixo, cada cenário mostra só o que muda.
Só NF-e
O caso mais comum. inscricaoEstadual obrigatória.
{"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 | Inscrição estadual |
* | object | Configuração de NF-e |
* Campo obrigatório
NF-e e NFC-e
Loja que vende no balcão e também fatura para empresas. A série da NFC-e é separada da série da NF-e. inscricaoEstadual obrigatória.
{"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 | Inscrição estadual |
* | object | Configuração de NFC-e |
* Campo obrigatório
Só NFS-e
Empresa de serviços sem inscrição estadual. inscricaoMunicipal é a inscrição na prefeitura; em São Paulo é o 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 | Inscrição municipal |
* | object | Configuração de NFS-e |
* Campo obrigatório
NF-e e DC-e como marketplace
Plataforma que emite DC-e por terceiros. siteMarketplace é obrigatório; Carrier pode ser cadastrado, mas não emite.
{"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 | Configuração de DC-e |
* Campo obrigatório
O mesmo endpoint com id no corpo é uma atualização: reenvie o payload de cadastro acrescentando id, pois os demais campos continuam validados pelas regras de cadastro. Não atualiza cnpj, razaoSocial, inscricaoEstadual, inscricaoMunicipal, regime tributário (mude no console, em «Dados tributários») nem ambiente. Sem emissaoNFeProduto as séries de NF-e ficam como estão; com ele, veja «Definir a numeração de NF-e» abaixo. Mudar de município (uf / cidade) devolve 400 10001001 e passa pela operação. A atualização não reenvia a empresa para aprovação nem muda o status dela; a resposta é a mesma do cadastro.
Empresas do cadastro automático. Para empresas criadas por Cadastrar empresa automaticamente a atualização também completa as pendências: se a empresa está em rascunho ou rejeitada e ainda não tem inscrição estadual, inscricaoEstadual é gravada; se o regime está pendente de confirmação, mei e optanteSimplesNacional passam a definir o regime (sem essa pendência o regime continua sem atualização); um rascunho que fique com os dados completos entra em análise automaticamente; uma rejeitada só volta para análise, manual, quando a atualização completa um campo que estava pendente (vale para qualquer rascunho ou rejeitada desta conta, inclusive os criados no console). O que falta aparece em camposPendentes de Consultar empresa.
Definir a numeração de NF-e
Para empresas sem série de NF-e (como as do cadastro automático) ou que vão trocar de série ou de próximo número. Se a serieNFe ainda não tem série, ela é criada com sequencialNFe como próximo número; se já tem, o próximo número passa a ser sequencialNFe e uma série desabilitada volta a ficar habilitada. As demais séries de NF-e da empresa são desabilitadas, para que a emissão use só esta.
sequencialNFe pode ir para menos ou para mais, e a responsabilidade é de quem chama: para menos, números já usados são emitidos de novo e a SEFAZ os recusa como duplicados; para mais, os números do meio ficam pulados e não são inutilizados automaticamente (inutilize-os por conta própria se for o caso). Números de emissões anteriores que não foram autorizadas e são menores que sequencialNFe ainda são aproveitados primeiro. Acima de 999999999 devolve 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 | Identificador da empresa |
* | object | Configuração de NF-e |
* Campo obrigatório
Habilitar DC-e depois
Empresa cadastrada sem emissaoDCe. Se nenhuma série de DC-e estiver habilitada, ela é criada a partir de 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 | Identificador da empresa |
* | object | Configuração de DC-e |
* Campo obrigatório
Elevar o próximo número do DC-e
Mesma série, sequencialDCe maior que o próximo número atual. Igual ao atual não muda nada; menor devolve 400 10001001. Os números pulados nunca são emitidos. Trocar serieDCe com a antiga habilitada também devolve 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 | Identificador da empresa |
* | object | Configuração de DC-e |
* Campo obrigatório
Corrigir contato e endereço
Só nomeFantasia, email, telefoneComercial e os campos de endereço dentro do mesmo município mudam. Campos vazios não apagam o valor guardado.
{"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 | Identificador da empresa |
nomeFantasia | string | Nome fantasia |
email | string | E-mail de contato |
telefoneComercial | string | Telefone comercial |
* | object | Endereço |
* Campo obrigatório
Criar ou substituir o perfil de NFS-e
Enviar emissaoNFSe substitui o perfil inteiro; campos omitidos voltam ao padrão. A série já criada não é alterada: sequencialDps só vale quando a série ainda não existe.
{"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 | Identificador da empresa |
* | object | Configuração de NFS-e |
* Campo obrigatório
mei + optanteSimplesNacionalRegime tributário da empresa
Não há campo próprio: o regime sai da combinação dos dois booleanos e é gravado como CRT. mei=true prevalece. Nenhuma combinação gera CRT 2 (excesso de sublimite), que se define no console; Lucro Presumido, Real ou Arbitrado são todos CRT 3. Veja «Regime tributário» em Empresas.
| Valores | Significado |
|---|---|
| mei=true | CRT 4, MEI, microempreendedor individual; optanteSimplesNacional é ignorado; emissaoNFSe.regimeApuracaoSn não é necessário |
| mei=false, optanteSimplesNacional=true | CRT 1, Simples Nacional, ME ou EPP; excesso de sublimite também envia isto; com emissaoNFSe exige regimeApuracaoSn |
| mei=false, optanteSimplesNacional=false | CRT 3, Regime Normal, inclusive Lucro Presumido, Real ou Arbitrado; emissaoNFSe.regimeApuracaoSn não pode ser enviado |
endereco.ufEstado da empresa
| Valores | Significado |
|---|---|
| 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.tipoEmitenteTipo de emitente do DC-e
Sem distinção de maiúsculas.
| Valores | Significado |
|---|---|
| Marketplace | Plataforma de e-commerce que emite por terceiros; exige siteMarketplace |
| OwnIssuer | Empresa que emite por si mesma |
| EmissorProprio | Mesmo que OwnIssuer |
| Carrier | Transportadora; cadastro aceito, emissão recusada com 10019013 |
| Transportadora | Mesmo que Carrier |
emissaoNFSe.regimeApuracaoSnApuração no Simples Nacional
Só para ME/EPP: optanteSimplesNacional=true e mei=false.
| Valores | Significado |
|---|---|
| 1 | Tributos federais e municipal pelo Simples Nacional |
| 2 | Federais pelo Simples Nacional; ISS em valor fixo municipal |
| 3 | Federais pelo Simples Nacional; ISS pela alíquota normal do município |
emissaoNFSe.regimeEspecialTributacaoRegime especial de tributação
Omitido vale 0.
| Valores | Significado |
|---|---|
| 0 | Nenhum |
| 1 | Ato cooperado |
| 2 | Estimativa |
| 3 | Microempresa municipal |
| 4 | Notarial e registral |
| 5 | Profissional autônomo |
| 6 | Sociedade de profissionais |
| Código | HTTP | |
|---|---|---|
| 10003002 | 400 | CNPJ já cadastrado. A empresa existe: use o empresaId original ou atualize com id. |
| 10003000 | 404 | Atualização: id não existe ou não pertence a esta aplicação. |
| 10003006 | 400 | Dado obrigatório ausente: inscricaoEstadual em empresa de NF-e / DC-e, ou siteMarketplace com tipoEmitente=Marketplace. A mensagem nomeia o campo. |
| 10003004 | 400 | Cidade e estado não resolvem para um código IBGE. Verifique endereco.uf e endereco.cidade. |
| 10001001 | 400 | Falha de validação de campos, uma entrada por campo, ou erro de contrato: nenhum bloco de configuração, tipoEmitente inválido, atualização mudando cnpj ou município, sequencialDCe menor que o atual, troca de série. Corrija conforme mensagem. |
