Factur-X — Guía completa (PrestaShop 8 & 9)

Esta guía cubre la instalación, la configuración y el uso del módulo DataFirefly Factur-X (dffacturx) para PrestaShop 8 y 9. El módulo convierte sus pedidos en facturas electrónicas híbridas en formato Factur-X: un PDF/A-3b legible e imprimible que contiene, incrustados en su interior, los datos estructurados de la factura en formato XML CII (norma EN 16931).

Presentación

Una factura Factur-X es un único archivo que sirve para dos usos. Su cliente abre un PDF clásico que puede leer, imprimir y archivar. Su software contable, o la plataforma que procesa la factura, lee directamente el XML incrustado sin tener que interpretar la imagen. Ya no hay dos archivos que sincronizar, por lo que no existe riesgo de desajuste entre lo que se muestra y lo que se procesa.

El módulo cubre la generación de estos archivos: produce el XML, genera el PDF e incrusta uno dentro del otro con los metadatos esperados. La transmisión a través de una Plataforma Acreditada es una capa distinta, detallada en la sección sobre el alcance normativo.

Requisitos

• PrestaShop 8.0 a 9.x
• PHP 7.4 mínimo, 8.1 o superior recomendado
• TCPDF, incluido de origen en PrestaShop — sin instalación adicional
• Extensiones PHP: dom (construcción del XML), zlib (lectura de metadatos XMP comprimidos), zip (generación masiva)

Instalación

1. En el back-office, vaya a Módulos → Administrador de módulos → Subir un módulo.
2. Suba el archivo dffacturx.zip. También puede copiar la carpeta dffacturx directamente en el directorio modules/ de su tienda.
3. Ejecute la instalación. El módulo registra sus hooks y crea una pestaña Factur-X bajo el menú Pedidos.
4. Abra la configuración y rellene la identidad del vendedor antes de generar su primera factura.

Configuración

Identidad del vendedor

Es el paso obligatorio. Estos datos alimentan tanto el PDF visible como el XML estructurado. Sin ellos, el XML será rechazado por un validador.

• Razón social — precargada con el nombre de su tienda, a corregir si su denominación legal difiere.
• SIREN — 9 dígitos, sin espacios. Imprescindible: se transmite en el XML con el identificador de esquema adecuado.
• SIRET — 14 dígitos, opcional pero recomendado.
• Número de IVA intracomunitario — imprescindible si está sujeto (p. ej. FR12345678901).
• Forma jurídica y capital social — se muestran en las menciones legales al pie de la factura.
• Dirección, código postal, ciudad, país — el país se espera en formato ISO de dos letras (p. ej. FR).
• Contacto, teléfono, correo electrónico — se incluyen en el XML en los perfiles EN 16931 y superiores.

Perfil Factur-X

El perfil determina el nivel de detalle del XML y el identificador de especificación que se inscribe en él. El módulo lo ajusta automáticamente según su elección.

• EN 16931 — recomendado. Corresponde al núcleo completo de la norma europea, aceptado en todas partes.
• BASIC — XML más ligero, conserva el detalle de las líneas.
• EXTENDED — perfil extendido, para casos que requieran datos adicionales.
• MINIMUM y BASIC WL — perfiles sin detalle de líneas, reservados a usos específicos.

Opciones

• Descarga por el cliente — activa un enlace en el área de cuenta. El módulo verifica que el pedido pertenece al cliente conectado antes de servir el archivo.
• Generación automática — si indica un identificador de estado de pedido, se genera una factura y se guarda en la carpeta generated del módulo en cuanto un pedido alcanza ese estado. Los posibles errores se escriben en los registros de PrestaShop sin bloquear el cambio de estado.

Generar una factura

Desde la ficha del pedido

Abra un pedido en el back-office: aparece un panel Factur-X en la parte inferior de la página principal. Muestra el perfil activo y ofrece dos botones — Descargar PDF Factur-X para el archivo híbrido completo, y Descargar XML para el XML solo, útil durante las fases de prueba y validación.

Generación masiva

El menú Pedidos → Factur-X muestra la lista de sus pedidos con acceso directo al PDF y al XML en cada fila. Para procesar un lote, marque los pedidos correspondientes y elija la acción en bloque Descargar las Factur-X (ZIP): el módulo reúne todas las facturas en un archivo comprimido. Si un pedido falla, se omite y el error se registra — el archivo sigue siendo utilizable.

Lado cliente

Si la opción está activada, aparece un enlace Mis facturas Factur-X en el área de cuenta. El controlador front verifica que el cliente está conectado y que el pedido le pertenece; de lo contrario, redirige al historial de pedidos.

Qué contiene el archivo generado

El PDF producido es un PDF/A-3b generado por el TCPDF de PrestaShop. El módulo añade después, mediante actualización incremental, los elementos que lo convierten en una factura Factur-X:

• un objeto de archivo incrustado que contiene el XML, llamado factur-x.xml;
• una entrada en la matriz de archivos asociados del catálogo, con la relación Data;
• una entrada en el diccionario de archivos incrustados con nombre;
• metadatos XMP que describen el tipo de documento, el nombre del archivo, la versión y el nivel de conformidad, junto con el esquema de extensión PDF/A correspondiente.

La actualización incremental añade estos objetos al final del archivo sin modificar un solo byte del documento generado. Las fuentes, los flujos de contenido y el perfil de color producidos por TCPDF permanecen intactos, y el módulo no depende de ningún detalle interno de TCPDF, por tanto de ninguna versión concreta.

El XML es un CrossIndustryInvoice de UN/CEFACT. Contiene el contexto del documento con el identificador de especificación del perfil, la cabecera de la factura, las líneas cuando procede, el acuerdo comercial (vendedor y comprador), la entrega, y la liquidación con el desglose de IVA, los descuentos, los cargos y el resumen monetario.

Modelización contable

Los validadores Factur-X no comparan sus totales con los de PrestaShop: comprueban que el documento sea coherente consigo mismo. Por ello el módulo recalcula todos los importes a partir de las líneas y del desglose de IVA, para satisfacer las reglas de equilibrio de la norma.

• Líneas — el precio unitario neto se deduce del total de línea dividido por la cantidad. La unidad utilizada es el código de unidad genérico.
• Gastos de envío — modelados como cargo a nivel de documento, con su propio tipo de IVA.
• Descuentos — modelados como allowance a nivel de documento, repartidos proporcionalmente entre las distintas bases de IVA.
• Desglose de IVA — una ocurrencia por cada tipo encontrado, con base, importe y categoría.
• Categoría de IVA — categoría estándar si el tipo es superior a cero, categoría cero en caso contrario.
• Anticipo — el importe prepagado es cero y el importe a pagar equivale al total con IVA: la factura se emite y la totalidad sigue pendiente a efectos del documento.

Los casos particulares de IVA — exención, inversión del sujeto pasivo, entrega intracomunitaria — no se derivan automáticamente. Si su actividad los implica, valide algunas facturas representativas y adapte la categoría utilizada.

Validar antes de pasar a producción

Este paso no es opcional. Genere algunas facturas representativas de su actividad — un pedido simple, un pedido con descuento, un pedido con varios tipos de IVA — y compruébelas con:

• el validador de la FNFE-MPE, referencia francesa para Factur-X;
• Mustangproject, validador de código abierto para la conformidad EN 16931;
• veraPDF, para la conformidad del contenedor PDF/A-3.

El botón de descarga del XML solo está pensado para esta fase: le evita extraer manualmente el adjunto del PDF en cada intento.

Alcance normativo

La reforma francesa de la facturación electrónica sigue un calendario en dos tiempos. El 1 de septiembre de 2026, todas las empresas sujetas al IVA deben poder recibir facturas electrónicas, y las grandes empresas y las ETI deben emitirlas. El 1 de septiembre de 2027, la obligación de emisión se extiende a las pymes, microempresas y autónomos. La mayoría de los comercios PrestaShop deben por tanto recibir desde 2026 y emitir a partir de 2027.

Deben distinguirse tres funciones:

• Generar archivos Factur-X conformes — lo que hace este módulo. No se requiere ninguna certificación ni registro.
• Transmitir las facturas a través de una Plataforma Acreditada (antes PDP). El comerciante elige su plataforma y le entrega los archivos.
• Ser una Plataforma Acreditada — actividad sujeta a registro por el Estado, fuera del alcance del módulo.

Resolución de problemas

El validador rechaza el XML

Compruebe primero la identidad del vendedor, en particular el SIREN y el número de IVA: son las causas de rechazo más frecuentes. Compruebe después la dirección de facturación del cliente — un país o un código postal ausente también puede hacer fallar la validación.

Mensaje que indica que TCPDF no está disponible

El módulo utiliza la clase TCPDF proporcionada por PrestaShop y, en su defecto, intenta cargarla desde el directorio de herramientas. Si el error persiste, es que la biblioteca ha sido retirada de su instalación: restáurela desde un archivo de PrestaShop de la misma versión.

La acción en bloque ZIP no está disponible

La extensión PHP zip no está activada en el servidor. La descarga individual desde cada ficha de pedido sigue disponible sin ella.

La generación automática no produce nada

Compruebe que el identificador de estado de pedido está indicado en la configuración y que la carpeta generated del módulo tiene permisos de escritura. Los errores de generación se registran en los logs de PrestaShop con el prefijo Factur-X.

El PDF se abre pero el adjunto no aparece

No todos los lectores muestran el panel de adjuntos por defecto. Abra el panel dedicado de su lector de PDF, o utilice la descarga del XML solo para comprobar su contenido.

Arquitectura

El módulo sigue una organización clásica, con un autoloader PSR-4 manual cuya raíz de namespace DataFirefly/FacturX apunta a la carpeta src.

• src/Builder — definición de los perfiles y construcción del XML CII.
• src/Pdf — generación del PDF/A-3b e incrustación del XML.
• src/Service — extracción de los datos del pedido y orquestación.
• src/Install — instalación, pestaña de administración y hooks.
• controllers/admin y controllers/front — controladores de descarga de back-office y front-office.

La arquitectura se basa en ModuleAdminController y Smarty, idénticos entre PrestaShop 8 y 9, sin rama de código separada ni dependencia Symfony específica.

Changelog

1.0.0 — 4 de junio de 2026

• Generación de facturas híbridas Factur-X: PDF/A-3b con XML CII incrustado.
• Perfiles BASIC, EN 16931 y EXTENDED seleccionables.
• Construcción del XML CII conforme a UN/CEFACT con desglose de IVA por tipo.
• Incrustación autónoma del XML mediante actualización incremental del PDF.
• Metadatos XMP Factur-X y esquema de extensión PDF/A inyectados.
• Identidad del vendedor totalmente configurable.
• Descarga de PDF y XML desde la ficha del pedido, generación masiva en ZIP.
• Enlace de descarga en el área de cliente, activable.
• Generación automática opcional al cambio de estado del pedido.
• Compatible con PrestaShop 8.0 a 9.0 sin rama de código separada.