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.
| Paso | Endpoint | Observación |
|---|---|---|
| 1 Crear | POST .../classes-imposto | La 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ón | Emisión de NF-e · Emisión de NFC-e | Enví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 |
| Mantener | Listar · Consultar · Actualizar · Eliminar | El 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.
| Regla | NFe | NFCe |
|---|---|---|
| Grupos permitidos | icms, ipi, pis, cofins, ibsCbs; sin issqn | icms, issqn, pis, cofins, ibsCbs; sin ipi |
| Escenarios permitidos | Los siete | Solo SaidaDentroEstado y Padrao |
| Campos de las filas | Todos los campos del grupo del mismo nombre de la emisión de NF-e | Solo 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 incumplir | issqn da 10005218 | ipi 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
| Grupo | Campos de cada fila | Cantidad de filas |
|---|---|---|
icms | Dimensiones del escenario + cfop + campos de itens[].impostos.icms de la emisión de NF-e | Con issqn, al menos 1 fila |
issqn | Dimensiones del escenario + cfop + todos los campos de impostos.issqn de la emisión de NFC-e; solo en NFCe | Con icms, al menos 1 fila |
pis / cofins | Dimensiones del escenario + campos del grupo del mismo nombre de la emisión | Al menos 1 fila cada uno |
ipi | Dimensiones del escenario + campos del grupo ipi de la emisión de NF-e; solo en NFe | Opcional |
ibsCbs | Dimensiones del escenario + campos del grupo del mismo nombre de la emisión | Opcional |
Las dimensiones del escenario son tres campos:
cenario: escenario, obligatorio, valores en la tabla de abajo.tipoPessoa: tipo de cliente,Fisicapersona física,Juridicapersona jurídica,Estrangeirocomprador en el exterior; omitido, vale para cualquier tipo.naoContribuinte: comprador no contribuyente,truesolo para comprador que no es contribuyente del ICMS,falsesolo 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
cenario | Significado | Cuándo la factura está en este escenario | Tipos de cliente que coinciden | Primer dígito del cfop |
|---|---|---|---|---|
SaidaDentroEstado | Salida dentro del estado | Factura de salida, comprador en el mismo estado de la empresa; la NFC-e usa siempre este escenario | Fisica, Juridica | 5 |
SaidaForaEstado | Salida a otro estado | Factura de salida, comprador en otro estado | Fisica, Juridica | 6 |
SaidaExterior | Exportación | Factura de salida, comprador en el exterior | Estrangeiro | 7 |
EntradaDentroEstado | Entrada dentro del estado | Factura de devolución, contraparte en el mismo estado | Fisica, Juridica | 1 |
EntradaForaEstado | Entrada desde otro estado | Factura de devolución, contraparte en otro estado | Fisica, Juridica | 2 |
EntradaExterior | Entrada desde el exterior | Factura de devolución, contraparte en el exterior | Estrangeiro | 3 |
Padrao | General | Cualquier factura; solo se usa cuando ninguna fila del escenario sirve. No vale para el ICMS | Cualquiera | Libre |
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ón | En la NF-e | En la NFC-e |
|---|---|---|
| Escenario | La 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 exterior | Siempre SaidaDentroEstado |
| Tipo de cliente | Comprador con CPF es Fisica, con CNPJ es Juridica, en el exterior es Estrangeiro | Igual; sin comprador identificado, Fisica |
| No contribuyente | true cuando el indicador de contribuyente del comprador es NaoContribuinte, incluido el deducido por la plataforma | Siempre true |
Después, en cada grupo, vale la primera fila que coincida en este orden:
| Orden | Fila que coincide |
|---|---|
| 1 | Mismo escenario, tipoPessoa y naoContribuinte informados e iguales a los de la factura |
| 2 | Mismo escenario, tipoPessoa igual, naoContribuinte omitido |
| 3 | Mismo escenario, tipoPessoa omitido, naoContribuinte igual |
| 4 | Mismo escenario, ambos omitidos |
| 5 | Filas 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
| Grupo | Sin fila |
|---|---|
| ICMS (ISSQN en la línea de servicio), PIS, COFINS | Emisió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/CBS | La 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.
{"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ón | Usa |
|---|---|
impostos de la solicitud trae icms o issqn | El 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 cfop | Fila de ICMS de la clase |
Solicitud sin cfop | Si 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:
| Campo | Estado considerado | En la emisión |
|---|---|---|
icms[].beneficiosFiscaisPorEstado | Estado del emisor | Con fila del estado, sustituye el codigoBeneficioFiscal de la fila; sin ella, vale el de la fila |
icms[].creditosPresumidosPorEstado | Estado del emisor | Con 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 comprador | Con 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.
{"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 sinpercentualCreditoSimplesen la fila ni en el registro de la empresa:10004043. Empresa CRT 3 con PIS / COFINS01o02sinaliquotay sin alícuota legal por su régimen de PIS/COFINS:10005008. - Códigos solo de contribuyente: una fila de ICMS con
naoContribuinte=trueotipoPessoa=Fisicaexplícitos no usa CST / CSOSN 10, 30, 70, 101, 201, 202, 203 nipercentualCreditoSimples; si no,10004047, la misma regla de la emisión. - CFOP y grupo: fila de ISSQN solo con
5933, fila de ICMS nunca con5933(10005214). - Sustitución entera: la actualización recibe la clase entera, sin
codigoy con el mismotipo; el grupo o la fila que no venga deja de existir. - Campo desconocido rechazado: cualquier campo inexistente, en cualquier nivel, da
10005210con la ruta, comoicms[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 comotrue/false; enviados como texto dan10005213con la ruta. - Números como se envían:
18.00guardado vuelve18.00en 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:
situacao | Significado | En la emisión |
|---|---|---|
Compativel | Pasa la validación con el régimen actual de la empresa | Normal |
IncompativelComRegime | El régimen de la empresa cambió y la clase ya no pasa; motivos en motivosIncompatibilidade | 10005220 |
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:
| Campo | Descripción |
|---|---|
grupo | Grupo con el problema, como icms; ausente cuando no se puede señalar |
linha | Fila en el grupo, desde 0; ausente cuando no se puede señalar |
campo | Campo de la fila, como situacaoTributaria; ausente cuando no se puede señalar |
codigoErro | Código que devolvería el guardado, como 10004046 |
crt | CRT de la empresa en la revalidación |
regimeTributario | Régimen de PIS/COFINS en la revalidación: 1 Simples Nacional, 2 Lucro Presumido, 3 Lucro Real; ausente si no está registrado |
mensagem | Explicació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.
{"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:
{ "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
classeImpostoyversaoClasseImpostoen 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ódigo | HTTP | Significado |
|---|---|---|
| 10005200 | 404 | Clase de impuesto no encontrada o eliminada |
| 10005202 | 400 | La clase referenciada en la emisión no existe, fue eliminada o es de otra empresa |
| 10005203 | 400 | Código de tributación no admitido |
| 10005204 | 400 | La clasificación no pertenece al CST |
| 10005205 | 400 | Clase referenciada con un campo que la NFC-e no admite |
| 10005206 | 409 | Clase modificada al mismo tiempo |
| 10005208 | 400 | codigo en el cuerpo; el código lo genera la plataforma |
| 10005209 | 400 | Grupo que la línea necesita sin fila para esta factura |
| 10005210 | 400 | Campo desconocido en el cuerpo |
| 10005211 | 400 | Combinación de escenario repetida en el grupo |
| 10005212 | 400 | Primer dígito del CFOP distinto del escenario |
| 10005213 | 400 | Número o booleano enviado como texto |
| 10005214 | 400 | CFOP fuera del grupo: ISSQN solo con 5933, ICMS nunca con 5933 |
| 10005215 | 400 | Tipo de la clase referenciada distinto del documento |
| 10005216 | 400 | El tipo de la clase no se puede cambiar |
| 10005217 | 400 | Clase NFCe con un campo que la NFC-e no admite |
| 10005218 | 400 | Grupo que el tipo de la clase no admite |
| 10005219 | 400 | Clase NFCe con escenario fuera de SaidaDentroEstado o Padrao |
| 10005220 | 400 | Clase referenciada incompatible con el régimen actual de la empresa |
| 10005230 | 400 | Motivo de desgravación fuera de los valores del CST |
| 10005231 | 400 | Importe por factura en la clase |
| 10005232 | 400 | icmsPorEstado con un valor que ninguna fila de ICMS usa |
| 10005233 | 400 | Estado repetido en la configuración por estado |
| 10005234 | 400 | Más de 4 créditos presuntos del mismo estado |
| 10005235 | 400 | Importe 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.
