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.
| Passo | Endpoint | Observação |
|---|---|---|
| 1 Criar | POST .../classes-imposto | A 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ão | Emissão de NF-e · Emissão de NFC-e | Envie 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 |
| Manter | Listar · Consultar · Atualizar · Excluir | A 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.
| Regra | NFe | NFCe |
|---|---|---|
| Grupos permitidos | icms, ipi, pis, cofins, ibsCbs; sem issqn | icms, issqn, pis, cofins, ibsCbs; sem ipi |
| Cenários permitidos | Os sete | Só SaidaDentroEstado e Padrao |
| Campos das linhas | Todos os campos do grupo de mesmo nome da emissão de NF-e | Só 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 viola | issqn dá 10005218 | ipi 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
| Grupo | Campos de cada linha | Quantidade de linhas |
|---|---|---|
icms | Dimensões do cenário + cfop + campos de itens[].impostos.icms da emissão de NF-e | Com issqn, pelo menos 1 linha |
issqn | Dimensões do cenário + cfop + todos os campos de impostos.issqn da emissão de NFC-e; só em NFCe | Com icms, pelo menos 1 linha |
pis / cofins | Dimensões do cenário + campos do grupo de mesmo nome da emissão | Pelo menos 1 linha cada |
ipi | Dimensões do cenário + campos do grupo ipi da emissão de NF-e; só em NFe | Opcional |
ibsCbs | Dimensões do cenário + campos do grupo de mesmo nome da emissão | Opcional |
As dimensões do cenário são três campos:
cenario: cenário, obrigatório, valores na tabela abaixo.tipoPessoa: tipo de cliente,Fisicapessoa física,Juridicapessoa jurídica,Estrangeirocomprador no exterior; omitido, vale para qualquer tipo.naoContribuinte: comprador não contribuinte,truesó para comprador que não é contribuinte do ICMS,falsesó 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
cenario | Significado | Quando a nota está neste cenário | Tipos de cliente que casam | Primeiro dígito do cfop |
|---|---|---|---|---|
SaidaDentroEstado | Saída dentro do estado | Nota de saída, comprador no mesmo estado da empresa; a NFC-e usa sempre este cenário | Fisica, Juridica | 5 |
SaidaForaEstado | Saída para outro estado | Nota de saída, comprador em outro estado | Fisica, Juridica | 6 |
SaidaExterior | Exportação | Nota de saída, comprador no exterior | Estrangeiro | 7 |
EntradaDentroEstado | Entrada dentro do estado | Nota de devolução, contraparte no mesmo estado | Fisica, Juridica | 1 |
EntradaForaEstado | Entrada de outro estado | Nota de devolução, contraparte em outro estado | Fisica, Juridica | 2 |
EntradaExterior | Entrada do exterior | Nota de devolução, contraparte no exterior | Estrangeiro | 3 |
Padrao | Geral | Qualquer nota; só usado quando nenhuma linha do cenário serve. Não vale para o ICMS | Qualquer | Livre |
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ão | Na NF-e | Na NFC-e |
|---|---|---|
| Cenário | Devoluçã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) é exterior | Sempre SaidaDentroEstado |
| Tipo de cliente | Comprador com CPF é Fisica, com CNPJ é Juridica, no exterior é Estrangeiro | Igual; sem comprador identificado, Fisica |
| Não contribuinte | true quando o indicador de contribuinte do comprador é NaoContribuinte, inclusive o deduzido pela plataforma | Sempre true |
Depois, em cada grupo, vale a primeira linha que casar nesta ordem:
| Ordem | Linha que casa |
|---|---|
| 1 | Mesmo cenário, tipoPessoa e naoContribuinte preenchidos e iguais aos da nota |
| 2 | Mesmo cenário, tipoPessoa igual, naoContribuinte omitido |
| 3 | Mesmo cenário, tipoPessoa omitido, naoContribuinte igual |
| 4 | Mesmo cenário, os dois omitidos |
| 5 | Linhas 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
| Grupo | Sem linha |
|---|---|
| ICMS (ISSQN na linha de serviço), PIS, COFINS | Emissã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/CBS | A 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.
{"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ção | Usa |
|---|---|
impostos da requisição traz icms ou issqn | O 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 cfop | Linha de ICMS da classe |
Requisição sem cfop | Se 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:
| Campo | Estado considerado | Na emissão |
|---|---|---|
icms[].beneficiosFiscaisPorEstado | Estado do emitente | Com linha do estado, substitui o codigoBeneficioFiscal da linha; sem ela, vale o da linha |
icms[].creditosPresumidosPorEstado | Estado do emitente | Com linhas do estado (até 4), substituem os creditosPresumidos da linha; sem elas, valem os da linha |
icmsPorEstado (raiz da classe, só NFe) | Estado do comprador | Com 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.
{"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 sempercentualCreditoSimplesna linha nem no cadastro da empresa:10004043. Empresa CRT 3 com PIS / COFINS01ou02semaliquotae sem alíquota legal pelo regime de PIS/COFINS:10005008. - Códigos só de contribuinte: linha de ICMS com
naoContribuinte=trueoutipoPessoa=Fisicaexplícitos não usa CST / CSOSN 10, 30, 70, 101, 201, 202, 203 nempercentualCreditoSimples; senão10004047, a mesma regra da emissão. - CFOP e grupo: linha de ISSQN só com
5933, linha de ICMS nunca com5933(10005214). - Substituição inteira: a atualização recebe a classe inteira, sem
codigoe com o mesmotipo; grupo ou linha que não vier deixa de existir. - Campo desconhecido recusado: qualquer campo inexistente, em qualquer nível, dá
10005210com o caminho, comoicms[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 comotrue/false; enviados como texto dão10005213com o caminho. - Números como enviados:
18.00gravado volta18.00na 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:
situacao | Significado | Na emissão |
|---|---|---|
Compativel | Passa na validação com o regime atual da empresa | Normal |
IncompativelComRegime | O regime da empresa mudou e a classe não passa mais; motivos em motivosIncompatibilidade | 10005220 |
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:
| Campo | Descrição |
|---|---|
grupo | Grupo com problema, como icms; ausente quando não dá para apontar |
linha | Linha no grupo, a partir de 0; ausente quando não dá para apontar |
campo | Campo da linha, como situacaoTributaria; ausente quando não dá para apontar |
codigoErro | Código que o salvamento devolveria, como 10004046 |
crt | CRT da empresa na revalidação |
regimeTributario | Regime de PIS/COFINS na revalidação: 1 Simples Nacional, 2 Lucro Presumido, 3 Lucro Real; ausente se não cadastrado |
mensagem | Explicaçã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.
{"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:
{ "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
classeImpostoeversaoClasseImpostona 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ódigo | HTTP | Significado |
|---|---|---|
| 10005200 | 404 | Classe de imposto não encontrada ou excluída |
| 10005202 | 400 | A classe referenciada na emissão não existe, foi excluída ou é de outra empresa |
| 10005203 | 400 | Código de tributação não suportado |
| 10005204 | 400 | Classificação não pertence ao CST |
| 10005205 | 400 | Classe referenciada com campo que a NFC-e não suporta |
| 10005206 | 409 | Classe alterada ao mesmo tempo |
| 10005208 | 400 | codigo no corpo; o código é gerado pela plataforma |
| 10005209 | 400 | Grupo que a linha precisa sem linha para esta nota |
| 10005210 | 400 | Campo desconhecido no corpo |
| 10005211 | 400 | Combinação de cenário repetida no grupo |
| 10005212 | 400 | Primeiro dígito do CFOP diferente do cenário |
| 10005213 | 400 | Número ou booleano enviado como texto |
| 10005214 | 400 | CFOP fora do grupo: ISSQN só com 5933, ICMS nunca com 5933 |
| 10005215 | 400 | Tipo da classe referenciada diferente do documento |
| 10005216 | 400 | Tipo da classe não pode ser alterado |
| 10005217 | 400 | Classe NFCe com campo que a NFC-e não suporta |
| 10005218 | 400 | Grupo que o tipo da classe não admite |
| 10005219 | 400 | Classe NFCe com cenário fora de SaidaDentroEstado ou Padrao |
| 10005220 | 400 | Classe referenciada incompatível com o regime atual da empresa |
| 10005230 | 400 | Motivo de desoneração fora dos valores do CST |
| 10005231 | 400 | Valor por nota na classe |
| 10005232 | 400 | icmsPorEstado com valor que nenhuma linha de ICMS usa |
| 10005233 | 400 | Estado repetido na configuração por estado |
| 10005234 | 400 | Mais de 4 créditos presumidos do mesmo estado |
| 10005235 | 400 | Valor 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.
