TF Fiscal
Documentación

Clases de impuesto

Clases de impuesto: guarde los impuestos de ítem de la NF-e / NFC-e en filas por escenario con un código y envíe solo el código en cada línea de la factura; tipo de la clase, escenarios, orden de elección de la fila, error sin fila, CFOP desde la clase y su sobrescritura, sobrescritura por grupo, reglas al guardar, cambio de régimen y situación, versiones e idempotencia, códigos de error.

Visión general

Una clase de impuesto es un conjunto de impuestos de ítem guardado en la empresa emisora, por ejemplo "Reventa de mercaderías - SP". En lugar de una única configuración, cada grupo de la clase es una lista de filas, una por escenario: venta dentro del estado a empresa, venta a otro estado a persona física… En la emisión la plataforma elige, en cada grupo, la fila que sirve para el escenario, el tipo de cliente y el comprador de la factura.

PasoEndpointObservación
1 CrearPOST .../classes-impostoLa plataforma genera el código y lo devuelve en la respuesta; elija el tipo NFe o NFCe; cada fila validada según el régimen de la empresa
2 Referenciar en la emisiónEmisión de NF-e · Emisión de NFC-eEnvíe ese código en classeImposto en la línea; en el Asistente Fiscal y el SDK embebido, referenciar una clase de impuesto requiere conexión, vea Clases de impuesto y conexión; cfop e impostos pueden omitirse
MantenerListar · Consultar · Actualizar · EliminarEl listado filtra por tipo y situacao; la actualización sustituye la clase entera

Todas las rutas están bajo /openapi/v2/empresas/{empresaId}/, con la misma autenticación de los demás endpoints, vea Autenticación.

El código de la clase lo genera la plataforma: TF y 10 dígitos, los 9 primeros aleatorios y el último dígito verificador, por ejemplo TF4440123455. Es único en toda la plataforma y nunca se reutiliza, ni siquiera tras eliminarse. Los cuerpos de la creación y de la sustitución entera no llevan codigo; enviado, da 10005208. Consulta, sustitución y eliminación ubican la clase por el código de la ruta. La aplicación debe suscribir los alcances «Gestión de clases de impuesto», «Detalle y actualización de la clase de impuesto» y «Eliminación de clase de impuesto»; sin ellos la respuesta es 403.

Tipo de la clase

Cada clase recibe su tipo al crearse y no cambia después (10005216). La emisión solo acepta su tipo: la NF-e solo referencia clases NFe y la NFC-e solo clases NFCe, si no 10005215.

ReglaNFeNFCe
Grupos permitidosicms, ipi, pis, cofins, ibsCbs; sin issqnicms, issqn, pis, cofins, ibsCbs; sin ipi
Escenarios permitidosLos sieteSolo SaidaDentroEstado y Padrao
Campos de las filasTodos los campos del grupo del mismo nombre de la emisión de NF-eSolo los campos que la emisión de NFC-e tiene: fila de ICMS sin substituicaoTributaria, difal, partilha, percentualCreditoSimples, diferimiento, etc.; PIS / COFINS solo con situacaoTributaria y aliquota
Al incumplirissqn da 10005218ipi da 10005218, escenario fuera da 10005219, campo no admitido da 10005217 con la ruta

Minorista y mayorista suelen tener tributación distinta; si la misma operación emite los dos documentos, cree una clase de cada tipo.

Grupos y filas

GrupoCampos de cada filaCantidad de filas
icmsDimensiones del escenario + cfop + campos de itens[].impostos.icms de la emisión de NF-eCon issqn, al menos 1 fila
issqnDimensiones del escenario + cfop + todos los campos de impostos.issqn de la emisión de NFC-e; solo en NFCeCon icms, al menos 1 fila
pis / cofinsDimensiones del escenario + campos del grupo del mismo nombre de la emisiónAl menos 1 fila cada uno
ipiDimensiones del escenario + campos del grupo ipi de la emisión de NF-e; solo en NFeOpcional
ibsCbsDimensiones del escenario + campos del grupo del mismo nombre de la emisiónOpcional

Las dimensiones del escenario son tres campos:

  • cenario: escenario, obligatorio, valores en la tabla de abajo.
  • tipoPessoa: tipo de cliente, Fisica persona física, Juridica persona jurídica, Estrangeiro comprador en el exterior; omitido, vale para cualquier tipo.
  • naoContribuinte: comprador no contribuyente, true solo para comprador que no es contribuyente del ICMS, false solo para contribuyente o exento de inscripción; omitido, vale para cualquier comprador.

La combinación de las tres no puede repetirse en el grupo (10005211); así, una factura coincide por completo con como máximo una fila de cada grupo. Cada grupo tiene como máximo 50 filas.

El tipoPessoa de la fila y el cliente.tipoPessoa de la emisión de NF-e son campos distintos: el de la emisión sigue F / J y describe al comprador; el de la fila usa Fisica / Juridica / Estrangeiro y dice a qué cliente se aplica la fila, comparado en la emisión con el tipo deducido del CPF, del CNPJ o del comprador en el exterior.

CRT, opción por el Simples, ambiente y serie vienen siempre del registro de la empresa; la clase no tiene esos campos. CEST y el origen origem son de la línea de la factura y siguen en itens[].

Escenarios

cenarioSignificadoCuándo la factura está en este escenarioTipos de cliente que coincidenPrimer dígito del cfop
SaidaDentroEstadoSalida dentro del estadoFactura de salida, comprador en el mismo estado de la empresa; la NFC-e usa siempre este escenarioFisica, Juridica5
SaidaForaEstadoSalida a otro estadoFactura de salida, comprador en otro estadoFisica, Juridica6
SaidaExteriorExportaciónFactura de salida, comprador en el exteriorEstrangeiro7
EntradaDentroEstadoEntrada dentro del estadoFactura de devolución, contraparte en el mismo estadoFisica, Juridica1
EntradaForaEstadoEntrada desde otro estadoFactura de devolución, contraparte en otro estadoFisica, Juridica2
EntradaExteriorEntrada desde el exteriorFactura de devolución, contraparte en el exteriorEstrangeiro3
PadraoGeneralCualquier factura; solo se usa cuando ninguna fila del escenario sirve. No vale para el ICMSCualquieraLibre

Primer dígito del cfop distinto del escenario: 10005212. El cfop de la fila de ISSQN es siempre 5933, incluso en la Padrao, y la fila de ICMS no puede usar 5933; si no, 10005214. Para grupos iguales en todos los escenarios, como PIS y COFINS, basta una fila Padrao.

Cómo se elige la fila en la emisión

La plataforma deduce tres valores de la factura:

DimensiónEn la NF-eEn la NFC-e
EscenarioLa devolución es entrada, el resto es salida; comprador en el mismo estado de la empresa es dentro del estado, en otro estado es fuera del estado, comprador en el exterior (cliente.idEstrangeiro, endereco.uf igual a EX) es exteriorSiempre SaidaDentroEstado
Tipo de clienteComprador con CPF es Fisica, con CNPJ es Juridica, en el exterior es EstrangeiroIgual; sin comprador identificado, Fisica
No contribuyentetrue cuando el indicador de contribuyente del comprador es NaoContribuinte, incluido el deducido por la plataformaSiempre true

Después, en cada grupo, vale la primera fila que coincida en este orden:

OrdenFila que coincide
1Mismo escenario, tipoPessoa y naoContribuinte informados e iguales a los de la factura
2Mismo escenario, tipoPessoa igual, naoContribuinte omitido
3Mismo escenario, tipoPessoa omitido, naoContribuinte igual
4Mismo escenario, ambos omitidos
5Filas Padrao, en el mismo orden de 1 a 4; el ICMS no tiene este paso

Una dimensión informada y distinta de la factura nunca coincide. Por ejemplo, una fila con "tipoPessoa": "Juridica" no se elige en una venta a persona física, aunque sea la única fila dentro del estado.

Cuando ninguna fila sirve

GrupoSin fila
ICMS (ISSQN en la línea de servicio), PIS, COFINSEmisión rechazada con 10005209; el mensaje indica la clase, el grupo, el escenario, el tipo de cliente y si el comprador es no contribuyente
IPI, IBS/CBSLa línea de la factura queda sin el grupo

Para resolverlo, agregue una fila a la clase o envíe el grupo directo en la solicitud.

CFOP desde la clase

Sin cfop en la línea de la factura, vale el cfop de la fila de ICMS elegida; cuando la fila elegida es de ISSQN, vale su 5933. Con cfop en la solicitud, vale el de la solicitud. Así el mismo producto sale dentro o fuera del estado con la línea de la factura idéntica, y el CFOP 5102 o 6102 viene del escenario.

Envío directo y sobrescritura por grupo

El grupo enviado en impostos en la línea de la factura se usa entero, y la clase no elige fila para él; los grupos no enviados siguen la elección en la clase. Los campos de un grupo no se mezclan: si la fila de ICMS elegida es CST 20 con reducción de base y la solicitud cambia el ICMS por CST 00, el resultado es el CST 00 de la solicitud, sin restos de la reducción.

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

En el ejemplo el ICMS es el 00 / 12 % de la solicitud; PIS, COFINS e IBS/CBS vienen de las filas de la clase. Con icms (o issqn) en la solicitud no hay fila de donde tomar el CFOP, así que el cfop tiene que venir en la solicitud, si no 10001002.

ICMS e ISSQN van juntos, y cada línea de la factura usa solo uno de ellos:

SituaciónUsa
impostos de la solicitud trae icms o issqnEl grupo de la solicitud; ninguna fila de ICMS o ISSQN de la clase
Solicitud con cfop 5933 (línea de servicio de la NFC-e)Fila de ISSQN de la clase
Solicitud con otro cfopFila de ICMS de la clase
Solicitud sin cfopSi el grupo icms de la clase tiene filas, elige solo entre ellas, y sin fila que sirva da 10005209; solo con el grupo icms vacío usa la fila de ISSQN. La NF-e solo tiene ICMS

Orden de prioridad: solicitud > clase de impuesto > registro de la empresa > tabla de la plataforma (solo CRT 3) > rechazo señalando el campo. Una fila de ICMS sin aliquota ni FCP usa la tabla de la plataforma. El porcentaje de tributos percentualCargaTributaria no está en la clase: solo vale enviado en impostos en la solicitud; sin él, la plataforma usa la tabla del IBPT.

Configuración por estado, desgravación y crédito presunto

Además de los campos de la emisión (incluidos motivoDesoneracao, motivoDesoneracaoSt, deduzDesonerado, codigoBeneficioFiscalReducaoBase y creditosPresumidos), la fila de ICMS acepta configuración por estado:

CampoEstado consideradoEn la emisión
icms[].beneficiosFiscaisPorEstadoEstado del emisorCon fila del estado, sustituye el codigoBeneficioFiscal de la fila; sin ella, vale el de la fila
icms[].creditosPresumidosPorEstadoEstado del emisorCon filas del estado (hasta 4), sustituyen los creditosPresumidos de la fila; sin ellas, valen los de la fila
icmsPorEstado (raíz de la clase, solo NFe)Estado del compradorCon fila del estado, aliquota, substituicaoTributaria.aliquota y substituicaoTributaria.mva sustituyen los de la fila de ICMS elegida; lo no informado sigue la fila y, sin ella, la tabla de la plataforma

Los códigos de beneficio y de crédito presunto vienen de la tabla del estado del emisor, por eso valen por el estado del emisor; la alícuota de ST y la MVA acompañan al destino, por eso valen por el estado del comprador. La alícuota por estado solo se aplica a las filas con CST 00, 10, 20, 30, 51, 70, 90 y CSOSN 201, 202, 203, 900; la ST por estado, a las filas con CST 10, 30, 70, 90 y CSOSN 201, 202, 203, 900. Cuando la factura envía el grupo icms, vale entero y nada de esto se aplica.

Importe desgravado, importe de ICMS-ST desgravado e importe del crédito presunto son importes por factura y no existen en la clase (10005231); omitidos, la plataforma los calcula según el CST, vea la emisión de NF-e. Cuando la plataforma no puede calcular el importe, la clase se rechaza al guardar con 10005235: el motivo de desgravación del ICMS-ST motivoDesoneracaoSt exige la reducción de base de la ST substituicaoTributaria.percentualReducaoBase, y la plataforma toma el ICMS-ST sin la reducción menos el debido; el motivo de desgravación en el CST 90 exige percentualReducaoBase. La desgravación que no proviene de una reducción de base solo puede ir en la solicitud de emisión, con motivo e importe, sin clase.

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 } ]
}

Una fila de CST con ST necesita mva y aliquota de la ST; si icmsPorEstado informa esos valores, la fila puede omitirlos, y la emisión solo rechaza (10004043) cuando el estado del comprador no tiene configuración y la fila tampoco.

Reglas al guardar

  • Validación por el régimen de la empresa: una empresa con CRT 1 / 4 solo usa CSOSN de 3 dígitos, con CRT 2 / 3 solo CST de 2 dígitos; si no, 10004046. CSOSN 101 / 201 sin percentualCreditoSimples en la fila ni en el registro de la empresa: 10004043. Empresa CRT 3 con PIS / COFINS 01 o 02 sin aliquota y sin alícuota legal por su régimen de PIS/COFINS: 10005008.
  • Códigos solo de contribuyente: una fila de ICMS con naoContribuinte = true o tipoPessoa = Fisica explícitos no usa CST / CSOSN 10, 30, 70, 101, 201, 202, 203 ni percentualCreditoSimples; si no, 10004047, la misma regla de la emisión.
  • CFOP y grupo: fila de ISSQN solo con 5933, fila de ICMS nunca con 5933 (10005214).
  • Sustitución entera: la actualización recibe la clase entera, sin codigo y con el mismo tipo; el grupo o la fila que no venga deja de existir.
  • Campo desconocido rechazado: cualquier campo inexistente, en cualquier nivel, da 10005210 con la ruta, como icms[0].aliquotaX. Vale solo para los endpoints de clase; la emisión no cambia.
  • Tipos estrictos: números como número JSON ("aliquota": 18, nunca "18") y booleanos como true / false; enviados como texto dan 10005213 con la ruta.
  • Números como se envían: 18.00 guardado vuelve 18.00 en la consulta.
  • Límite de filas: hasta 50 filas por grupo; por encima, 10001001.

Cada fila pasa también por todas las validaciones del grupo del mismo nombre de la emisión; validaciones y errores al guardar están en Crear clase de impuesto. Todos los valores de cada campo y los campos que cada código exige al guardar están en la sección de enums y en "Formatos de los demás campos" de esa página.

Cambio de régimen y situación

La respuesta y los ítems del listado traen situacao:

situacaoSignificadoEn la emisión
CompativelPasa la validación con el régimen actual de la empresaNormal
IncompativelComRegimeEl régimen de la empresa cambió y la clase ya no pasa; motivos en motivosIncompatibilidade10005220

Cuando cambia el CRT, el régimen de PIS/COFINS o el percentualCreditoSimples del registro, la plataforma revalida todas las clases de la empresa con las mismas reglas del guardado y marca o desmarca cada una sola. La marcación no cambia versao. En el paso de compatible a incompatible llega el webhook tax_class.incompatible (requiere suscripción explícita, vea Webhooks); una clase que ya estaba incompatible solo actualiza los motivos, sin nuevo envío.

Cada ítem de motivosIncompatibilidade:

CampoDescripción
grupoGrupo con el problema, como icms; ausente cuando no se puede señalar
linhaFila en el grupo, desde 0; ausente cuando no se puede señalar
campoCampo de la fila, como situacaoTributaria; ausente cuando no se puede señalar
codigoErroCódigo que devolvería el guardado, como 10004046
crtCRT de la empresa en la revalidación
regimeTributarioRégimen de PIS/COFINS en la revalidación: 1 Simples Nacional, 2 Lucro Presumido, 3 Lucro Real; ausente si no está registrado
mensagemExplicación en el idioma de la solicitud, el mismo texto del error al guardar

Para resolverlo, sustituya la clase entera por el régimen nuevo (actualizar clase); al pasar la validación vuelve a Compativel y versao suma 1. El listado con situacao=IncompativelComRegime muestra todas las clases a corregir.

Ejemplo

Empresa de SP en el régimen normal (CRT 3): cuatro filas de ICMS, dentro / fuera del estado × persona física / jurídica, y una fila 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" }]
}

Una NF-e para una empresa de RJ, con la línea enviando solo el código devuelto en la creación:

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

El escenario deducido es SaidaForaEstado con Juridica, y el ICMS coincide con la tercera fila: CFOP 6102, CST 00, alícuota 12 %; PIS, COFINS e IBS/CBS vienen de las filas Padrao.

Una empresa del Simples (CRT 1 / 4) usa CSOSN; el ejemplo está en Crear clase de impuesto, sección "Ejemplo: empresa del Simples Nacional".

Clase para la NFC-e

La NFC-e solo referencia clases NFCe. Sus filas ya se validan al guardar con las reglas de la emisión de NFC-e (vea "Tipo de la clase"), así que la emisión no las rechaza por campo no admitido. La NFC-e elige siempre con SaidaDentroEstado y comprador no contribuyente: las filas de ICMS fuera de Padrao usan SaidaDentroEstado, y una fila con "naoContribuinte": false nunca coincide.

Versiones y facturas anteriores

  • La creación es la versión 1; después, cualquier cambio suma 1, incluso solo de descricao; una sustitución con contenido idéntico no cambia la versión.
  • El resultado expandido queda grabado en la factura al aceptarla, y la consulta muestra classeImposto y versaoClasseImposto en la línea. Las líneas sin clase no traen estos dos campos.
  • Modificar o eliminar la clase después no cambia las facturas ya aceptadas.
  • En el reenvío idéntico con el mismo id, la comparación usa la solicitud original, antes de expandir la clase; si coincide, vuelve la tarea original sin leer la clase, aunque haya cambiado de versión, se haya eliminado o haya quedado sin fila que sirva. Vale para NF-e y NFC-e. Un cuerpo distinto sigue rechazándose con las reglas de siempre.

Códigos de error

CódigoHTTPSignificado
10005200404Clase de impuesto no encontrada o eliminada
10005202400La clase referenciada en la emisión no existe, fue eliminada o es de otra empresa
10005203400Código de tributación no admitido
10005204400La clasificación no pertenece al CST
10005205400Clase referenciada con un campo que la NFC-e no admite
10005206409Clase modificada al mismo tiempo
10005208400codigo en el cuerpo; el código lo genera la plataforma
10005209400Grupo que la línea necesita sin fila para esta factura
10005210400Campo desconocido en el cuerpo
10005211400Combinación de escenario repetida en el grupo
10005212400Primer dígito del CFOP distinto del escenario
10005213400Número o booleano enviado como texto
10005214400CFOP fuera del grupo: ISSQN solo con 5933, ICMS nunca con 5933
10005215400Tipo de la clase referenciada distinto del documento
10005216400El tipo de la clase no se puede cambiar
10005217400Clase NFCe con un campo que la NFC-e no admite
10005218400Grupo que el tipo de la clase no admite
10005219400Clase NFCe con escenario fuera de SaidaDentroEstado o Padrao
10005220400Clase referenciada incompatible con el régimen actual de la empresa
10005230400Motivo de desgravación fuera de los valores del CST
10005231400Importe por factura en la clase
10005232400icmsPorEstado con un valor que ninguna fila de ICMS usa
10005233400Estado repetido en la configuración por estado
10005234400Más de 4 créditos presuntos del mismo estado
10005235400Importe desgravado que no se puede calcular; envíelo en la emisión

Códigos generales: 10001001 falló la validación de campos, 10001002 falta cfop con icms o issqn enviado directo, 10004043 falta un campo que el código exige, 10004044 campo que no se aplica al código, 10004046 código incompatible con el régimen de la empresa, 10004047 código solo de contribuyente en fila de no contribuyente, 10005008 falta alícuota legal de PIS/COFINS, 10003000 empresa no encontrada.