Empresas
Ciclo de vida de uma empresa emitente na TF Fiscal, como uma empresa atende NF-e, CT-e, DC-e e NFS-e, regime tributário e regime de PIS/COFINS, habilitação de DC-e e de NFS-e e os códigos de erro relacionados.
O que é uma empresa
Uma empresa (empresa) é a entidade legal em nome da qual os documentos são emitidos: o vendedor de um marketplace, uma transportadora ou um integrador emitindo para si mesmo. Toda empresa é identificada pelo empresaId devolvido por Registrar empresa, que é a variável de caminho de todos os endpoints de emissão, consulta e cancelamento.
| Etapa | Endpoint | Observações |
|---|---|---|
| 1 Registrar empresa | POST /openapi/v2/empresas | Devolve empresaId, dceHabilitado e nfseHabilitado; um corpo com id atualiza uma empresa existente |
| 2 Vincular certificado | POST /openapi/v1/empresas/{empresaId}/certificadoDigital | Certificado A1 (.pfx / .p12) e sua senha; multipart ou JSON + Base64 |
| 3 Registrar webhook | POST /openapi/v1/webhooks | Uma URL de callback por aplicação, compartilhada por todos os tipos de documento |
| 4 Acompanhar a análise | GET /openapi/v2/empresas, GET /openapi/v2/empresas/{empresaId} | Lista suas empresas; consulta status da análise, motivo de rejeição, documentos habilitados e resumo do certificado pelo empresaId; não cobrado |
| Tudo de uma vez | POST /openapi/v2/empresas/cadastro-automatico | Só CNPJ, certificado A1 e senha; a plataforma cria a empresa e vincula o certificado, substituindo os passos 1 e 2. Pendências: Registrar empresa com id; situação: Consultar empresa |
Ciclo de vida
- Cadastro: uma chamada bem-sucedida a Registrar empresa coloca a empresa na fila de aprovação da plataforma. Cadastrar o mesmo CNPJ de novo devolve
10003002; reutilize oempresaIdoriginal ou envie uma atualização comid. - Certificado: vincule o certificado A1. O certificado deve pertencer ao CNPJ da empresa (
10003010), estar válido (10003011) e ser diferente do atualmente ativo (10003012); senha errada devolve10003008. Um envio bem-sucedido substitui o certificado anterior. - Aprovação: quando a aprovação automática está ativa para o integrador, a plataforma compara os dados cadastrados com o cadastro nacional de empresas e aprova automaticamente se coincidirem; em caso de divergência, serviço de consulta indisponível ou ausência de registro, a operação analisa manualmente. Sem aprovação automática, a análise é sempre manual. A empresa só emite depois que a operação a aprova e o certificado está vinculado. Emitir antes disso devolve
10004004para NF-e (10019004para DC-e,10017004para CT-e). Acompanhe a aprovação em Listar empresas ou Consultar empresa:statusAtivasignifica aprovada e, comRejeitada, o motivo vem emmotivoStatus. - Ambiente: toda empresa tem um ambiente atual, homologação
Homologacaoou produçãoProducao. Empresas recém-cadastradas começam em homologação; a troca para produção é uma ação da operação, sem API. O valor de ambiente em toda requisição de emissão (ambienteEmissaopara NF-e e CT-e,ambientepara DC-e) deve ser igual ao ambiente atual da empresa; divergência devolve10004030(NF-e),10017010(CT-e) ou10019010(DC-e). Veja Ambientes.
Nota: uma atualização (corpo com
id) nunca ressubmete a empresa para revisão e nunca altera seu status ou ambiente. A exceção são as empresas em rascunho ou rejeitadas, como as deixadas pelo cadastro automático: sem inscrição estadual, a atualização gravainscricaoEstadual, e com os dados completos o rascunho entra em análise automaticamente; a rejeitada só volta para análise (manual) quando a atualização completa um campo que estava pendente.
Uma empresa, quatro tipos de documento
O mesmo empresaId, o mesmo certificado e o mesmo webhook atendem todos os tipos de documento. O que muda é a série de numeração que cada tipo exige:
| Tipo de documento | Modelo | Série configurada por | Campo de ambiente | Código de não emissão |
|---|---|---|---|---|
| NF-e | 55 | emissaoNFeProduto.ambienteProducao (sequencialNFe / serieNFe) no cadastro ou na atualização com id | ambienteEmissao | 10004004 |
| CT-e | 57 | Configurada do lado da plataforma; o cadastro não tem bloco de CT-e. Sem série, ou com várias habilitadas e nenhuma escolhida, a emissão devolve 10017007 | ambienteEmissao | 10017004 |
| DC-e | 99 | emissaoDCe.ambienteProducao (tipoEmitente, sequencialDCe / serieDCe, siteMarketplace) no cadastro ou em uma atualização com id | ambiente | 10019004 |
| NFS-e | — | emissaoNFSe (serieDps e os demais valores padrão do perfil) no cadastro ou em uma atualização com id, ou mantido pela operação | ambienteEmissao | 10018004 |
emissaoNFeProduto,emissaoDCeeemissaoNFSesão cada um opcional, mas pelo menos um é obrigatório. Uma empresa só de NF-e envia o primeiro, uma empresa só de DC-e ou só de NFS-e pode omiti-lo (nenhuma série do modelo 55 é criada) e enviar mais de um habilita os tipos de documento correspondentes. Omitir os três devolve 40010001001.- A série e o próximo número enviados no cadastro são os usados na emissão; depois disso a plataforma gerencia a sequência.
- Na atualização com
ideemissaoNFeProduto: a série é criada se não existir; se existir, o próximo número passa a sersequencialNFe, e as demais séries de NF-e da empresa são desabilitadas; sem o bloco as séries ficam como estão. Baixar o próximo número faz a SEFAZ recusar duplicados, subir pula números que não são inutilizados automaticamente; as duas coisas são responsabilidade de quem chama. Veja «Definir a numeração de NF-e» em Registrar empresa. - O mesmo CNPJ pode ser cadastrado por integradores diferentes; cada integrador define as próprias séries e a plataforma não verifica conflitos entre integradores. Se o mesmo CNPJ emite por vários integradores, cada um precisa usar séries que não se sobreponham; caso contrário os números colidem e a SEFAZ rejeita.
- A emissão de CT-e exige ainda que o CNPJ esteja habilitado para CT-e na SEFAZ estadual; sem isso a SEFAZ rejeita com
230 - IE do emitente não cadastrada, o que a plataforma não pode resolver.
Regime tributário
O regime tributário (Código de Regime Tributário, CRT) define quais códigos tributários a nota usa e como os tributos são calculados. A plataforma guarda internamente o código oficial de 1 a 4; a API aberta não recebe nem devolve esse código e expressa o regime com dois booleanos, optanteSimplesNacional e mei.
| CRT | Nome oficial | Quem é | optanteSimplesNacional / mei na consulta da empresa |
|---|---|---|---|
| 1 | Simples Nacional | Microempresa ou empresa de pequeno porte (ME / EPP) do Simples Nacional | true / false |
| 2 | Simples Nacional – excesso de sublimite de receita bruta | Optante do Simples Nacional com receita acima do sublimite estadual e municipal | true / false |
| 3 | Regime Normal | Empresa fora do Simples Nacional | false / false |
| 4 | Simples Nacional - Microempreendedor individual - MEI | Microempreendedor individual | true / true |
A família de código acompanha o regime: em NF-e e NFC-e, CRT 1 / 4 usa CSOSN de 3 dígitos e CRT 2 / 3 usa CST de 2 dígitos; fora disso, 10004046 (veja NF-e). O regime também define se regimeApuracaoSn é obrigatório no perfil de NFS-e, veja abaixo. inscricaoEstadual é obrigatória para emitir NF-e, CT-e e DC-e: ausente devolve 10003006; uma empresa só de NFS-e não precisa de inscrição estadual.
Como os dois booleanos viram CRT no cadastro
mei | optanteSimplesNacional | CRT gravado |
|---|---|---|
false | false | 3 Regime Normal |
false | true | 1 Simples Nacional |
true | true | 4 MEI |
true | false | 4 MEI: mei prevalece, sem recusa e sem olhar optanteSimplesNacional |
Todo MEI é optante do Simples Nacional, então envie true / true. Nenhuma combinação dos dois booleanos gera CRT 2; veja «Excesso de sublimite» abaixo.
Como mudar depois
- A atualização de Registrar empresa com
idnão muda o regime. A única exceção é a empresa do cadastro automático com regime pendente de confirmação: nesse caso os dois booleanos da requisição são gravados uma vez. - No console, o botão «Dados tributários» do detalhe da empresa muda o CRT a qualquer momento (de 1 a 4), em qualquer status da empresa, e também encerra a pendência de confirmação. A mudança vale para a emissão em até um minuto, e as classes de imposto referenciadas são revalidadas pelo regime novo.
- Consultar empresa devolve os dois booleanos conforme o CRT atual; com o regime pendente de confirmação, os dois vêm
null.
Excesso de sublimite (CRT 2)
A API aberta não expressa o CRT 2, e a plataforma nunca o deduz. Para essas empresas:
- No cadastro, envie como Simples Nacional:
optanteSimplesNacional=trueemei=false; a plataforma grava CRT 1. - No console, em «Dados tributários», mude o regime para Simples Nacional (excesso de sublimite), o CRT 2.
- Depois disso a consulta da empresa devolve
true/false, e reenviartrue/falsenuma atualização comidnão volta para CRT 1.
Com CRT 2, o ICMS dos itens usa CST de 2 dígitos.
Lucro Presumido, Lucro Real e Lucro Arbitrado
Não são regimes tributários: são formas de apuração do imposto de renda federal, e na nota todas são CRT 3 Regime Normal. A API aberta não recebe nem devolve essa informação; a Consulta de CNPJ, os endpoints de empresa e o cadastro automático não têm campo para ela. Na emissão ela só afeta a alíquota de PIS / COFINS no CST 01, e a plataforma a chama de regime de PIS/COFINS:
| Regime de PIS/COFINS | Para | PIS | COFINS |
|---|---|---|---|
| Cumulativo | Lucro Presumido, Lucro Arbitrado | 0,65 % | 3,00 % |
| Não cumulativo | Lucro Real | 1,65 % | 7,60 % |
O regime de PIS/COFINS é configurado no console em «Dados tributários»: Lucro Presumido (cumulativo) ou Lucro Real (não cumulativo); para Lucro Arbitrado escolha o cumulativo. Uma empresa CRT 3 cadastrada pela API começa sem regime de PIS/COFINS. A NFS-e também usa o regime de PIS/COFINS, com regras próprias (veja NFS-e); abaixo, só NF-e e NFC-e.
Na emissão de NF-e e NFC-e (inclusive a emissão offline) de uma empresa CRT 3, a alíquota de PIS e COFINS no CST 01 segue esta tabela:
| Na requisição ou na classe de imposto referenciada | Empresa com regime de PIS/COFINS | Empresa sem regime de PIS/COFINS |
|---|---|---|
Com aliquota | Deve ser a alíquota legal acima; senão recusa 10005008 | Usa o valor enviado |
Sem aliquota | A plataforma preenche a alíquota legal | Recusa 10005007 |
Ao salvar uma classe de imposto vale a mesma conferência: com regime de PIS/COFINS configurado, uma linha CST 01 com aliquota diferente da legal devolve 10005008. Fora do CST 01 a plataforma não preenche alíquota pelo regime; em empresas CRT 1, 2 e 4 também não.
Habilitando DC-e
O DC-e (modelo 99) é habilitado pelo bloco emissaoDCe:
"emissaoDCe": {"ambienteProducao": {"tipoEmitente": "Marketplace","sequencialDCe": 1,"serieDCe": "1","siteMarketplace": "https://loja.exemplo.com.br"}}
tipoEmitenteéMarketplace(uma plataforma emitindo em nome de vendedores não contribuintes / pessoas físicas) ouOwnIssuer(uma empresa emitindo para si mesma).Carrierpode ser cadastrado, mas a emissão é rejeitada com10019013.siteMarketplaceé obrigatório paraMarketplace.- Uma empresa cadastrada sem
emissaoDCenão fica habilitada para DC-e: o cadastro é aceito, a resposta trazdceHabilitado=falsee a emissão devolve10019012. Confira esse campo logo após cadastrar. - Para habilitar DC-e depois, reenvie o payload de cadastro com
ide o blocoemissaoDCe. A série do modelo 99 só avança:sequencialDCepode elevar o próximo número, mas nunca reduzi-lo (40010001001), e trocarserieDCeenquanto a série antiga continua habilitada é recusado (40010001001, passe pela operação).
Habilitando NFS-e
A NFS-e é habilitada pelo bloco emissaoNFSe. Só com ele a empresa passa a emitir NFS-e e ganha a sequência de numeração. Aqui ficam apenas os dados que não mudam de uma nota para outra: código de serviço, CNAE, NBS, alíquota de ISS, retenção e IBS/CBS acompanham o serviço vendido e vão no bloco servico de cada emissão.
"emissaoNFSe": {"serieDps": "1","sequencialDps": 1,"regimeApuracaoSn": 1,"regimeEspecialTributacao": 0}
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
serieDps | string(1-5 dígitos) | Não | Série do DPS / RPS usada na emissão. Toda nota usa este valor; a emissão não aceita série própria. Sem este campo, 1 |
sequencialDps | integer | Não | Número da próxima nota a emitir, a partir de 1. Ao migrar de outro emissor, envie o maior número já usado mais um para a numeração continuar de onde parou. Sem este campo, 1. Uma vez criada a sequência, a atualização não a altera |
regimeApuracaoSn | integer | Obrigatório para ME/EPP | Como o Simples Nacional apura o imposto: 1 federal e municipal pelo SN / 2 federal pelo SN e municipal fixo / 3 federal pelo SN e municipal normal. A adesão ao Simples vem de optanteSimplesNacional / mei no nível superior. Enviar em empresa fora do Simples é rejeitado |
regimeEspecialTributacao | integer | Não | Se há tratamento tributário especial: 0 nenhum / 1 ato cooperado / 2 estimativa / 3 microempresa municipal / 4 notarial e registral / 5 profissional autônomo / 6 sociedade de profissionais. Sem este campo, 0 |
- A resposta do cadastro passa a trazer
nfseHabilitado:{ "empresaId": "…", "dceHabilitado": false, "nfseHabilitado": true }. Sem o bloco éfalsee a emissão devolve10018005. - Na atualização (corpo com
id) enviar o bloco substitui o perfil inteiro: opcionais omitidos voltam ao padrão; sem o bloco o perfil não muda enfseHabilitadoreflete o estado atual. Forçar o padrão municipal é ação da operação, não passa por este bloco. - Regras estruturais rejeitadas já na aceitação (400
10001001): ME/EPP semregimeApuracaoSn, empresa fora do Simples comregimeApuracaoSn. - Uma empresa só de NFS-e pode omitir
emissaoNFeProduto(nenhuma série do modelo 55 é criada) e não precisa deinscricaoEstadual. - A inscrição municipal (CCM) de São Paulo vem do
inscricaoMunicipaldo nível superior e não se repete neste bloco.
Códigos de erro relacionados
| codigo | HTTP | Cenário | Ação |
|---|---|---|---|
10003002 | 400 | CNPJ já cadastrado | A empresa existe: use o empresaId original ou atualize com id |
10003000 | 404 | empresaId não existe ou não pertence a esta aplicação | Verifique o empresaId |
10003006 | 400 | Dados de cadastro sem a IE | Informe inscricaoEstadual |
10003010 / 10003011 / 10003012 | 400 | CNPJ do certificado divergente / expirado / idêntico ao atual | Use o certificado correto |
10003035 | 400 | Base64 inválido ou certificado acima de 1MB (forma JSON) | Corrija a codificação ou o arquivo |
10003008 | 400 | Senha do certificado não confere | Verifique a senha |
10003004 | 400 | Cadastro: cidade / estado não resolvem para um código IBGE | Verifique a UF e o nome da cidade |
10004004 | 400 | Empresa não apta a emitir (ainda não aprovada ou certificado não pronto) | Aguarde a aprovação / vincule o certificado |
10004030 | 400 | ambienteEmissao diferente do ambiente atual da empresa | Submeta no ambiente da empresa ou peça à operação para trocá-lo |
10001001 | 400 | Falha de validação de campos, ou erro de contrato de cadastro / atualização (os três blocos de configuração ausentes, atualização alterando cnpj / município, redução do cursor da série DC-e, troca de série, regras estruturais de emissaoNFSe não atendidas) | Corrija conforme mensagem |
A lista completa está em Códigos de erro.
