Pro sürüm

Compliance — Derinlemesine başvuru

Bir bakışta

Compliance modülü, NextPDF\Pro\Compliance altında üç bağımsız yüzeyi bir araya getirir:

Dil etiketi raporlama — sıkı bir PDF/UA-2 /Lang politika cephesi artı yapılandırılmış, PSR-3 biçimli bir uygunluk olayı raportörü.
E-fatura işleme — EN 16931 anlamsal modeline karşı Factur-X 1.08 / ZUGFeRD 2.4 doğrulaması ve hibrit PDF/A-3 üretimi.
Köken — çekişmeli sertleştirilmiş bir JUMBF ayrıştırıcısı aracılığıyla çağıran tarafından sağlanan C2PA bildiri depolarını gömer ve çıkarır; iddia sentezi önizleme kapısında kalır.

Modül, denetlediğini raporlar. Belgeleri sertifikalandırmaz ve kriptografik imzalama yapmaz.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) ile gelir ve Pro katmanı lisans zarfıyla etkinleşir. Bu yetkilendirmeye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve lisans edinin.

Özellik başına lisans bayrağı yoktur. Bu bir Pro sürümü yeteneğidir. Deneysel C2PA iddia oluşturucusu, ayrıca açık bir ortam onayı gerektirir (bkz. Uç durumlar ve arıza modları).

Genel API yüzeyi

composer require nextpdf/pro:^3

Sembol	Parametreler	Varsayılan davranış	Döndürür	Fırlatır veya şununla başarısız olur	Notlar
`LangComplianceReporter::warn()` / `::error()`	`string $tag, string $reason, ?string $clauseReference = null`	PSR-3 günlükleyicisi aracılığıyla dil etiketi olayı başına bir yapılandırılmış JSON kaydı yayar	`void`	Kayıt JSON kodlamada başarısız olursa `JsonException`	`warn` = gevşek mod reddi; `error` = sıkı mod reddi
`LangComplianceReporter::reportException()`	`InvalidBcp47TagException $exception, string $severity = 'error'`	Etiketi ve nedeni istisnadan çıkarır; `warn()` veya `error()`’a devreder	`void`	Yukarıdaki gibi	Kolaylık yolu
`LangComplianceReporter::buildRecord()`	`string $severity, string $tag, string $reason, ?string $clauseReference = null`	Kayıt dizisini günlüğe kaydetmeden oluşturur	`array`	Fırlatmaz	Dosya başına JSON özetleri gibi özel alıcılar için
`ConformancePolicy::default()`	`?LoggerInterface $logger = null`	Sıkı UA-2 politikası: hatalı biçimlendirilmiş veya kayıtlı olmayan `/Lang` etiketleri reddedilir	`self`	Fırlatmaz	v5.0 varsayılanı sıkıdır
`ConformancePolicy::fromCore()`	`CoreConformancePolicy $core, ?LoggerInterface $logger = null`	Mevcut bir Core politikasını olduğu gibi sarar; hiçbir eksen değiştirilmez	`self`	Fırlatmaz	Sıkı duruş için `default()`’u tercih edin
`ConformancePolicy::withStrictUa2()`	`bool $enabled`	Sıkı eksen ayarlanmış bir kopya döndürür; devre dışı bırakma bir PSR-3 `notice` yayar	`self`	Fırlatmaz	Deprecated devre dışı bırakma; kaldırma hedefi `6.0.0`
`ConformancePolicy::isStrictUa2()` / `::mode()`	—	Temel Core politikasını okur	`bool` / `ConformanceMode`	Fırlatmaz	—
`EInvoiceValidator::validate()`	`string $pdfPath`	Tam işlem hattı: PDF/A-3 sarmalayıcı denetimi, ek çıkarma, profil algılama, EN 16931 kuralları, Schematron	`EInvoiceValidationResult`	G/Ç hatası, hatalı biçimlendirilmiş PDF yapısı veya araç çökmesi durumunda `EInvoiceException` alt sınıfı	Dondurulmuş SPI arabirimi; iyi biçimlendirilmiş, e-fatura olmayan bir PDF bir sonuç döndürür, asla fırlatmaz
`EInvoiceXmlValidator::validate()`	`string $xmlPayload, ValidatorContext $context`	Bir CII yükü üzerinde yapısal ön denetim artı EN 16931 derin anlamsal kural külliyatı	sözleşme `ValidationResult`	Geçersiz giriş için fırlatmaz; ret, bulgularla birlikte başarısız bir sonuç olarak ortaya çıkar	Somut katmanlar arası doğrulayıcı; giriş `XmlGuard` aracılığıyla kapılanır
`EInvoiceValidationResult::isValid()`	—	Yalnızca sarmalayıcı, ek belirtimi, profil, sözdizimi geçerli olduğunda ve hiçbir FATAL ihlal bulunmadığında doğru	`bool`	Fırlatmaz	Boş ihlal listesi tek başına geçerlilik değildir
`EInvoiceValidationResult::notAnEInvoice()`	—	Belirlenimci tümü-null, tümü-false sonuç	`self`	Fırlatmaz	”Hibrit fatura değil” durumu için fabrika
`EInvoiceProfile`	string destekli enum	`MINIMUM`, `BASIC_WL`, `BASIC`, `EN16931`, `EXTENDED` durumları, BT-24 URN’leriyle desteklenir	—	—	`isEn16931Conformant()`, `MINIMUM` ve `BASIC_WL` için false’tur
`EInvoiceSyntax`	string destekli enum	`UN_CEFACT_CII`, `UBL_INVOICE`, `UBL_CREDIT_NOTE` durumları	—	—	Yalnızca CII `isFacturXEligible()`’dir; UBL yalnızca doğrulayıcıdır
`BusinessRuleViolation`	`string $ruleId, BusinessRuleSeverity $severity, string $message, ?string $xpath = null, ?string $ramPath = null`	Değişmez ihlal DTO’su	—	—	Kural kimliği aileleri `BR-`, `BR-CO-`, `BR-CL-`, `BR-DEC-`, `BR-FXEXT-`
`BusinessRuleSeverity`	string destekli enum	`FATAL` faturayı geçersiz kılar; `WARNING` bir kalite endişesini işaretler	—	—	EN 16931 Schematron düzeylerini yansıtır
`FacturXEmbedder::embed()`	imza bloğuna bakın	Bir PDF/A kaynağına gömülü dosya akışı, dosya belirtimi ve XMP ekler; xref’i yeniden yazar	`void`	Hatalı biçimlendirilmiş XML, okunamayan kaynak, eksik katalog, nesne akışı veya xref akışı kaynağı ya da çıktı yazma hatası durumunda `EInvoiceException`	Kaynak dosya olduğu gibi bırakılır
`FacturXEmbedderOptions::default()`	—	`/AFRelationship /Alternative`, dosya adı `factur-x.xml`, tür `INVOICE`, sürüm `1.0`	`self`	Fırlatmaz	Varsayılanlar Alman zorunluluğunu karşılar ve Fransa’da kabul edilir kalır
`FacturXEmbedderOptions::withRelationship()` / `::withFilename()`	`string`	Geçersiz kılma uygulanmış bir kopya döndürür	`self`	Kabul kümelerinin dışında `InvalidArgumentException`	İlişkiler: `Source`, `Data`, `Alternative`; dosya adları `zugferd-invoice.xml` ve `xrechnung.xml`’i içerir
`FacturXEmbedderOptions::withDocumentType()`	`string $documentType`	XMP belge türü geçersiz kılması uygulanmış bir kopya döndürür	`self`	Fırlatmaz	Değerler savunmacı biçimde numaralandırılmaz
`FacturXContractEmbedder::embed()`	`string $pdfBytes, string $xmlPayload, EmbedderOptions $options`	Kısa ömürlü geçici dosyalar aracılığıyla `FacturXEmbedder` üzerinde bayt-giriş, bayt-çıkış bağdaştırıcısı	`string`	`EInvoiceException`; `XRECHNUNG` profili yalnızca Enterprise olduğu için reddedilir	Katmanlar arası `EmbedderInterface` uygulaması
`C2paManifestEmbedder::embed()`	`string $pdfBytes, ManifestStore $store`	Deponun bayt serileştirmesini profil konumuna gömer	`string`	Herhangi bir gömme hatasında `C2paException`	Dondurulmuş SPI arabirimi; yalnızca bayt, G/Ç yok
`C2paManifestEmbedder::extract()`	`string $pdfBytes`	Gömülü bir depoyu sertleştirilmiş JUMBF ayrıştırıcısı aracılığıyla ayrıştırır	`ManifestStore\|null`	Bir depo mevcut olduğunda ancak bir sertleştirme sınırını aştığında `C2paException` alt sınıfı	Null yokluğu belirtir; yokluk asla fırlatmaz
`ManifestStore::fromBoxes()` / `::empty()`	`list<JumbfBox>` / —	Değişmez depo değer nesnesini oluşturur	`self`	Fırlatmaz	Kutu sırası, gidiş-dönüş eşitliği için taşıyıcıdır
`ManifestStore::toBytes()` / `::isEmpty()` / `::size()`	—	Kök kutuları serileştirir; boş depo boş bir dizeye serileştirilir	`string` / `bool` / `int`	Fırlatmaz	—
`JumbfBoxParser::parse()`	`string $bytes`	Kök düzeyindeki JUMBF kutularını katı sınırlar altında ayrıştırır	`list<JumbfBox>`	`MalformedJumbfException`, `JumbfBombException`, `JumbfCycleDetectedException`, `JumbfDepthExceededException`	Sınırlar: derinlik 8, kutu başına 64 MiB, toplam 128 MiB, `MAX_CHILDREN_PER_SUPERBOX` 4096
`JumbfBox::superbox()` / `::leaf()`	`string $tbox, …`	Doğrulanmış bir kutu oluşturur; `toBytes()` ayrıştırıcı aracılığıyla gidiş-dönüş yapar	`self`	TBox tam olarak 4 bayt olmadığında `MalformedJumbfException`	—
`C2paCapabilityStatus::current()` / `::summary()`	—	C2PA yetenek olgunluğunu raporlar, şu anda `preview-draft`	`self` / `string`	Fırlatmaz	Makine tarafından denetlenebilir önizleme işaretçisi
`Feature::PREVIEW_C2PA_DRAFT->isEnabled()`	—	Her çağrıda süreç ortamını okur; yalnızca sabit `'1'` etkinleştirir	`bool`	Fırlatmaz	Ortam değişkeni `NEXTPDF_FEATURE_PREVIEW_C2PA_DRAFT`
`ExperimentalC2paEmbedder::buildManifestStore()`	`string $sourceBytes, string $producer`	Bir SHA-256 karma bağlama iddia beyanıyla taslağa sabitlenmiş bir bildiri deposu oluşturur	`ManifestStore`	Önizleme bayrağı kapalıyken kurucu `LogicException` fırlatır	Önizleme; tel biçimi bir taslak anlık görüntüsüne sabitlenir; iddia imzası yayılmaz

Giriş noktası imzaları, kelimesi kelimesine:

public static function default(?LoggerInterface $logger = null): self
public function withStrictUa2(bool $enabled): self
public function isStrictUa2(): bool

public function validate(string $pdfPath): EInvoiceValidationResult

public function embed(
    string $sourcePdfPath,
    string $xml,
    EInvoiceProfile $profile,
    string $outputPdfPath,
    ?FacturXEmbedderOptions $options = null,
): void

public function embed(string $pdfBytes, ManifestStore $store): string
public function extract(string $pdfBytes): ?ManifestStore

Davranış sözleşmesi

Dil etiketi raporlama. LangComplianceReporter, PDF/UA-2 dil etiketi olayı başına bir yapılandırılmış JSON kaydı yayar. Her kayıt; sabit olay ayırıcısını, bir önem derecesini (gevşek modda ret için warn, sıkı modda ret için error), kusurlu etiketi kelimesi kelimesine, makine tarafından okunabilen bir nedeni, ayrıştırılmış etiket bileşenlerini (veya etiket RFC 5646 biçim dilbilgisinde başarısız olduğunda null), bir ISO 14289-2 §8.4.4 kural referansını ve mikrosaniyeli bir UTC zaman damgasını taşır. JSON, PSR-3 mesaj gövdesi olarak taşınır; aşağı akış alıcıları mesaj alanını doğrudan ayrıştırır. ConformancePolicy, Core uygunluk politikası üzerindeki Premium cephesidir. Varsayılanı, sıkı UA-2 dil işlemeyi uygular ve /Lang’a ulaşan hatalı biçimlendirilmiş veya kayıtlı olmayan bir etiketi reddeder. Devre dışı bırakma yardımcısı withStrictUa2(false), eski gevşek davranışa döner ve etkin değer gerçekten değiştiğinde bir PSR-3 bildirimi günlüğe kaydeder. NextPDF, o yardımcıyı v5.0’dan beri 6.0.0 kaldırma hedefiyle deprecated olarak işaretler. Geçiş yapmak için: külliyatı hatalı biçimlendirilmiş /Lang değerleri açısından composer pdfua2:audit-lang-tags <pdf-or-dir> ile denetleyin, bunları düzeltin, ardından devre dışı bırakma çağrısını kaldırın.

E-fatura işleme. EInvoiceValidator, hibrit PDF doğrulaması için dondurulmuş SPI sözleşmesidir: PDF/A-3 sarmalayıcı denetimi, /AF ek çıkarma, BT-24 belirtim tanımlayıcısından profil algılama, EN 16931 iş kuralı motoru ve bir Schematron geçişi. İyi biçimlendirilmiş, Factur-X olmayan bir PDF, fırlatmak yerine EInvoiceValidationResult::notAnEInvoice() döndürür; yalnızca G/Ç hataları, hatalı biçimlendirilmiş PDF yapısı veya araç çökmeleri bir EInvoiceException alt sınıfı yükseltir. EInvoiceXmlValidator, somut katmanlar arası XML doğrulayıcısıdır: girişi Core XmlGuard aracılığıyla kapılar, yapısal ön denetimi ve derin EN 16931 anlamsal kural külliyatını çalıştırır ve kapalı biçimde başarısız olur — motor hataları asla sessiz geçişler olarak değil, hata bulguları olarak ortaya çıkar. FacturXEmbedder, bir PDF/A kaynağını hibrit bir PDF/A-3’e dönüştürür: bir gömülü dosya akışı, yapılandırılabilir bir /AFRelationship’e sahip bir dosya belirtimi ve bir Factur-X XMP uzantı paketi ekler, ardından klasik çapraz başvuru tablosunu yeniden yazar. Hem katalog /AF dizisi hem de /Names /EmbeddedFiles ad ağacı eke başvurur, böylece eski ZUGFeRD okuyucuları onu çözümler.

Köken. C2paManifestEmbedder, çağıran tarafından sağlanan bir C2PA bildiri deposunu bir PDF bayt dizesine gömer veya birini çıkarır. ManifestStore, sınırı geçen değişmez değer nesnesidir. Bu yüzey yalnızca bayt tabanlıdır ve satıcıdan bağımsızdır: iddiaları sentezlemez, URI referanslarını içe almaz veya karma bağlamalarını çözümlemez ve hiçbir ağ veya dosya sistemi G/Ç’si gerçekleştirmez. extract(), bir kaçırmada null döndürür ve deposuz PDF’lerde ucuzdur. Null olmayan her çıkarma, JumbfBoxParser sertleştirme sınırlarını zaten geçmiştir.

Bu modül denetlediğini raporlar. Bir belgeyi sertifikalandırmaz, onu hukuken bağlayıcı kılmaz veya herhangi bir çıktının bir yönetmeliği karşıladığını garanti etmez. E-fatura doğrulayıcısı bir vergi dairesi doğrulayıcısı değildir ve ulusal genişletmeleri hariç tutar (örneğin İtalyan SDI, Fransız Chorus Pro, Alman XRechnung). EN 16931-1’de belirtildiği gibi, fatura düzenleyen, ilgili mevzuatın kurallarını karşılamaktan sorumlu kalır. Bir standart için destek, ona uygunluk değildir. Düzenleyici yeterlilik için uyumluluk ekibinize danışın.

Uç durumlar ve arıza modları

İyi biçimlendirilmiş, Factur-X olmayan bir PDF, bir “e-fatura değil” sonucu döndürür; fırlatmaz.
Boş bir iş kuralı ihlali listesi, tek başına belgenin geçerli olduğu anlamına gelmez; sarmalayıcı ve ek denetimleri de geçerlidir.
FacturXEmbedder, sıkıştırılmış nesne akışları (/Type /ObjStm) veya çapraz başvuru akışları (/Type /XRef, hibrit /XRefStm) kullanan kaynaklarda kapalı biçimde başarısız olur. Bu tür kaynakları önce klasik bir çapraz başvuru tablosuyla yeniden kaydedin.
XML yükleri Core XmlGuard aracılığıyla kapılanır: DOCTYPE veya varlık bildirimleri, aşırı büyük giriş ve geçersiz UTF-8, gömme yolunda bir EInvoiceException ile ya da doğrulayıcı yolunda başarısız bir sonuçla reddedilir.
FacturXContractEmbedder, XRECHNUNG profilini sessizce alt sürüme düşürmek yerine yüksek sesle reddeder; XRechnung üretimi bir Enterprise yeteneğidir.
C2paManifestEmbedder::extract(), yokluğu (null), hatalı biçimlendirmeden (ihlal edilen değişmezi adlandıran C2paException alt sınıfı: hatalı biçimlendirilmiş yapı, boyut veya sayı bombası, ofset döngüsü, iç içe geçme derinliği) ayırt eder.
ExperimentalC2paEmbedder yapımı, önizleme ortam bayrağı '1'’e eşit olmadıkça bir LogicException fırlatır. Tel biçimi bir C2PA taslak anlık görüntüsüne sabitlenir ve haber verilmeden değişebilir; hiçbir iddia imzası yaymaz. Bu yetenek, C2PA PDF profili dondurulana kadar önizleme olarak kalır.
Sıkı UA-2 gevşek devre dışı bırakma deprecated’dir; sıkı varsayılana geçin (bkz. Davranış sözleşmesi).
Bu modül kriptografik imzalama yapmaz. C2PA iddia imzalama ve anahtar muhafazası kapsam dışıdır; FIPS modu imzalama davranışı için Security modülüne bakın.

Uygunluk

Davranış	Başvuru	Durum
Doğal dil bildirimi (`/Lang`)	ISO 14289-2:2024 §8.4.4	Denetlendi / raporlandı
Çekirdek fatura anlamsal modeli	EN 16931-1:2026	Denetlendi (düzenleyen sorumlu kalır)
İlişkili dosyalar / gömülü dosya akışları	ISO 32000-2:2020 §14.13.2	Üretildi (`/AF`, `/EF`, `/Params`)
Ek ilişkisi ve kapsayıcı kuralları	Factur-X 1.08 §3.1, §6.2	Üretildi / denetlendi (varsayılan `/AFRelationship /Alternative`)
C2PA bildiri deposu / JUMBF	C2PA 2.1 §11.1	Gömme / çıkarma desteklenir; iddia sentezi önizleme

Bu, modülün karşı geliştirildiği belirtimleri ve neyi denetlediğini ya da ürettiğini kaydeder. Bir sertifikasyon veya düzenleyici yeterlilik beyanı değildir. NextPDF, bu standartlar için hiçbir sertifikasyona sahip değildir.

Geliştirme notları

Raportörün kayıt biçimi kararlı bir sözleşmedir; aşağı akış uyarı kuralları sabit olay ayırıcısına sabitlenebilir.
Sıkı UA-2’yi devre dışı bırakmak, yalnızca etkin değer değiştiğinde telemetride görünür bir kullanımdan kaldırma bildirimi yayar; geçerli değeri yeniden onaylamak sessizdir.
Factur-X gömücüsü, kaynak baytları kelimesi kelimesine korur ve yeni nesneler ekler; PDF/A-3 uygunluğunu korumayı amaçlar ancak yeniden doğrulamaz. Kesin doğrulama için çıktıyı harici bir PDF/A doğrulayıcısından geçirin.
C2PA yüzeyi beş değişmezi dondurur: üçüncü taraf içe aktarma yok, yalnızca bayt sözleşmesi, G/Ç yok, kaçırmada-null çıkarma ve kararlı katmanda iddia sentezi yok.
JumbfBoxParser sınırları genel sabitlerdir; sınırları yeniden türetmek yerine kabul ettiğiniz girişleri bunlara göre boyutlandırın.

Yayın sınırı

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