Conformidad ZUGFeRD / Factur-X: perfil de factura EN 16931 embebido

De un vistazo

Declaración de alcance. NextPDF produce el perfil XML embebido; la validez fiscal y legal la determina la autoridad receptora, no la biblioteca.

ZUGFeRD / Factur-X es una factura híbrida: un PDF legible por humanos (un sustrato de archivo PDF/A-3) con un XML de Cross-Industry-Invoice (CII) embebido y legible por máquina, que sigue el modelo de datos semántico EN 16931. NextPDF Core proporciona el contrato del embebedor (NextPDF\Contracts\EInvoice); el motor concreto Factur-X 1.08 se distribuye en el paquete Premium nextpdf/pro. La biblioteca produce el XML embebido y la estructura del adjunto PDF/A-3; un validador EN 16931 / Schematron —o la autoridad fiscal receptora— determina la validez fiscal.

Instalación

composer require nextpdf/core:^3   # EInvoice contracts only
composer require nextpdf/pro       # Factur-X 1.08 embedder engine

Core proporciona EmbedderInterface, ProfileInterface, ProfileType, ValidatorInterface y ValidationResult en NextPDF\Contracts\EInvoice. El docblock de la interfaz lo indica explícitamente: el nivel Pro (motor de reescritura byte a byte Factur-X 1.08) y el nivel Enterprise (constructor gestionado por PDF/A) implementan este contrato. Core por sí solo no embebe facturas: define el contrato byte-in/byte-out que satisfacen esos niveles.

Panorama conceptual

NextPDF\Contracts\EInvoice\ProfileType es el discriminador de conformidad EN 16931: MINIMUM, BASIC_WL, BASIC, EN16931, EXTENDED, XRECHNUNG. Su isEn16931Conformant() codifica la regla tomada directamente de EN 16931-1. MINIMUM y BASIC_WL no son conformes con EN 16931 (incumplen la cardinalidad del identificador de especificación BT-24 y el requisito de líneas de factura). BASIC, EN16931, EXTENDED, XRECHNUNG sí son conformes con EN 16931.

El embebedor (EmbedderInterface) está contratado para:

parsear el XML CII suministrado mediante XmlGuard (a salvo de XXE);
inyectar el esquema de extensión XMP de Factur-X para el perfil declarado;
adjuntar el XML como archivo embebido con el AFRelationship correcto (Data / Alternative), para que el sustrato de archivo PDF/A-3 (§6.7.5, requisitos de archivo embebido — claves F/UF) lo transporte.

NextPDF genera esta estructura. No afirma que la factura sea fiscalmente válida; esa determinación corresponde a la autoridad receptora, según las reglas de negocio del §7 de EN 16931 y cualquier CIUS nacional.

Superficie de la API

Símbolo	Efecto
`Contracts\EInvoice\EmbedderInterface`	Contrato byte-in/byte-out; Pro/Enterprise lo implementan.
`Contracts\EInvoice\ProfileType` (enum)	Discriminador de perfiles EN 16931.
`ProfileType::isEn16931Conformant(): bool`	Falso para MINIMUM/BASIC_WL; verdadero para BASIC/EN16931/EXTENDED/XRECHNUNG.
`Contracts\EInvoice\ValidatorInterface`	Contrato de validación que devuelve un `ValidationResult` con las violaciones de reglas.

Ejemplo de código — Inicio rápido

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Contracts\EInvoice\ProfileType;

// Core: choose and check the profile before delegating embedding to Pro.
$profile = ProfileType::EN16931;

if (!$profile->isEn16931Conformant()) {
    fwrite(STDERR, "Profile {$profile->value} is not EN 16931 conformant.\n");
    exit(1);
}

// The concrete embedder is provided by nextpdf/pro:
//   $embedder = /* the Factur-X embedder from nextpdf/pro; see the Premium docs */;
//   $pdfWithInvoice = $embedder->embed($basePdfBytes, $ciiXml, $options);
echo "Profile {$profile->value} selected (embedding requires nextpdf/pro).\n";

Ejemplo de código — Producción

La canalización de producción (nivel Pro) embebe el XML CII en una base PDF/A-3. Después ejecuta un validador Schematron EN 16931 (o lo envía a la autoridad receptora). Ese informe debe tratarse como la compuerta de decisión. NextPDF emite el XML embebido y el adjunto PDF/A-3; el validador o la autoridad decide la validez fiscal. Core por sí solo no puede ejecutar esta canalización: nextpdf/pro es necesario para el motor del embebedor.

Casos límite y trampas

Core solo tiene contratos. Sin nextpdf/pro no hay ningún embebedor concreto. El código que lo usa debe depender de la interfaz y degradar el comportamiento con claridad cuando la implementación Pro esté ausente.
MINIMUM / BASIC_WL no son EN 16931. isEn16931Conformant() devuelve falso para estos; no se debe anunciar una factura EN 16931 al usarlos.
Sustrato PDF/A-3. El XML embebido viaja en un contenedor de archivo PDF/A-3; las claves F/UF del archivo embebido (PDF/A §6.7.5) deben estar presentes.
El XML se parsea a salvo de XXE. El contrato exige el parseo con XmlGuard; un embebedor personalizado no debe introducir una vía vulnerable a XXE.
La validez no es el veredicto de la biblioteca. Producir un archivo Factur-X estructuralmente correcto no es una afirmación de que la autoridad fiscal lo aceptará.

Rendimiento

El proceso de embebido reescribe el PDF para añadir el adjunto XML y el esquema de extensión XMP. Está presupuestado en ≤ 1500 ms de reloj y un pico de ≤ 128 MB para una factura típica.

Notas de seguridad

El XML embebido se parsea de forma segura frente a XXE mediante XmlGuard. El XML de la factura contiene PII comercial (partes, importes) por naturaleza: está embebido, no cifrado. La confidencialidad de la factura es responsabilidad del integrador.

Residencia de datos y mitigaciones de PII

El XML de la factura transporta PII de las partes e información financiera. El embebido ocurre dentro del proceso; ningún dato sale del proceso durante el embebido. La transmisión a una autoridad receptora queda fuera del alcance y es responsabilidad del integrador en materia de residencia de datos.

Telemetría segura y depuración de registros

No registrar nunca el XML CII ni los bytes del PDF embebido: contienen PII de la factura. Registrar solo el nombre del perfil y un veredicto estructural.

Modelo de amenazas

Un archivo Factur-X no tiene control de acceso. El XML embebido es legible para cualquiera que tenga el archivo. El híbrido garantiza la legibilidad por máquina de la factura, no su confidencialidad ni su aceptación fiscal.

Comportamiento en modo FIPS

El embebido no realiza ninguna criptografía. Una factura Factur-X firmada es un asunto aparte de la receta de firma y hereda la postura FIPS de esa receta; esta página no hace ninguna afirmación sobre la firma.

Conformidad

Afirmación	Especificación	Cláusula
Una factura EN 16931 transporta los términos de negocio del modelo de datos semántico.	EN 16931-1	§6.4
La conformidad con EN 16931 se rige por la cardinalidad de las reglas de negocio que una factura conforme debe satisfacer.	EN 16931-1	§7
El perfil EN 16931 de Factur-X exige que el XML CII cumpla las reglas de negocio.	Factur-X 1.08	perfil EN 16931
El perfil EN 16931 de Factur-X exige el contenido de factura obligatorio.	Factur-X 1.08	perfil EN 16931
Factur-X es un híbrido: XML legible por máquina embebido junto al PDF legible por humanos.	Factur-X 1.08	Basic
El XML embebido viaja en un sustrato de archivo PDF/A (claves F/UF de archivo embebido).	ISO 19005-4	§6.7.5

Las citas son punteros de ID de cláusula + reference_id hacia el corpus de verificación. No se reproduce ningún texto de las normas; las cláusulas se resumen con palabras de NextPDF.