Factura — Referencia detallada

De un vistazo

El módulo Invoice tiene tres superficies independientes: incrustación, validación y ejecución de reglas Schematron. ZugferdEmbedder y PeppolEmbedder adjuntan el XML de factura suministrado por quien llama a un portador PDF/A-4f o PDF/A-3b y devuelven un resultado estructurado. InvoiceXmlValidator ejecuta una verificación estructural previa EN 16931 con severidad seleccionable COMPAT o STRICT. SchematronValidator ejecuta packs de reglas Schematron precompilados en proceso y analiza los hallazgos SVRL. NextPDF no genera el XML de factura; quien llama suministra y es dueño de la carga útil.

Disponibilidad y licencias

Esta capacidad se distribuye en NextPDF Enterprise (nextpdf/enterprise) y se activa con un sobre de licencia de nivel Enterprise. Un despliegue sin ese derecho no carga las clases de la capacidad. Comparar ediciones y obtener una licencia.

Matiz por nivel: la detección y validación de facturas electrónicas es la superficie de nivel Pro (módulo Pro Compliance). La incrustación de facturas híbridas, el perfil XRechnung CIUS y el motor Schematron en proceso son exclusivos de Enterprise. No hay ningún código de capacidad por característica más allá del límite del paquete nextpdf/enterprise.

Superficie pública de la API

composer require nextpdf/enterprise:^3

Símbolo	Parámetros	Comportamiento por defecto	Devuelve	Lanza o falla con	Notas
ZugferdEmbedder::basic()	PdfAManager, FileAttachment, string $xmlData	Incrusta XML CII de perfil BASIC: paso de XmlGuard, validación estructural, inyección del esquema XMP, adjunto	ZugferdEmbedResult	InvalidArgumentException, ZugferdEmbeddingException	Vía rápida; punto de partida recomendado
ZugferdEmbedder::minimum()	PdfAManager, FileAttachment, string $xmlData	El mismo flujo con el perfil MINIMUM	ZugferdEmbedResult	InvalidArgumentException, ZugferdEmbeddingException	Vía rápida
ZugferdEmbedder::create()	ZugferdProfile, string $xmlData	Entrada del builder; rechaza XML vacío	self	InvalidArgumentException	Se configura mediante withoutValidation(), withDescription()
ZugferdEmbedder::withAfRelationship() / PeppolEmbedder::withAfRelationship()	AFRelationship|string	Sustituye la relación /Alternative por defecto; regulado por el rulebook de archivos asociados	self	InvalidArgumentException	Schema, EncryptedPayload, FormData se rechazan para facturas
ZugferdEmbedder::embed()	PdfAManager, FileAttachment	Llamada terminal del builder: XmlGuard, validación opcional, comprobación del portador, XMP, adjunto	ZugferdEmbedResult	InvalidArgumentException, ZugferdEmbeddingException	El fallo de validación nombra el primer error
ZugferdProfile (enum)	—	Casos MINIMUM, BASIC_WL, BASIC, EN16931, EXTENDED, XRECHNUNG	—	—	XRECHNUNG adjunta xrechnung.xml; los perfiles CII adjuntan factur-x.xml
ZugferdXmpSchema::apply()	XmpMetadata, ZugferdProfile	Registra la descripción RDF de Factur-X y la entrada de esquema de extensión PDF/A	XmpMetadata	Ninguno	La invoca embed(); también se puede usar directamente
PeppolEmbedder::invoice() / ::creditNote()	PdfAManager, FileAttachment, string $ublXml	Incrusta XML UBL de factura o nota de crédito Peppol BIS 3.0	PeppolEmbedResult	InvalidArgumentException, PeppolEmbeddingException	Nombres de archivo por defecto invoice.xml / creditnote.xml
PeppolEmbedder::create()	string $ublXml, string $filename = 'invoice.xml'	Entrada del builder; rechaza XML o nombre de archivo vacíos	self	InvalidArgumentException	Se configura mediante withFilename(), withDescription(), withoutSanitization()
PeppolEmbedder::embed()	PdfAManager, FileAttachment	Paso de XmlGuard, comprobación del portador, control del rulebook, adjunto	PeppolEmbedResult	InvalidArgumentException, PeppolEmbeddingException	Nueva comprobación del rulebook según el portador en el momento del adjunto
InvoiceXmlValidator::validate()	string $xmlData, ZugferdProfile, ?InvoiceValidatorMode	Verificación estructural previa EN 16931; severidad COMPAT por defecto	InvoiceValidationResult	No lanza; los fallos se exponen como hallazgos de error	El modo se resuelve por argumento, luego por entorno, luego COMPAT
InvoiceXmlValidator::isCrossIndustryInvoice()	string $xmlData	Comprobación del elemento raíz y del espacio de nombres para cargas CII	bool	No lanza; devuelve false	Sonda de detección económica
InvoiceValidatorMode (enum)	—	COMPAT (por defecto) mantiene los hallazgos BT-24 como advertencia; STRICT los eleva a error	—	—	fromEnvironment() recurre a COMPAT ante valores sin definir o no reconocidos
InvoiceValidationResult / InvoiceValidationFinding	—	Agregados inmutables: isValid, getErrors(), getWarnings(); nivel, código y mensaje por hallazgo	—	—	InvoiceValidationResult::fail() envuelve un único error
SchematronValidator::validate()	string $xsltPath, string $xmlData	Ejecuta un XSLT Schematron precompilado; analiza el SVRL en hallazgos	SchematronResult	InvalidArgumentException ante un XSLT ausente o ilegible; los fallos del motor devuelven un resultado de error	El tiempo se captura en durationMs
SchematronValidator::runRules()	string $xslPath, string $xmlPayload	Adaptador entre niveles; asigna los hallazgos de error a objetos RuleViolation del contrato	list<RuleViolation>	Igual que validate()	Los hallazgos de nivel info se omiten
SchematronResult / SchematronFinding	—	Veredicto, hallazgos, duración; getFailedAssertions(), getSuccessfulReports()	—	—	SchematronResult::error() marca los fallos del motor como no válidos
SchematronCacheInterface	—	Contrato de caché con detección de manipulación: getVerified(), set(), computeKey()	—	—	Falla en modo cerrado ante discrepancia de digest
AtomicRenameSchematronCache	string $cacheDir, bool $atomicRename = true, LoggerInterface	Caché de archivos verificada con SHA-256 y escrituras con renombrado atómico	—	InvalidArgumentException, SchematronCacheException	El directorio debe existir o poder crearse, y ser escribible
VersionPinRegistry	array $pins, ?string $sourcePath	Fijaciones de packs de reglas bloqueadas con SHA-256: loadFromLockFile(), get(), verifyArtefact(), regenerateLockFile()	—	VersionPinException, InvalidArgumentException, JsonException ante un JSON de lock malformado	Los digests en blanco o malformados fallan en modo cerrado
InvoiceContractValidator	?SemanticValidator	Adaptador ValidatorInterface entre niveles; verificación estructural previa más reglas semánticas profundas EN 16931	ContractResult	Falla en modo cerrado; los errores del motor se exponen como hallazgos de error	Se enlaza en rutas de framework cuando nextpdf/premium está instalado
ZugferdContractEmbedder	FacturXContractEmbedder	Adaptador EmbedderInterface entre niveles; incrustación byte-in / byte-out	string (bytes de PDF)	Propaga los fallos del delegado	Delega en el motor de reescritura de bytes de nivel Pro
ZugferdEmbeddingException, PeppolEmbeddingException, SchematronCacheException, VersionPinException	—	Taxonomía de fallos del módulo	—	—	Todas extienden RuntimeException

public static function basic(
    PdfAManager $pdfAManager,
    FileAttachment $fileAttachment,
    string $xmlData,
): ZugferdEmbedResult

public function embed(
    PdfAManager $pdfAManager,
    FileAttachment $fileAttachment,
): ZugferdEmbedResult

public static function invoice(
    PdfAManager $pdfAManager,
    FileAttachment $fileAttachment,
    string $ublXml,
): PeppolEmbedResult

public static function validate(
    string $xmlData,
    ZugferdProfile $profile,
    ?InvoiceValidatorMode $mode = null,
): InvoiceValidationResult

public function validate(string $xsltPath, string $xmlData): SchematronResult

Contrato de comportamiento

Incrustación. ZugferdEmbedder adjunta a un portador PDF/A una carga útil XML UN/CEFACT CII ZUGFeRD 2.4 / Factur-X 1.08 suministrada por quien llama. Admite dos portadores: PDF/A-4f (ISO 19005-4:2020), el portador moderno preferido, y PDF/A-3b (ISO 19005-3:2012) por compatibilidad hacia atrás. embed() ejecuta siempre primero un paso de seguridad XmlGuard, luego la validación estructural salvo que se haya fijado withoutValidation(), después verifica que el portador admita archivos incrustados, inyecta la declaración de esquema de extensión XMP mediante ZugferdXmpSchema y adjunta el XML como archivo asociado. La relación del adjunto usa por defecto la recomendación del rulebook /Alternative; las sustituciones pasan por el mismo rulebook, que impone el conjunto de relaciones de ISO 32000-2:2020 §14.13 y el subconjunto de facturas EN 16931. PeppolEmbedder realiza lo equivalente para el XML UBL 2.1 de factura o nota de crédito Peppol BIS Billing 3.0 suministrado por quien llama. Ninguno de los dos incrustadores genera el XML de factura.

Validación. InvoiceXmlValidator comprueba el XML CII frente a las expectativas estructurales de EN 16931: elemento raíz, secciones requeridas, cardinalidad de la cabecera, líneas de detalle cuando el perfil las exige y el identificador de especificación BT-24 exigido por la regla de negocio BR-1. InvoiceValidatorMode selecciona la severidad. COMPAT (por defecto) informa de un BT-24 ausente o discordante como advertencia, para que una puerta booleana de validez no regrese. STRICT convierte ambos en un error grave y además comprueba la coherencia del perfil frente al ZugferdProfile declarado, reflejando la semántica de los validadores externos KoSIT / Mustang. El modo se resuelve en este orden: argumento explícito, luego la sustitución por entorno INVOICE_VALIDATOR_MODE y luego COMPAT. Los resultados son objetos estructurados InvoiceValidationResult / InvoiceValidationFinding; el validador devuelve hallazgos en lugar de lanzar.

Schematron. SchematronValidator ejecuta conjuntos de reglas Schematron precompilados —las reglas .sch de CEN EN 16931 compiladas a XSLT en tiempo de compilación— usando el procesador XSLT de PHP en proceso. Analiza el informe SVRL en objetos SchematronFinding / SchematronResult: las aserciones fallidas se convierten en hallazgos de error y los informes exitosos en hallazgos de info. Una caché opcional (SchematronCacheInterface, con la implementación de archivo con renombrado atómico) sirve bytes de hoja de estilo verificados, indexados por digest de contenido más la versión del compilador. VersionPinRegistry fija cada pack de reglas externo a una versión bloqueada con SHA-256 y falla en modo cerrado ante desviaciones o digests malformados.

Este módulo produce y comprueba datos de factura estructurados. No afirma que ningún documento sea una factura legalmente conforme, que esté aprobado por la autoridad fiscal ni que se garantice su aceptación por autoridad alguna. El validador comprueba únicamente el modelo semántico EN 16931 y el contenedor ZUGFeRD / Factur-X / UBL; excluye las extensiones nacionales (por ejemplo, el SDI italiano, el Chorus Pro francés o el transporte XRechnung alemán). Como establece EN 16931-1, el emisor de la factura es responsable de cumplir las reglas de la legislación pertinente; este no es un validador de la autoridad fiscal. La compatibilidad con una norma no equivale a su conformidad.

Casos límite y modos de fallo

• El XML vacío falla de inmediato: los builders lanzan InvalidArgumentException; InvoiceXmlValidator::validate() devuelve un resultado fallido.
• XmlGuard rechaza las declaraciones DOCTYPE, la expansión de entidades, las cargas sobredimensionadas y los caracteres de control. Los incrustadores lo exponen como ZugferdEmbeddingException o PeppolEmbeddingException conservando la causa.
• withoutValidation() y withoutSanitization() nunca omiten el paso de seguridad XmlGuard. Solo se pueden saltar las comprobaciones estructurales de términos de negocio.
• Un portador sin soporte de archivos incrustados (cualquiera que no sea PDF/A-4f ni PDF/A-3b) provoca InvalidArgumentException nombrando las versiones aceptadas.
• Un valor AFRelationship no permitido se rechaza en el límite del builder; dentro de embed() se ejecuta de nuevo una comprobación del rulebook según el portador.
• COMPAT mantiene un BT-24 ausente con severidad de advertencia; STRICT convierte los valores BT-24 ausentes y con perfil discordante en errores graves.
• SchematronValidator solo lanza ante una ruta XSLT ausente o ilegible. Los fallos de transformación o de análisis de SVRL devuelven SchematronResult::error() con isValid en false.
• Una entrada de caché cuyos bytes almacenados no superan la verificación de digest se expulsa y la hoja de estilo se relee de disco; los bytes envenenados nunca se devuelven.
• El procesador XSLT se ejecuta con la carga de recursos de archivo y de red bloqueada y nunca registra funciones PHP; document(), xsl:include, xsl:import y result-document no pueden cargar recursos.
• VersionPinRegistry rechaza los digests SHA-256 en blanco o malformados en la ingesta y en la regeneración; verifyArtefact() devuelve false en lugar de dejar pasar una fijación no verificable.
• Este módulo no realiza ninguna firma criptográfica; el comportamiento en modo FIPS queda fuera de alcance aquí (véase el módulo Signature).

Conformidad

Comportamiento	Referencia	Estado
Modelo semántico central de factura	EN 16931-1:2026 §4	Desarrollado conforme a; el emisor sigue siendo responsable
Identificador de especificación (BT-24)	EN 16931-1:2026 BR-1	Advertencia en COMPAT, error en STRICT
Enlace de sintaxis UN/CEFACT CII	CEN/TS 16931-3-3:2020	Incrustación admitida
Enlace de sintaxis UBL 2.1	CEN/TS 16931-3-2:2020	Incrustación admitida
Archivo asociado PDF/A-3	ISO 19005-3:2012 §6.7.8	Portador admitido
Archivo incrustado PDF/A-4f	ISO 19005-4:2020 Annex A	Portador admitido
Valores de relación de archivo asociado	ISO 32000-2:2020 §14.13	Regulado por el rulebook
Análisis de informes Schematron / SVRL	ISO/IEC 19757-3	Desarrollado conforme a (basado en el producto; norma no incluida en el corpus de citas)

Desarrollado conforme a, no es una certificación ni una aprobación de la autoridad fiscal. NextPDF no ostenta certificación alguna para ninguna de estas normas. NextPDF produce facturas estructuradas conformes al modelo de datos EN 16931 y notifica hallazgos de reglas; no produce facturas legalmente conformes, no proporciona salida aprobada por la autoridad fiscal ni garantiza su aceptación. Consulte a sus asesores fiscales y legales.

Notas de desarrollo

• El motor Schematron requiere la extensión PHP ext-xsl; aprovisionarla y habilitarla es responsabilidad del operador.
• El procesamiento es en proceso y local. No se producen llamadas de red salientes durante la incrustación o la validación. El transporte nacional de facturación electrónica, las plataformas de compensación y los sistemas de archivo son externos a este módulo.
• Los packs de reglas se compilan de .sch a XSLT en tiempo de compilación; el tiempo de ejecución ejecuta únicamente hojas de estilo precompiladas.
• Las claves de caché incorporan la sal de versión del compilador (actualmente nextpdf-schxslt-1.0); modificarla invalida las cachés desplegadas sin un paso de purga.
• Las fijaciones de packs de reglas viven en el archivo de lock en enterprise/config/invoice-versions.lock (VersionPinRegistry::DEFAULT_LOCK_PATH); CI verifica los artefactos desplegados frente a los digests fijados.
• Quienes llaman entre niveles usan InvoiceContractValidator y ZugferdContractEmbedder; quienes llaman de forma nativa a Enterprise usan ZugferdEmbedder e InvoiceXmlValidator directamente.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie pública de la API admitida. Las rutas de espacio de nombres internas, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de runbook y los prefijos de ticket quedan fuera de alcance.

Véase también

• Capacidad Invoice — contraparte de capacidad de esta referencia.
• Pro Compliance — detección/validación de nivel Pro.
• Presentación electrónica de documentos
• Resumen de Enterprise