NF-e abstract models

Este módulo es la base para la emisión de la Nota Fiscal Electrónica (NF-e modelo 55 y NFC-e modelo 65) en Odoo, proporcionando una estructura de datos completa y fiel al layout oficial 4.0 de SEFAZ.

Es importante entender que este módulo actúa como una biblioteca de modelos abstractos (mixins) y no realiza la emisión de la NF-e por sí solo. Su finalidad es ser la base para un módulo de implementación, como el l10n_br_nfe, que es responsable de mapear estos modelos en los documentos fiscales de Odoo (l10n_br_fiscal.document) y comunicarse con los web services de SEFAZ. Esta arquitectura, que separa la estructura de datos de la lógica de emisión, es la misma utilizada con éxito en los otros documentos fiscales electrónicos de la localización brasileña.

Estructura y Principales Conceptos de la NF-e

El módulo l10n_br_nfe_spec mapea con precisión la compleja estructura jerárquica de la NF-e. Los conceptos más importantes implementados son:

• Identificación (ide): El encabezado de la nota, que contiene información como modelo, serie, número, fechas, finalidad y tipo de operación.
• Emisor y Destinatario (emit, dest): Modelos detallados para los datos registrales completos del emisor y del receptor de la mercancía.
• Ítems de la Nota (det): El corazón de la NF-e, un grupo repetible para cada producto o servicio, que contiene descripción, NCM, CFOP, cantidades y valores.
• Impuestos (imposto): Dentro de cada ítem, hay una estructura compleja para el detalle de todos los tributos incidentes (ICMS, IPI, PIS, COFINS, etc.).
• Totales (total): Contiene el grupo ICMSTot con la consolidación de todas las bases de cálculo y valores de impuestos de la nota.
• Transporte (transp): Modelos para informar la modalidad del flete, los datos de la transportadora, del vehículo y de los volúmenes transportados.
• Pago (pag): Estructura para detallar las formas de pago (detPag), incluyendo información de tarjetas, PIX y boletos.

Generación de Código Automatizada

La principal característica de este módulo es que el 100% de sus modelos de datos Odoo se generan automáticamente a partir de los esquemas XSD oficiales, publicados por el Portal da NF-e. Esta generación mediante xsdata-odoo garantiza la máxima fidelidad a los layouts fiscales y agilidad en la actualización a nuevas versiones.

Aunque los esquemas XSD oficiales de la NF-e se publican y mantienen en el Portal da SEFAZ, la arquitectura de este proyecto se apoya en la biblioteca nfelib para la tarea de serialización de los datos en XML. Para facilitar el proceso de desarrollo y garantizar la consistencia, la propia nfelib almacena en su repositorio una copia actualizada de estos esquemas oficiales.

Por lo tanto, la práctica recomendada para (re)generar los modelos de este módulo es utilizar un clon local del repositorio de nfelib como fuente para los archivos de esquema (.xsd), dirigiendo el comando de xsdata-odoo al directorio correspondiente.

Links:

• GitHub - akretion/xsdata-odoo: Odoo abstract model generator from xsd schemas using xsdata
• GitHub - akretion/nfelib

El comando utilizado para generar los modelos de la versión 4.0 de la NF-e fue:

Prefijo de los campos y versión

Con más de 800 campos fiscales solo en la NF-e, con una media docena de documentos fiscales complejos, con 3000 módulos OCA, existiría un riesgo real de conflicto con los nombres de campos provenientes de los esquemas. Además, tenemos varias versiones de la NFe, la 3.1, la 4.0 etc...

En esto se decidió que cada campo tiene un prefijo compuesto del nombre del schema y de algunos dígitos de la versión del esquema. En el caso nfe40_. La elección de 2 dígitos permite que una actualización menor del esquema use los mismos campos (y datos en la base de datos entonces) y que un simple update Odoo (--update=...) consiga resolver la migración. Mientras que para un cambio mayor como de 3.1 a 4.0, se asumiría usar nuevos campos y nuevas tablas (para los objetos no Odoo) y que la lib nfelib trabajaría con los campos de la versión mayor del documento fiscal considerado.

El Tratamiento Específico de los Impuestos ICMS e ICMSSN

Un desafío particular en la generación de los modelos de la NF-e es la forma en que el ICMS está estructurado en el XSD oficial. El esquema define un grupo de tags para cada CST de ICMS (ej: ICMS00, ICMS10, ICMS40, etc.), muchos de los cuales contienen campos con nombres idénticos (como vBC, pICMS, vICMS).

Si todos estos grupos se generaran e inyectaran en el mismo modelo Odoo, ocurrirían colisiones de nombres de campos. Para resolver esto, el comando de generación utiliza el parámetro XSDATA_SKIP para ignorar explícitamente esas clases de impuesto individuales.

Este enfoque es el ideal, pues la localización brasileña de Odoo, a través del módulo l10n_br_fiscal, ya posee un sistema robusto y genérico para cálculo y representación de impuestos. Por lo tanto, el mapeo de los campos de impuestos al XML es una tarea que exige una lógica más elaborada, siendo delegada al módulo de implementación (l10n_br_nfe), que es el lugar apropiado para tales reglas de negocio.