Enterprise sürüm

Compliance — Derinlemesine başvuru

Bir bakışta

Compliance modülü, tamamlanmış bir PDF’i harici bir doğrulama yardımcı bileşenine yönlendirir ve normalize edilmiş tek bir sonuç döndürür. ComplianceGateway, sorumlu yardımcı bileşeni bir ComplianceProfile öğesinden çözümler, kapalı arızalama kullanılabilirlik politikasını uygular ve her araç kararını bir ExternalValidationResult içinde sarmalar. veraPDF (PDF/A, PDF/UA, PDF 2.0 Arlington), EU DSS (PAdES düzeyleri), birleşik Mustang/KoSIT yardımcı bileşeni (ZUGFeRD, Factur-X, EN 16931) ve bağımsız bir KoSIT arka plan hizmeti için köprüler sunulur. Modül ayrıca AiReadyCertifier hazırlık damgalaması ve resmî KoSIT XRechnung test paketi için bir çalıştırıcı sağlar.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Enterprise (nextpdf/enterprise) içinde sunulur ve Enterprise katmanı lisans zarfıyla etkinleşir. Bu hakka sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve bir lisans edinin.

Compliance/Evidence yüzeyi, enterprise.compliance.evidence yeteneği tarafından lisanslanır. Eksik veya süresi dolmuş bir hak, özelliği reddeder; davranışı sessizce düşürmez.

Katman	Compliance yüzeyi
Core	Süreç içi bayt akışı ve dilbilgisi denetimleri; harici yardımcı bileşen yetkilendirmesi yok.
Pro	Süreç içi EN 16931 / Factur-X / ZUGFeRD doğrulaması; harici yardımcı bileşen yok.
Enterprise	Birleşik bir sonuç ve kapalı arızalama politikasıyla harici doğrulayıcı ağ geçidi (bu modül).

Pro süreç içi e-fatura doğrulayıcısı ile Enterprise harici ZUGFeRD yardımcı bileşeni ayrı yüzeylerdir. Harici doğrulayıcı ağ geçidi yalnızca nextpdf/enterprise paketinde sunulur.

Genel API yüzeyi

composer require nextpdf/enterprise:^3

Simge	Parametreler	Varsayılan davranış	Döndürür	Şununla hata verir veya başarısız olur	Notlar
`ComplianceGateway::__construct`	`list<ExternalValidator> $validators`, `LoggerInterface $logger`, `bool $optional = false`	Doğrulayıcıları araç adına göre dizinler	—	—	İsteğe bağlı mod, kullanılabilirlik denetimini yalnızca uyarıya indirger
`ComplianceGateway::validate`	`string $pdfContent`, `ComplianceProfile $profile`, `array $options = []`	Doğrulayıcıyı `ComplianceProfile::toolName()` ile çözümler, kullanılabilirliği denetler, yetki devreder	`?ExternalValidationResult`	`ComplianceSidecarUnavailableException`; `InvalidArgumentException` (araç için kayıtlı doğrulayıcı yok)	Yalnızca isteğe bağlı modda ve yardımcı bileşen kapalıyken `null` döndürür
`ComplianceGateway::validateAllProfiles`	`string $pdfContent`, `string $toolName`	Araca eşlenen her profili doğrular	`list<ExternalValidationResult>`	`validate()` ile aynı	`null` (isteğe bağlı mod) sonuçlarını atlar
`ComplianceGateway::healthCheck`	—	Kayıtlı her yardımcı bileşenin sağlık uç noktasını yoklar	`array<string, bool>`	—	Erişilebilirliği raporlar; hiçbir belgeyi doğrulamaz
`ComplianceGateway::buildComplianceMatrix` (statik)	`list<ExternalValidationResult> $results`, `string $commitSha`	Sonuçları şema sürümlü bir matrise indirger	`array<string, mixed>`	—	Şema sürümü `1.0`; araç çıktısını kaydeder, hiçbir şey öne sürmez
`ComplianceProfile` (enum)	15 string destekli durum	Her profili bir standart etiketine ve bir araca eşler	—	—	`standardReference(): string`, `toolName(): string`
`ExternalValidator` (arayüz)	—	PSR-18 üzerinden yardımcı bileşen köprü sözleşmesi	—	Aktarım hatasında `validate()`, `ComplianceSidecarUnavailableException` oluşturur	`getToolName()`, `isAvailable()`, `validate()`
`VeraPdfValidator::validate`	Arayüz imzası	veraPDF REST yardımcı bileşenine multipart POST; JSON rapor ayrıştırması	`ExternalValidationResult`	`ComplianceSidecarUnavailableException`; `InvalidArgumentException` (desteklenmeyen profil)	PDF/A, PDF/UA, Arlington; yalnızca JSON ayrıştırır, asla XML değil
`DssValidator::validate`	Arayüz imzası	EU DSS REST yardımcı bileşenine Base64 JSON POST	`ExternalValidationResult`	`ComplianceSidecarUnavailableException`; `InvalidArgumentException` (desteklenmeyen profil)	PAdES B-B’den B-LTA’ya; yapıcı, bir saniyenin altındaki zaman aşımlarını reddeder
`ZugferdExternalValidator::validate`	Arayüz imzası	Birleşik Mustang/KoSIT yardımcı bileşenine multipart POST	`ExternalValidationResult`	`ComplianceSidecarUnavailableException` (açık bir devre kesicide de); `InvalidArgumentException` (desteklenmeyen profil)	ZUGFeRD 2.4, Factur-X 1.08, EN 16931; isteğe bağlı enjekte edilen devre kesici
`KoSitValidator::validate`	Arayüz imzası	Bağımsız bir KoSIT arka plan hizmetine ham XML POST	`ExternalValidationResult`	`ComplianceSidecarUnavailableException`; `InvalidArgumentException` (desteklenmeyen profil)	Yalnızca EN 16931; Schematron SVRL raporunu kapalı arızalama ile ayrıştırır
`ExternalValidationResult`	Salt okunur değer nesnesi	Normalize edilmiş araç kararı	—	—	`passes()`, `fails()`, `nonConformanceCount()`, `toComplianceMatrix()`
`NonConformance`	Salt okunur değer nesnesi	Kural kimliği, madde, önem derecesi ve konum içeren tek bir bulgu	—	—	`toArray()`
`ComplianceSidecarUnavailableException`	`string $toolName`, `string $endpoint`, `int $code = 0`, `?Throwable $previous = null`	Kapalı arızalama yardımcı bileşen kullanılamazlık sinyali	—	—	Herkese açık salt okunur `toolName` ve `endpoint`
`AiReadyCertifier::certify`	`string $pdfBytes`	Üç hazırlık ölçütünü değerlendirir; XMP köken bilgisini damgalar	`array{0: AiReadyCertification, 1: string}`	`InvalidArgumentException` (damgalama, klasik bir çapraz başvuru tablosu gerektirir)	Düzey `not_certified` olduğunda ikinci öge girdiye eşittir
`AiReadyCertification`	Salt okunur değer nesnesi	Düzey, ölçüt sayısı, sorunlar ve kaynak karması içeren hazırlık değerlendirmesi	—	—	Dahili hazırlık etiketi, bir standart sertifikasyonu değil
`XRechnungTestSuiteRunner::__construct`	`string $suitePath`, `ExternalValidator $validator`, `bool $useCuratedNegativeFallback = true`	Çıkarılmış paket dizinini çözümler	—	`InvalidArgumentException` (dizin mevcut değil)	Resmî KoSIT XRechnung test paketini hedefler
`XRechnungTestSuiteRunner::run`	`bool $stopOnFirstFailure = false`	Her paket örneğini köprü üzerinden doğrular	`XRechnungTestSuiteResult`	`XRechnungTestSuiteException` (doğrulayıcı kullanılamıyor; XML dosyası yok)	Ayrıca `isAvailable()`, `getSuitePath()`, `discoverTestFiles()`
`XRechnungTestSuiteResult`	Salt okunur değer nesnesi	Toplu paket sonucu	—	—	`allPassed()`, `totalCount()`, `getFailures()`, `getErrors()`, `toSummary()`
`XRechnungTestCaseResult`	Salt okunur değer nesnesi	Durum başına sonuç	—	—	`passed()`, `hasError()`, `getFilename()`
`XRechnungTestSuiteException`	Statik yapıcılar	Paket çalışma zamanı hata sinyali	`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;
}

Davranış sözleşmesi

ComplianceGateway::validate(), getToolName() değeri ComplianceProfile::toolName() ile eşleşen kayıtlı ExternalValidator öğesini çözümler, isAvailable() denetimini yapar, yetki devreder ve normalize edilmiş bir ExternalValidationResult döndürür. Dışarıdan gözlemlenebilen kurallar:

Kapalı arızalama varsayılanı. Çözümlenen yardımcı bileşen kullanılamıyorsa ve isteğe bağlı mod kapalıysa, çağrı ComplianceSidecarUnavailableException oluşturur. Belge denetlenmez; asla geçti olarak değerlendirilmez.
İsteğe bağlı mod. Ağ geçidini optional: true ile oluşturmak (operatörler bunu NEXTPDF_COMPLIANCE_OPTIONAL ortam değişkeninden bağlar), kullanılamayan bir yardımcı bileşeni, günlüğe kaydedilmiş bir uyarıya ve null dönüşüne indirger. Çağıranlar null değerini “denetlenmedi” olarak değerlendirmelidir. İsteğe bağlı mod yalnızca ön kullanılabilirlik yoklamasını kapsar; doğrulama çağrısının kendisi sırasındaki bir aktarım hatası, her iki modda da ComplianceSidecarUnavailableException oluşturur.
Bilinmeyen profil. Kayıtlı bir doğrulayıcısı olmayan bir profil, InvalidArgumentException oluşturur; asla sessizce geçmez.
Geçme semantiği. ExternalValidationResult::passes(), conformant değerinin true olmasını ve sıfır uygunsuzluk bulunmasını gerektirir. Her sonuç; profili, araç adını ve sürümünü, öne sürüm sayısını, bulguları, doğrulanan baytların SHA-256 değerini, bir UTC zaman damgasını ve çağrı süresini taşır.
Matris bir kayıttır, bir öne sürüm değil. buildComplianceMatrix(), izlenebilirlik için araç sürümleri ve bir commit SHA değeri içeren, şema sürümlü bir yapı üreten statik bir azaltıcıdır. Araç çıktısını kaydeder; hiçbir şey öne sürmez.
Veri akışı. Tam PDF bayt akışı, yapılandırılmış yardımcı bileşene bir PSR-18 istemcisi üzerinden iletilir. Her doğrulama; profil, araç, geçme/kalma, öne sürüm sayısı ve süre ile PSR-3 üzerinden günlüğe kaydedilir.

ComplianceProfile::standardReference() ve ::toolName() tarafından döndürüldüğü şekilde profil-araç yönlendirmesi:

Profil durumları	Standart başvuru	Araç
`pdfa-1b`, `pdfa-2b`, `pdfa-3b`, `pdfa-4`, `pdfa-4f`	ISO 19005-1/-2/-3/-4 (Düzey B; 4f için Düzey F)	veraPDF
`pdfua-1`, `pdfua-2`	ISO 14289-1:2014, ISO 14289-2:2024	veraPDF
`pdf20-arlington`	ISO 32000-2:2020 (Arlington modeli)	veraPDF
`pades-b-b`, `pades-b-t`, `pades-b-lt`, `pades-b-lta`	ETSI EN 319 142-1 B-B’den B-LTA’ya	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() üç ölçütü değerlendirir: yapısal imza varlığı, LTV sağlığı ve şifreleme yokluğu. Geçen üç ölçüt certified düzeyini verir; bir veya iki ölçüt partial verir; sıfır ölçüt not_certified verir. certified veya partial durumunda, bir XMP köken akışı ve bir Catalog geçersiz kılması taşıyan artımlı bir güncelleme ekler; özgün baytlar asla değiştirilmez. “certified” düzeyi, bir standart sertifikasyonu değil, NextPDF’e özgü dahili bir hazırlık etiketidir.

VeraPdfValidator yalnızca JSON yardımcı bileşen yanıtlarını ayrıştırır (XML yok; yapısı gereği XXE temizdir). KoSitValidator, arka plan hizmetinin XML SVRL raporunu DOCTYPE bildirimleri reddedilmiş ve ağ erişimi devre dışı bırakılmış olarak ayrıştırır ve ayrıştırılamayan bir raporu çağrının bir arızası olarak değerlendirir.

Uç durumlar ve arıza modları

Yardımcı bileşen zaman aşımı veya aktarım hatası, köprüden ComplianceSidecarUnavailableException olarak ortaya çıkar; kapalı arızalama varsayılanı geçerli olur.
200 olmayan bir yardımcı bileşen yanıtı, araca özgü bir bulguyla (örneğin VERAPDF-HTTP-ERROR) başarısız bir sonuç üretir; asla bir uygunluk geçişi değildir.
Hatalı biçimlendirilmiş bir yardımcı bileşen JSON veya XML gövdesi, bir uygunluk geçişi değil, çağrının bir doğrulama arızasıdır.
İmza içermeyen EU DSS sonuçları DSS-NO-SIGNATURES ile başarısız olur. TOTAL_PASSED dışında bir gösterge DSS-SIG-INVALID ile başarısız olur. Beklenen temelin altındaki bir imza düzeyi DSS-LEVEL-MISMATCH ile başarısız olur.
DssValidator, istek başına zaman aşımı bütçesini her istekte X-NextPDF-Timeout-Seconds başlığı aracılığıyla yayımlar; entegratörün PSR-18 istemcisi buna uymalıdır; böylece takılmış bir yardımcı bileşen çağıran iş parçacığını sınırsızca engelleyemez.
ZugferdExternalValidator, yardımcı bileşen çağrılarını isteğe bağlı olarak enjekte edilen bir devre kesici üzerinden yönlendirir; açık bir kesici ComplianceSidecarUnavailableException ile eşlenir (hızlı arızalama, yine de kapalı arızalama). Varsayılan, işlem yapmayan bir kesicidir.
KoSitValidator::isAvailable(), arka plan hizmeti sağlık yoklamasından HTTP 200 ve 405’i kabul eder; arka plan hizmeti sağlıklıyken GET’e 405 ile yanıt verir.
AiReadyCertifier damgalaması, özgün belge klasik bir çapraz başvuru tablosundan yoksun olduğunda (örneğin çapraz başvuru akışları), InvalidArgumentException ile kapalı arızalanır.
XRechnungTestSuiteRunner::run(), doğrulayıcı kullanılamadığında veya paket hiç XML dosyası içermediğinde çalışmayı reddeder; useCuratedNegativeFallback etkinken, paket hiç geçersiz örnek içermediğinde özenle hazırlanmış bir negatif külliyat ikame eder.

FIPS modu davranışı

Bu modül hiçbir imzalama ve hiçbir anahtar muhafazası yapmaz. FIPS modu algoritma politikası, Security ve Signature modülleri tarafından yönetilir. İmza uygunluğu, kendi belirlemesini yapan EU DSS’e devredilir.

Uygunluk

Ağ geçidi, uygunluk kararını harici bir araca devreder; bu tasarım, standartların kendi belirlediği sınırı yansıtır: uygunluk, bir üretici tarafından öne sürülerek değil, gereksinimlere göre belirlenir.

Davranış	Başvuru
Uyumlu işlemci yükümlülüğü; uygunluk standarda göre belirlenir	ISO 19005-4:2020 §5.2
PDF/A-4 dosya gereksinimleri ile üreticinin kendi beyanı	ISO 19005-4:2020 §6.6.4
PDF/UA-2 uyumluluğu dosyanın bir özelliğidir	ISO 14289-2:2024 §6
PAdES temel imza düzeyleri	ETSI EN 319 142-1 §5.4.3

Kararı harici araç üretir. NextPDF hiçbir sertifikasyon tutmaz ve hiçbiri vermez; bir profil için destek, ona uygunluk anlamına gelmez. Doğrulama sonuçları, hukuki görüş değil, başvuru amaçlı teknik yapı denetim kayıtlarıdır; düzenleyici yeterliliği değerlendirmek için uyumluluk ekibinize danışın.

Geliştirme notları

Operatör, yardımcı bileşenleri barındırır ve işletir, sürümlerini sabitler, ağ erişimlerini kısıtlar, TLS yapılandırmalarını doğrular ve isteğe bağlı modu etkinleştiren ortamı denetler. Yardımcı bileşen uç noktaları bir güven sınırıdır; belgeler, sonuçlar ve günlükler için yerleşim ve saklama denetimleri operatörün sorumluluğundadır.
buildComplianceMatrix() çıktısı CI izlenebilirliği için tasarlanmıştır: commit SHA değerini sabitleyin ve matrisi derleme yapıtlarının yanında arşivleyin.
XRechnung çalıştırıcısı, resmî test paketinin yerel bir dizine çıkarılmış olmasını bekler; yapıcı iletisi genel indirme kaynağını adlandırır.
İç mekanizma ayrıntısı, kaynak deposunun iç belgelerinde kalır ve bu kılavuzun kapsamı dışındadır.

Yayımlama sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilen davranışı ve desteklenen genel API yüzeyini belgeler. İç ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, runbook dosya adları ve bilet önekleri kapsam dışıdır.

Ayrıca bkz.

Compliance yeteneği genel bakışı
Validation — Derinlemesine başvuru
Evidence — Derinlemesine başvuru
Pro Compliance — süreç içi e-fatura (ayrı yüzey)
Core Conformance