Cumplimiento — Referencia detallada

De un vistazo

El módulo Compliance dirige un PDF terminado a un sidecar de validación externo y devuelve un único resultado normalizado. ComplianceGateway resuelve el sidecar responsable a partir de un ComplianceProfile, aplica una política de disponibilidad de cierre seguro y envuelve cada veredicto de herramienta en un ExternalValidationResult. Se distribuyen puentes para veraPDF (PDF/A, PDF/UA, PDF 2.0 Arlington), EU DSS (niveles PAdES), el sidecar combinado Mustang/KoSIT (ZUGFeRD, Factur-X, EN 16931) y un daemon KoSIT independiente. El módulo también proporciona el sellado de preparación de AiReadyCertifier y un ejecutor para el conjunto de pruebas oficial KoSIT XRechnung.

Disponibilidad y licencias

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

La superficie de Compliance/Evidence está licenciada por la capacidad enterprise.compliance.evidence. Un derecho de uso ausente o caducado deniega la función; no degrada el comportamiento de forma silenciosa.

Nivel	Superficie de Compliance
Core	Comprobaciones de flujo de bytes y de gramática en proceso; sin delegación en sidecar externo.
Pro	Validación EN 16931 / Factur-X / ZUGFeRD en proceso; sin sidecar externo.
Enterprise	Puerta de enlace de validadores externos (este módulo) con un resultado unificado y una política de cierre seguro.

El validador de facturas electrónicas en proceso de Pro y el sidecar externo ZUGFeRD de Enterprise son superficies distintas. La puerta de enlace de validadores externos se distribuye únicamente en el paquete nextpdf/enterprise.

Superficie de API pública

composer require nextpdf/enterprise:^3

Símbolo	Parámetros	Comportamiento por defecto	Devuelve	Lanza o falla con	Notas
ComplianceGateway::__construct	list<ExternalValidator> $validators, LoggerInterface $logger, bool $optional = false	Indexa los validadores por nombre de herramienta	—	—	El modo opcional degrada la comprobación de disponibilidad a solo advertencia
ComplianceGateway::validate	string $pdfContent, ComplianceProfile $profile, array $options = []	Resuelve el validador mediante ComplianceProfile::toolName(), comprueba la disponibilidad, delega	?ExternalValidationResult	ComplianceSidecarUnavailableException; InvalidArgumentException (ningún validador registrado para la herramienta)	Devuelve null únicamente en modo opcional con el sidecar caído
ComplianceGateway::validateAllProfiles	string $pdfContent, string $toolName	Valida cada perfil asignado a la herramienta	list<ExternalValidationResult>	Igual que validate()	Omite los resultados null (de modo opcional)
ComplianceGateway::healthCheck	—	Sondea el punto de conexión de estado de cada sidecar registrado	array<string, bool>	—	Informa de la accesibilidad; no valida ningún documento
ComplianceGateway::buildComplianceMatrix (estático)	list<ExternalValidationResult> $results, string $commitSha	Reduce los resultados a una matriz con versión de esquema	array<string, mixed>	—	Versión de esquema 1.0; registra la salida de la herramienta, no afirma nada
ComplianceProfile (enum)	15 casos respaldados por cadena	Asigna cada perfil a una etiqueta de norma y a una herramienta	—	—	standardReference(): string, toolName(): string
ExternalValidator (interfaz)	—	Contrato de puente de sidecar sobre PSR-18	—	validate() lanza ComplianceSidecarUnavailableException ante un fallo de transporte	getToolName(), isAvailable(), validate()
VeraPdfValidator::validate	Firma de la interfaz	POST multipart al sidecar REST de veraPDF; análisis del informe JSON	ExternalValidationResult	ComplianceSidecarUnavailableException; InvalidArgumentException (perfil no compatible)	PDF/A, PDF/UA, Arlington; analiza solo JSON, nunca XML
DssValidator::validate	Firma de la interfaz	POST JSON en Base64 al sidecar REST de EU DSS	ExternalValidationResult	ComplianceSidecarUnavailableException; InvalidArgumentException (perfil no compatible)	PAdES B-B hasta B-LTA; el constructor rechaza tiempos de espera inferiores a un segundo
ZugferdExternalValidator::validate	Firma de la interfaz	POST multipart al sidecar combinado Mustang/KoSIT	ExternalValidationResult	ComplianceSidecarUnavailableException (también con un cortacircuitos abierto); InvalidArgumentException (perfil no compatible)	ZUGFeRD 2.4, Factur-X 1.08, EN 16931; cortacircuitos inyectado opcional
KoSitValidator::validate	Firma de la interfaz	POST de XML sin procesar a un daemon KoSIT independiente	ExternalValidationResult	ComplianceSidecarUnavailableException; InvalidArgumentException (perfil no compatible)	Solo EN 16931; analiza el informe SVRL de Schematron con cierre seguro
ExternalValidationResult	Objeto de valor de solo lectura	Veredicto de herramienta normalizado	—	—	passes(), fails(), nonConformanceCount(), toComplianceMatrix()
NonConformance	Objeto de valor de solo lectura	Hallazgo único con id de regla, cláusula, gravedad y ubicación	—	—	toArray()
ComplianceSidecarUnavailableException	string $toolName, string $endpoint, int $code = 0, ?Throwable $previous = null	Señal de indisponibilidad de sidecar con cierre seguro	—	—	toolName y endpoint públicos de solo lectura
AiReadyCertifier::certify	string $pdfBytes	Evalúa tres criterios de preparación; sella la procedencia XMP	array{0: AiReadyCertification, 1: string}	InvalidArgumentException (el sellado requiere una tabla de referencias cruzadas clásica)	El segundo elemento es igual a la entrada cuando el nivel es not_certified
AiReadyCertification	Objeto de valor de solo lectura	Evaluación de preparación con nivel, recuento de criterios, incidencias y hash de origen	—	—	Etiqueta de preparación interna, no una certificación de normas
XRechnungTestSuiteRunner::__construct	string $suitePath, ExternalValidator $validator, bool $useCuratedNegativeFallback = true	Resuelve el directorio del conjunto extraído	—	InvalidArgumentException (el directorio no existe)	Apunta al conjunto de pruebas oficial KoSIT XRechnung
XRechnungTestSuiteRunner::run	bool $stopOnFirstFailure = false	Valida cada instancia del conjunto a través del puente	XRechnungTestSuiteResult	XRechnungTestSuiteException (validador no disponible; sin archivos XML)	También isAvailable(), getSuitePath(), discoverTestFiles()
XRechnungTestSuiteResult	Objeto de valor de solo lectura	Resultado agregado del conjunto	—	—	allPassed(), totalCount(), getFailures(), getErrors(), toSummary()
XRechnungTestCaseResult	Objeto de valor de solo lectura	Resultado por caso	—	—	passed(), hasError(), getFilename()
XRechnungTestSuiteException	Constructores estáticos	Señal de fallo en ejecución del conjunto	self	—	validatorUnavailable(), noTestFilesFound(string $suitePath)

namespace NextPDF\Enterprise\Compliance;

final class ComplianceGateway
{
    /** @param list<ExternalValidator> $validators */
    public function __construct(
        array $validators,
        private readonly LoggerInterface $logger,
        private readonly bool $optional = false,
    );

    /** @param array<string, mixed> $options */
    public function validate(
        string $pdfContent,
        ComplianceProfile $profile,
        array $options = [],
    ): ?ExternalValidationResult;

    /** @return list<ExternalValidationResult> */
    public function validateAllProfiles(string $pdfContent, string $toolName): array;

    /** @return array<string, bool> */
    public function healthCheck(): array;

    /**
     * @param list<ExternalValidationResult> $results
     * @return array<string, mixed>
     */
    public static function buildComplianceMatrix(array $results, string $commitSha): array;
}

interface ExternalValidator
{
    public function getToolName(): string;

    public function isAvailable(): bool;

    /** @param array<string, mixed> $options */
    public function validate(
        string $pdfContent,
        ComplianceProfile $profile,
        array $options = [],
    ): ExternalValidationResult;
}

enum ComplianceProfile: string
{
    case PdfA1b = 'pdfa-1b';
    // PdfA2b, PdfA3b, PdfA4, PdfA4f, PdfUa1, PdfUa2, Pdf20Arlington,
    // PadesBasic, PadesTimestamp, PadesLongTerm, PadesArchive,
    // Zugferd24, FacturX108, En16931

    public function standardReference(): string;

    public function toolName(): string;
}

final class AiReadyCertifier
{
    /** @return array{0: AiReadyCertification, 1: string} Tuple of [certification, stamped PDF bytes] */
    public function certify(string $pdfBytes): array;
}

Contrato de comportamiento

ComplianceGateway::validate() resuelve el ExternalValidator registrado cuyo getToolName() coincide con ComplianceProfile::toolName(), comprueba isAvailable(), delega y devuelve un ExternalValidationResult normalizado. Reglas observables desde el exterior:

• Cierre seguro por defecto. Cuando el sidecar resuelto no está disponible y el modo opcional está desactivado, la llamada lanza ComplianceSidecarUnavailableException. El documento no se comprueba; nunca se trata como aprobado.
• Modo opcional. Construir la puerta de enlace con optional: true (los operadores lo conectan desde la variable de entorno NEXTPDF_COMPLIANCE_OPTIONAL) degrada un sidecar no disponible a una advertencia registrada y un retorno null. Quien llama debe tratar null como «no comprobado». El modo opcional cubre únicamente el sondeo previo de disponibilidad; un fallo de transporte durante la propia llamada de validación lanza ComplianceSidecarUnavailableException en ambos modos.
• Perfil desconocido. Un perfil sin validador registrado lanza InvalidArgumentException; nunca aprueba de forma silenciosa.
• Semántica de aprobación. ExternalValidationResult::passes() requiere que conformant sea verdadero y cero no conformidades. Cada resultado lleva el perfil, el nombre y la versión de la herramienta, el recuento de aserciones, los hallazgos, el SHA-256 de los bytes validados, una marca de tiempo UTC y la duración de la llamada.
• La matriz es un registro, no una afirmación. buildComplianceMatrix() es un reductor estático que produce una estructura con versión de esquema, con las versiones de las herramientas y un SHA de commit para la trazabilidad. Registra la salida de la herramienta; no afirma nada.
• Flujo de datos. El flujo de bytes completo del PDF se transmite al sidecar configurado a través de un cliente PSR-18. Cada validación se registra mediante PSR-3 con el perfil, la herramienta, aprobado/fallido, el recuento de aserciones y la duración.

Enrutamiento de perfil a herramienta, tal como lo devuelven ComplianceProfile::standardReference() y ::toolName():

Casos de perfil	Referencia de norma	Herramienta
pdfa-1b, pdfa-2b, pdfa-3b, pdfa-4, pdfa-4f	ISO 19005-1/-2/-3/-4 (Nivel B; Nivel F para 4f)	veraPDF
pdfua-1, pdfua-2	ISO 14289-1:2014, ISO 14289-2:2024	veraPDF
pdf20-arlington	ISO 32000-2:2020 (modelo Arlington)	veraPDF
pades-b-b, pades-b-t, pades-b-lt, pades-b-lta	ETSI EN 319 142-1 B-B hasta B-LTA	EU DSS
zugferd-2.4, factur-x-1.08, en-16931	ZUGFeRD 2.4 / Factur-X 1.08 / EN 16931-1:2017	Mustang/KoSIT

AiReadyCertifier::certify() evalúa tres criterios: la presencia estructural de firma, la salud de LTV y la ausencia de cifrado. Tres criterios superados producen el nivel certified; uno o dos producen partial; cero produce not_certified. En certified o partial, añade una actualización incremental que lleva un flujo de procedencia XMP y una anulación de Catalog; los bytes originales nunca se modifican. El nivel «certified» es una etiqueta de preparación interna de NextPDF, no una certificación de normas.

VeraPdfValidator analiza únicamente respuestas JSON del sidecar (sin XML; libre de XXE por construcción). KoSitValidator analiza el informe SVRL en XML del daemon con las declaraciones DOCTYPE rechazadas y el acceso de red desactivado, y trata un informe que no se puede analizar como un fallo de la llamada.

Casos límite y modos de fallo

• Un tiempo de espera del sidecar o un error de transporte se manifiesta como ComplianceSidecarUnavailableException desde el puente; aplica el cierre seguro por defecto.
• Una respuesta del sidecar distinta de 200 produce un resultado fallido con un hallazgo específico de la herramienta (por ejemplo VERAPDF-HTTP-ERROR); nunca es una aprobación de conformidad.
• Un cuerpo JSON o XML del sidecar mal formado es un fallo de validación de la llamada, no una aprobación de conformidad.
• Los resultados de EU DSS sin firmas fallan con DSS-NO-SIGNATURES. Una indicación distinta de TOTAL_PASSED falla con DSS-SIG-INVALID. Un nivel de firma por debajo de la línea base esperada falla con DSS-LEVEL-MISMATCH.
• DssValidator publica su presupuesto de tiempo de espera por solicitud en cada solicitud mediante la cabecera X-NextPDF-Timeout-Seconds; el cliente PSR-18 del integrador debe respetarlo para que un sidecar bloqueado no pueda retener el hilo llamante de forma ilimitada.
• ZugferdExternalValidator opcionalmente enruta las llamadas al sidecar a través de un cortacircuitos inyectado; un cortacircuitos abierto se corresponde con ComplianceSidecarUnavailableException (fallo rápido, aun así con cierre seguro). El valor por defecto es un cortacircuitos sin operación.
• KoSitValidator::isAvailable() acepta HTTP 200 y 405 del sondeo de estado del daemon; el daemon responde a GET con 405 cuando está en buen estado.
• El sellado de AiReadyCertifier falla de forma segura con InvalidArgumentException cuando el documento original carece de una tabla de referencias cruzadas clásica (por ejemplo, flujos de referencias cruzadas).
• XRechnungTestSuiteRunner::run() se niega a ejecutarse cuando el validador no está disponible o el conjunto no contiene archivos XML; con useCuratedNegativeFallback activado sustituye por un corpus negativo curado cuando el conjunto no incluye instancias no válidas.

Comportamiento en modo FIPS

Este módulo no realiza firma ni custodia de claves. La política de algoritmos en modo FIPS la gobiernan los módulos Security y Signature. La conformidad de firma se delega en EU DSS, que toma su propia determinación.

Conformidad

La puerta de enlace delega el veredicto de conformidad en una herramienta externa; el diseño refleja el propio límite de las normas según el cual la conformidad se determina frente a los requisitos, no la afirma un productor.

Comportamiento	Referencia
Obligación del procesador conforme; la conformidad se determina frente a la norma	ISO 19005-4:2020 §5.2
Requisitos de archivo PDF/A-4 frente a la autoafirmación del productor	ISO 19005-4:2020 §6.6.4
La conformidad PDF/UA-2 es una propiedad del archivo	ISO 14289-2:2024 §6
Niveles de firma de referencia PAdES	ETSI EN 319 142-1 §5.4.3

La herramienta externa produce el veredicto. NextPDF no posee ninguna certificación y no concede ninguna; la compatibilidad con un perfil no es conformidad con él. Los resultados de validación son registros técnicos de comprobación de estructura a título de referencia, no asesoramiento jurídico; consulte a su equipo de cumplimiento para juzgar la suficiencia regulatoria.

Notas de desarrollo

• El operador aloja y opera los sidecars, fija sus versiones, restringe su alcance de red, valida su TLS y controla el entorno que habilita el modo opcional. Los puntos de conexión del sidecar son un límite de confianza; los controles de residencia y retención de documentos, resultados y registros son responsabilidad del operador.
• La salida de buildComplianceMatrix() está diseñada para la trazabilidad de CI: fije el SHA de commit y archive la matriz junto a los artefactos de compilación.
• El ejecutor de XRechnung espera el conjunto de pruebas oficial extraído en un directorio local; el mensaje de su constructor indica la fuente de descarga pública.
• El detalle del mecanismo interno permanece en la documentación interna del repositorio de origen y queda fuera del alcance de este manual.

Límite de publicación

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

Consulta también

• Descripción general de la capacidad Compliance
• Validation — Referencia detallada
• Evidencia — Referencia detallada
• Pro Compliance — factura electrónica en proceso (superficie distinta)
• Core Conformance