TF Fiscal
Documentação

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.

EtapaEndpointObservações
1 Registrar empresaPOST /openapi/v2/empresasDevolve empresaId, dceHabilitado e nfseHabilitado; um corpo com id atualiza uma empresa existente
2 Vincular certificadoPOST /openapi/v1/empresas/{empresaId}/certificadoDigitalCertificado A1 (.pfx / .p12) e sua senha; multipart ou JSON + Base64
3 Registrar webhookPOST /openapi/v1/webhooksUma URL de callback por aplicação, compartilhada por todos os tipos de documento
4 Acompanhar a análiseGET /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 vezPOST /openapi/v2/empresas/cadastro-automaticoSó 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

  1. 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 o empresaId original ou envie uma atualização com id.
  2. 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 devolve 10003008. Um envio bem-sucedido substitui o certificado anterior.
  3. 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 10004004 para NF-e (10019004 para DC-e, 10017004 para CT-e). Acompanhe a aprovação em Listar empresas ou Consultar empresa: status Ativa significa aprovada e, com Rejeitada, o motivo vem em motivoStatus.
  4. Ambiente: toda empresa tem um ambiente atual, homologação Homologacao ou produção Producao. 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 (ambienteEmissao para NF-e e CT-e, ambiente para DC-e) deve ser igual ao ambiente atual da empresa; divergência devolve 10004030 (NF-e), 10017010 (CT-e) ou 10019010 (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 grava inscricaoEstadual, 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 documentoModeloSérie configurada porCampo de ambienteCódigo de não emissão
NF-e55emissaoNFeProduto.ambienteProducao (sequencialNFe / serieNFe) no cadastro ou na atualização com idambienteEmissao10004004
CT-e57Configurada 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 10017007ambienteEmissao10017004
DC-e99emissaoDCe.ambienteProducao (tipoEmitente, sequencialDCe / serieDCe, siteMarketplace) no cadastro ou em uma atualização com idambiente10019004
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çãoambienteEmissao10018004
  • emissaoNFeProduto, emissaoDCe e emissaoNFSe sã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 400 10001001.
  • 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 id e emissaoNFeProduto: a série é criada se não existir; se existir, o próximo número passa a ser sequencialNFe, 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.

CRTNome oficialQuem éoptanteSimplesNacional / mei na consulta da empresa
1Simples NacionalMicroempresa ou empresa de pequeno porte (ME / EPP) do Simples Nacionaltrue / false
2Simples Nacional – excesso de sublimite de receita brutaOptante do Simples Nacional com receita acima do sublimite estadual e municipaltrue / false
3Regime NormalEmpresa fora do Simples Nacionalfalse / false
4Simples Nacional - Microempreendedor individual - MEIMicroempreendedor individualtrue / 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

meioptanteSimplesNacionalCRT gravado
falsefalse3 Regime Normal
falsetrue1 Simples Nacional
truetrue4 MEI
truefalse4 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 id nã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:

  1. No cadastro, envie como Simples Nacional: optanteSimplesNacional=true e mei=false; a plataforma grava CRT 1.
  2. No console, em «Dados tributários», mude o regime para Simples Nacional (excesso de sublimite), o CRT 2.
  3. Depois disso a consulta da empresa devolve true / false, e reenviar true / false numa atualização com id nã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/COFINSParaPISCOFINS
CumulativoLucro Presumido, Lucro Arbitrado0,65 %3,00 %
Não cumulativoLucro Real1,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 referenciadaEmpresa com regime de PIS/COFINSEmpresa sem regime de PIS/COFINS
Com aliquotaDeve ser a alíquota legal acima; senão recusa 10005008Usa o valor enviado
Sem aliquotaA plataforma preenche a alíquota legalRecusa 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:

json
"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) ou OwnIssuer (uma empresa emitindo para si mesma). Carrier pode ser cadastrado, mas a emissão é rejeitada com 10019013. siteMarketplace é obrigatório para Marketplace.
  • Uma empresa cadastrada sem emissaoDCe não fica habilitada para DC-e: o cadastro é aceito, a resposta traz dceHabilitado=false e a emissão devolve 10019012. Confira esse campo logo após cadastrar.
  • Para habilitar DC-e depois, reenvie o payload de cadastro com id e o bloco emissaoDCe. A série do modelo 99 só avança: sequencialDCe pode elevar o próximo número, mas nunca reduzi-lo (400 10001001), e trocar serieDCe enquanto a série antiga continua habilitada é recusado (400 10001001, 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.

json
"emissaoNFSe": {
"serieDps": "1",
"sequencialDps": 1,
"regimeApuracaoSn": 1,
"regimeEspecialTributacao": 0
}
CampoTipoObrigatórioDescrição
serieDpsstring(1-5 dígitos)NãoSé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
sequencialDpsintegerNãoNú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
regimeApuracaoSnintegerObrigatório para ME/EPPComo 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
regimeEspecialTributacaointegerNãoSe 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 é false e a emissão devolve 10018005.
  • 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 e nfseHabilitado reflete 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 sem regimeApuracaoSn, empresa fora do Simples com regimeApuracaoSn.
  • Uma empresa só de NFS-e pode omitir emissaoNFeProduto (nenhuma série do modelo 55 é criada) e não precisa de inscricaoEstadual.
  • A inscrição municipal (CCM) de São Paulo vem do inscricaoMunicipal do nível superior e não se repete neste bloco.

Códigos de erro relacionados

codigoHTTPCenárioAção
10003002400CNPJ já cadastradoA empresa existe: use o empresaId original ou atualize com id
10003000404empresaId não existe ou não pertence a esta aplicaçãoVerifique o empresaId
10003006400Dados de cadastro sem a IEInforme inscricaoEstadual
10003010 / 10003011 / 10003012400CNPJ do certificado divergente / expirado / idêntico ao atualUse o certificado correto
10003035400Base64 inválido ou certificado acima de 1MB (forma JSON)Corrija a codificação ou o arquivo
10003008400Senha do certificado não confereVerifique a senha
10003004400Cadastro: cidade / estado não resolvem para um código IBGEVerifique a UF e o nome da cidade
10004004400Empresa não apta a emitir (ainda não aprovada ou certificado não pronto)Aguarde a aprovação / vincule o certificado
10004030400ambienteEmissao diferente do ambiente atual da empresaSubmeta no ambiente da empresa ou peça à operação para trocá-lo
10001001400Falha 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.