TF Fiscal
Documentação

Classes de imposto

Classes de imposto: guarde os impostos de item da NF-e / NFC-e em linhas por cenário sob um código e envie só o código em cada linha da nota; tipo da classe, cenários, ordem de escolha da linha, erro sem linha, CFOP vindo da classe e sobrescrita, sobrescrita por grupo, regras ao salvar, mudança de regime e situação, versões e idempotência, códigos de erro.

Visão geral

Uma classe de imposto é um conjunto de impostos de item guardado na empresa emitente, por exemplo "Revenda de mercadorias - SP". Em vez de uma única configuração, cada grupo da classe é uma lista de linhas, uma por cenário: venda dentro do estado para empresa, venda para outro estado a pessoa física… Na emissão a plataforma escolhe, em cada grupo, a linha que serve para o cenário, o tipo de cliente e o comprador da nota.

PassoEndpointObservação
1 CriarPOST .../classes-impostoA plataforma gera o código e o devolve na resposta; escolha o tipo NFe ou NFCe; cada linha validada conforme o regime da empresa
2 Referenciar na emissãoEmissão de NF-e · Emissão de NFC-eEnvie esse código em classeImposto na linha; cfop e impostos podem ser omitidos; no Assistente Fiscal e no SDK embarcado, referenciar classe de imposto exige conexão, veja Classe de imposto e conexão
ManterListar · Consultar · Atualizar · ExcluirA listagem filtra por tipo e situacao; a atualização substitui a classe inteira

Todos os caminhos ficam em /openapi/v2/empresas/{empresaId}/, com a mesma autenticação dos demais endpoints, veja Autenticação.

O código da classe é gerado pela plataforma: TF e 10 dígitos, os 9 primeiros aleatórios e o último dígito verificador, por exemplo TF4440123455. É único em toda a plataforma e nunca reutilizado, nem depois de excluído. Os corpos da criação e da substituição inteira não levam codigo; enviado, dá 10005208. Consulta, substituição e exclusão localizam a classe pelo código no caminho. O aplicativo precisa assinar os escopos «Gestão de classes de imposto», «Detalhe e atualização da classe de imposto» e «Exclusão de classe de imposto»; sem eles a resposta é 403.

Tipo da classe

Cada classe recebe o tipo na criação e ele não muda depois (10005216). A emissão só aceita o seu tipo: a NF-e só referencia classe NFe e a NFC-e só classe NFCe, senão 10005215.

RegraNFeNFCe
Grupos permitidosicms, ipi, pis, cofins, ibsCbs; sem issqnicms, issqn, pis, cofins, ibsCbs; sem ipi
Cenários permitidosOs seteSó SaidaDentroEstado e Padrao
Campos das linhasTodos os campos do grupo de mesmo nome da emissão de NF-eSó os campos que a emissão de NFC-e tem: linha de ICMS sem substituicaoTributaria, difal, partilha, percentualCreditoSimples, diferimento etc.; PIS / COFINS só com situacaoTributaria e aliquota
Quando violaissqn dá 10005218ipi dá 10005218, cenário fora dá 10005219, campo não suportado dá 10005217 com o caminho

Varejo e atacado costumam ter tributação diferente; se a mesma operação emite os dois documentos, crie uma classe de cada tipo.

Grupos e linhas

GrupoCampos de cada linhaQuantidade de linhas
icmsDimensões do cenário + cfop + campos de itens[].impostos.icms da emissão de NF-eCom issqn, pelo menos 1 linha
issqnDimensões do cenário + cfop + todos os campos de impostos.issqn da emissão de NFC-e; só em NFCeCom icms, pelo menos 1 linha
pis / cofinsDimensões do cenário + campos do grupo de mesmo nome da emissãoPelo menos 1 linha cada
ipiDimensões do cenário + campos do grupo ipi da emissão de NF-e; só em NFeOpcional
ibsCbsDimensões do cenário + campos do grupo de mesmo nome da emissãoOpcional

As dimensões do cenário são três campos:

  • cenario: cenário, obrigatório, valores na tabela abaixo.
  • tipoPessoa: tipo de cliente, Fisica pessoa física, Juridica pessoa jurídica, Estrangeiro comprador no exterior; omitido, vale para qualquer tipo.
  • naoContribuinte: comprador não contribuinte, true só para comprador que não é contribuinte do ICMS, false só para contribuinte ou isento de inscrição; omitido, vale para qualquer comprador.

A combinação das três não pode se repetir no grupo (10005211); assim, uma nota casa por completo com no máximo uma linha de cada grupo. Cada grupo tem no máximo 50 linhas.

O tipoPessoa da linha e o cliente.tipoPessoa da emissão de NF-e são campos diferentes: o da emissão continua F / J e descreve o comprador; o da linha usa Fisica / Juridica / Estrangeiro e diz a que cliente a linha se aplica, comparado na emissão com o tipo deduzido do CPF, do CNPJ ou do comprador no exterior.

CRT, opção pelo Simples, ambiente e série vêm sempre do cadastro da empresa; a classe não tem esses campos. CEST e a origem origem são da linha da nota e continuam em itens[].

Cenários

cenarioSignificadoQuando a nota está neste cenárioTipos de cliente que casamPrimeiro dígito do cfop
SaidaDentroEstadoSaída dentro do estadoNota de saída, comprador no mesmo estado da empresa; a NFC-e usa sempre este cenárioFisica, Juridica5
SaidaForaEstadoSaída para outro estadoNota de saída, comprador em outro estadoFisica, Juridica6
SaidaExteriorExportaçãoNota de saída, comprador no exteriorEstrangeiro7
EntradaDentroEstadoEntrada dentro do estadoNota de devolução, contraparte no mesmo estadoFisica, Juridica1
EntradaForaEstadoEntrada de outro estadoNota de devolução, contraparte em outro estadoFisica, Juridica2
EntradaExteriorEntrada do exteriorNota de devolução, contraparte no exteriorEstrangeiro3
PadraoGeralQualquer nota; só usado quando nenhuma linha do cenário serve. Não vale para o ICMSQualquerLivre

Primeiro dígito do cfop diferente do cenário: 10005212. O cfop da linha de ISSQN é sempre 5933, inclusive na Padrao, e a linha de ICMS não pode usar 5933; senão 10005214. Para grupos iguais em todos os cenários, como PIS e COFINS, basta uma linha Padrao.

Como a linha é escolhida na emissão

A plataforma deduz três valores da nota:

DimensãoNa NF-eNa NFC-e
CenárioDevolução é entrada, o resto é saída; comprador no mesmo estado da empresa é dentro do estado, em outro estado é fora do estado, comprador no exterior (cliente.idEstrangeiro, endereco.uf igual a EX) é exteriorSempre SaidaDentroEstado
Tipo de clienteComprador com CPF é Fisica, com CNPJ é Juridica, no exterior é EstrangeiroIgual; sem comprador identificado, Fisica
Não contribuintetrue quando o indicador de contribuinte do comprador é NaoContribuinte, inclusive o deduzido pela plataformaSempre true

Depois, em cada grupo, vale a primeira linha que casar nesta ordem:

OrdemLinha que casa
1Mesmo cenário, tipoPessoa e naoContribuinte preenchidos e iguais aos da nota
2Mesmo cenário, tipoPessoa igual, naoContribuinte omitido
3Mesmo cenário, tipoPessoa omitido, naoContribuinte igual
4Mesmo cenário, os dois omitidos
5Linhas Padrao, na mesma ordem de 1 a 4; o ICMS não tem este passo

Uma dimensão preenchida e diferente da nota nunca casa. Por exemplo, uma linha com "tipoPessoa": "Juridica" não é escolhida numa venda a pessoa física, mesmo que seja a única linha dentro do estado.

Quando nenhuma linha serve

GrupoSem linha
ICMS (ISSQN na linha de serviço), PIS, COFINSEmissão recusada com 10005209; a mensagem diz a classe, o grupo, o cenário, o tipo de cliente e se o comprador é não contribuinte
IPI, IBS/CBSA linha da nota fica sem o grupo

Para resolver, acrescente uma linha à classe ou envie o grupo direto na requisição.

CFOP vindo da classe

Sem cfop na linha da nota, vale o cfop da linha de ICMS escolhida; quando a linha escolhida é de ISSQN, vale o seu 5933. Com cfop na requisição, vale o da requisição. Assim o mesmo produto sai dentro ou fora do estado com a linha da nota idêntica, e o CFOP 5102 ou 6102 vem do cenário.

Envio direto e sobrescrita por grupo

O grupo enviado em impostos na linha da nota é usado inteiro, e a classe não escolhe linha para ele; os grupos não enviados seguem a escolha na classe. Os campos de um grupo não se misturam: se a linha de ICMS escolhida é CST 20 com redução de base e a requisição troca o ICMS por CST 00, o resultado é o CST 00 da requisição, sem sobra da redução.

json
{
"codigo": "SKU-1",
"classeImposto": "TF4440123455",
"cfop": "6102",
"impostos": { "icms": { "situacaoTributaria": "00", "aliquota": 12 } }
}

No exemplo o ICMS é o 00 / 12 % da requisição; PIS, COFINS e IBS/CBS vêm das linhas da classe. Com icms (ou issqn) na requisição não há linha de onde tirar o CFOP, então o cfop tem de vir na requisição, senão 10001002.

ICMS e ISSQN andam juntos, e cada linha da nota usa só um deles:

SituaçãoUsa
impostos da requisição traz icms ou issqnO grupo da requisição; nenhuma linha de ICMS ou ISSQN da classe
Requisição com cfop 5933 (linha de serviço da NFC-e)Linha de ISSQN da classe
Requisição com outro cfopLinha de ICMS da classe
Requisição sem cfopSe o grupo icms da classe tem linhas, escolhe só entre elas, e sem linha que sirva dá 10005209; só com o grupo icms vazio usa a linha de ISSQN. A NF-e só tem ICMS

Ordem de prioridade: requisição > classe de imposto > cadastro da empresa > tabela da plataforma (só CRT 3) > recusa apontando o campo. Linha de ICMS sem aliquota e sem FCP usa a tabela da plataforma. O percentual de tributos percentualCargaTributaria não fica na classe: só vale enviado em impostos na requisição; sem ele, a plataforma usa a tabela do IBPT.

Configuração por estado, desoneração e crédito presumido

Além dos campos da emissão (inclusive motivoDesoneracao, motivoDesoneracaoSt, deduzDesonerado, codigoBeneficioFiscalReducaoBase e creditosPresumidos), a linha de ICMS aceita configuração por estado:

CampoEstado consideradoNa emissão
icms[].beneficiosFiscaisPorEstadoEstado do emitenteCom linha do estado, substitui o codigoBeneficioFiscal da linha; sem ela, vale o da linha
icms[].creditosPresumidosPorEstadoEstado do emitenteCom linhas do estado (até 4), substituem os creditosPresumidos da linha; sem elas, valem os da linha
icmsPorEstado (raiz da classe, só NFe)Estado do compradorCom linha do estado, aliquota, substituicaoTributaria.aliquota e substituicaoTributaria.mva substituem os da linha de ICMS escolhida; o que não for informado segue a linha e, sem ela, a tabela da plataforma

Os códigos de benefício e de crédito presumido vêm da tabela do estado do emitente, por isso valem pelo estado do emitente; alíquota de ST e MVA acompanham o destino, por isso valem pelo estado do comprador. A alíquota por estado só se aplica às linhas com CST 00, 10, 20, 30, 51, 70, 90 e CSOSN 201, 202, 203, 900; a ST por estado, às linhas com CST 10, 30, 70, 90 e CSOSN 201, 202, 203, 900. Quando a nota envia o grupo icms, ele vale inteiro e nada disto se aplica.

Valor desonerado, valor de ICMS-ST desonerado e valor do crédito presumido são valores por nota e não existem na classe (10005231); omitidos, a plataforma calcula conforme o CST, veja a emissão de NF-e. Quando a plataforma não consegue calcular o valor, a classe é recusada ao salvar com 10005235: o motivo de desoneração do ICMS-ST motivoDesoneracaoSt exige a redução de base da ST substituicaoTributaria.percentualReducaoBase, e a plataforma usa o ICMS-ST sem a redução menos o devido; o motivo de desoneração no CST 90 exige percentualReducaoBase. Desoneração que não vem de redução de base só pode ir na requisição de emissão, com motivo e valor, sem classe.

json
{
"tipo": "NFe",
"icms": [
{ "cenario": "SaidaDentroEstado", "cfop": "5102", "situacaoTributaria": "20", "aliquota": 18,
"percentualReducaoBase": 33.33, "motivoDesoneracao": 9,
"beneficiosFiscaisPorEstado": [ { "uf": "SP", "codigo": "SP800001" } ],
"creditosPresumidosPorEstado": [ { "uf": "SP", "codigo": "SP000001", "percentual": 2.5 } ] },
{ "cenario": "SaidaForaEstado", "cfop": "6102", "situacaoTributaria": "10", "aliquota": 12,
"substituicaoTributaria": { "mva": 40, "aliquota": 18 } }
],
"icmsPorEstado": [
{ "uf": "RJ", "aliquota": 12, "substituicaoTributaria": { "aliquota": 20, "mva": 55 } }
],
"pis": [ { "cenario": "Padrao", "situacaoTributaria": "01", "aliquota": 1.65 } ],
"cofins": [ { "cenario": "Padrao", "situacaoTributaria": "01", "aliquota": 7.6 } ]
}

Linha de CST com ST precisa de mva e aliquota da ST; se icmsPorEstado informa esses valores, a linha pode omiti-los, e a emissão só recusa (10004043) quando o estado do comprador não tem configuração e a linha também não.

Regras ao salvar

  • Validação pelo regime da empresa: empresa com CRT 1 / 4 só usa CSOSN de 3 dígitos, com CRT 2 / 3 só CST de 2 dígitos; senão 10004046. CSOSN 101 / 201 sem percentualCreditoSimples na linha nem no cadastro da empresa: 10004043. Empresa CRT 3 com PIS / COFINS 01 ou 02 sem aliquota e sem alíquota legal pelo regime de PIS/COFINS: 10005008.
  • Códigos só de contribuinte: linha de ICMS com naoContribuinte = true ou tipoPessoa = Fisica explícitos não usa CST / CSOSN 10, 30, 70, 101, 201, 202, 203 nem percentualCreditoSimples; senão 10004047, a mesma regra da emissão.
  • CFOP e grupo: linha de ISSQN só com 5933, linha de ICMS nunca com 5933 (10005214).
  • Substituição inteira: a atualização recebe a classe inteira, sem codigo e com o mesmo tipo; grupo ou linha que não vier deixa de existir.
  • Campo desconhecido recusado: qualquer campo inexistente, em qualquer nível, dá 10005210 com o caminho, como icms[0].aliquotaX. Vale só para os endpoints de classe; a emissão não muda.
  • Tipos estritos: números como número JSON ("aliquota": 18, nunca "18") e booleanos como true / false; enviados como texto dão 10005213 com o caminho.
  • Números como enviados: 18.00 gravado volta 18.00 na consulta.
  • Limite de linhas: até 50 linhas por grupo; acima disso, 10001001.

Cada linha passa também por todas as validações do grupo de mesmo nome da emissão; validações e erros ao salvar estão em Criar classe de imposto. Todos os valores de cada campo e os campos que cada código exige ao salvar estão na seção de enums e em "Formatos dos demais campos" dessa página.

Mudança de regime e situação

A resposta e os itens da listagem trazem situacao:

situacaoSignificadoNa emissão
CompativelPassa na validação com o regime atual da empresaNormal
IncompativelComRegimeO regime da empresa mudou e a classe não passa mais; motivos em motivosIncompatibilidade10005220

Quando muda o CRT, o regime de PIS/COFINS ou o percentualCreditoSimples do cadastro, a plataforma revalida todas as classes da empresa com as mesmas regras do salvamento e marca ou desmarca cada uma sozinha. A marcação não muda versao. Na passagem de compatível para incompatível chega o webhook tax_class.incompatible (exige assinatura explícita, veja Webhooks); uma classe que já estava incompatível só atualiza os motivos, sem novo envio.

Cada item de motivosIncompatibilidade:

CampoDescrição
grupoGrupo com problema, como icms; ausente quando não dá para apontar
linhaLinha no grupo, a partir de 0; ausente quando não dá para apontar
campoCampo da linha, como situacaoTributaria; ausente quando não dá para apontar
codigoErroCódigo que o salvamento devolveria, como 10004046
crtCRT da empresa na revalidação
regimeTributarioRegime de PIS/COFINS na revalidação: 1 Simples Nacional, 2 Lucro Presumido, 3 Lucro Real; ausente se não cadastrado
mensagemExplicação no idioma da requisição, o mesmo texto do erro ao salvar

Para resolver, substitua a classe inteira pelo regime novo (atualizar classe); passando na validação, ela volta a Compativel e versao soma 1. A listagem com situacao=IncompativelComRegime mostra todas as classes a corrigir.

Exemplo

Empresa de SP no regime normal (CRT 3): quatro linhas de ICMS, dentro / fora do estado × pessoa física / jurídica, e uma linha Padrao para PIS, COFINS e IBS/CBS.

json
{
"tipo": "NFe",
"descricao": "Revenda de mercadorias - SP",
"icms": [
{ "cenario": "SaidaDentroEstado", "tipoPessoa": "Juridica", "cfop": "5102", "situacaoTributaria": "00", "aliquota": 18 },
{ "cenario": "SaidaDentroEstado", "tipoPessoa": "Fisica", "cfop": "5102", "situacaoTributaria": "00", "aliquota": 18 },
{ "cenario": "SaidaForaEstado", "tipoPessoa": "Juridica", "cfop": "6102", "situacaoTributaria": "00", "aliquota": 12 },
{ "cenario": "SaidaForaEstado", "tipoPessoa": "Fisica", "cfop": "6108", "situacaoTributaria": "00", "aliquota": 12 }
],
"pis": [{ "cenario": "Padrao", "situacaoTributaria": "01", "aliquota": 1.65 }],
"cofins": [{ "cenario": "Padrao", "situacaoTributaria": "01", "aliquota": 7.6 }],
"ibsCbs": [{ "cenario": "Padrao", "situacaoTributaria": "000", "classificacaoTributaria": "000001" }]
}

Uma NF-e para uma empresa do RJ, com a linha enviando só o código devolvido na criação:

json
{ "codigo": "000068", "descricao": "Pendrive 16GB", "ncm": "85235190", "quantidade": 1, "unidadeMedida": "UN", "valorUnitario": 28.47, "classeImposto": "TF4440123455" }

O cenário deduzido é SaidaForaEstado com Juridica, e o ICMS casa com a terceira linha: CFOP 6102, CST 00, alíquota 12 %; PIS, COFINS e IBS/CBS vêm das linhas Padrao.

Empresa do Simples (CRT 1 / 4) usa CSOSN; o exemplo está em Criar classe de imposto, seção "Exemplo: empresa do Simples Nacional".

Classe para a NFC-e

A NFC-e só referencia classes NFCe. As linhas dessas classes já são validadas ao salvar com as regras da emissão de NFC-e (veja "Tipo da classe"), então a emissão não as recusa por campo não suportado. A NFC-e escolhe sempre com SaidaDentroEstado e comprador não contribuinte: as linhas de ICMS fora de Padrao usam SaidaDentroEstado, e uma linha com "naoContribuinte": false nunca casa.

Versões e notas anteriores

  • A criação é a versão 1; depois, qualquer alteração soma 1, inclusive só de descricao; uma substituição com conteúdo idêntico não muda a versão.
  • O resultado expandido fica gravado na nota no aceite, e a consulta mostra classeImposto e versaoClasseImposto na linha. Linhas sem classe não trazem esses dois campos.
  • Alterar ou excluir a classe depois não muda as notas já aceitas.
  • No reenvio idêntico com o mesmo id, a comparação usa a requisição original, antes de expandir a classe; se casa, volta a tarefa original sem ler a classe, mesmo que ela tenha mudado de versão, sido excluída ou ficado sem linha que sirva. Vale para NF-e e NFC-e. Corpo diferente continua recusado pelas regras de sempre.

Códigos de erro

CódigoHTTPSignificado
10005200404Classe de imposto não encontrada ou excluída
10005202400A classe referenciada na emissão não existe, foi excluída ou é de outra empresa
10005203400Código de tributação não suportado
10005204400Classificação não pertence ao CST
10005205400Classe referenciada com campo que a NFC-e não suporta
10005206409Classe alterada ao mesmo tempo
10005208400codigo no corpo; o código é gerado pela plataforma
10005209400Grupo que a linha precisa sem linha para esta nota
10005210400Campo desconhecido no corpo
10005211400Combinação de cenário repetida no grupo
10005212400Primeiro dígito do CFOP diferente do cenário
10005213400Número ou booleano enviado como texto
10005214400CFOP fora do grupo: ISSQN só com 5933, ICMS nunca com 5933
10005215400Tipo da classe referenciada diferente do documento
10005216400Tipo da classe não pode ser alterado
10005217400Classe NFCe com campo que a NFC-e não suporta
10005218400Grupo que o tipo da classe não admite
10005219400Classe NFCe com cenário fora de SaidaDentroEstado ou Padrao
10005220400Classe referenciada incompatível com o regime atual da empresa
10005230400Motivo de desoneração fora dos valores do CST
10005231400Valor por nota na classe
10005232400icmsPorEstado com valor que nenhuma linha de ICMS usa
10005233400Estado repetido na configuração por estado
10005234400Mais de 4 créditos presumidos do mesmo estado
10005235400Valor desonerado que não dá para calcular; envie-o na emissão

Códigos gerais: 10001001 falha de validação de campos, 10001002 falta cfop com icms ou issqn enviado direto, 10004043 falta campo que o código exige, 10004044 campo que não se aplica ao código, 10004046 código incompatível com o regime da empresa, 10004047 código só de contribuinte em linha de não contribuinte, 10005008 falta alíquota legal de PIS/COFINS, 10003000 empresa não encontrada.