Enterprise sürüm

Invoice — Derinlemesine başvuru

Bir bakışta

Invoice modülünün üç bağımsız yüzeyi vardır: gömme, doğrulama ve Schematron kural yürütme. ZugferdEmbedder ve PeppolEmbedder, çağıranın sağladığı fatura XML’ini bir PDF/A-4f veya PDF/A-3b taşıyıcısına ekler ve yapılandırılmış bir sonuç döndürür. InvoiceXmlValidator, seçilebilir COMPAT veya STRICT önem derecesiyle bir EN 16931 yapısal ön denetimi çalıştırır. SchematronValidator, önceden derlenmiş Schematron kural paketlerini süreç içinde yürütür ve SVRL bulgularını ayrıştırır. NextPDF, fatura XML’i üretmez; çağıran, yükü sağlar ve ona sahiptir.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Enterprise (nextpdf/enterprise) ile birlikte gelir ve bir Enterprise 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 bir lisans edinin.

Katman bazında ayrım: e-fatura algılama ve doğrulama, Pro katmanı yüzeyidir (Pro Compliance modülü). Karma fatura gömme, XRechnung CIUS profili ve süreç içi Schematron motoru yalnızca Enterprise’a özgüdür. nextpdf/enterprise paket sınırının ötesinde, özellik başına ayrı bir yetenek kodu yoktur.

Genel API yüzeyi

composer require nextpdf/enterprise:^3

Sembol	Parametreler	Varsayılan davranış	Döndürür	Şununla oluşur veya başarısız olur	Notlar
`ZugferdEmbedder::basic()`	`PdfAManager`, `FileAttachment`, `string $xmlData`	BASIC profili CII XML’ini gömer: XmlGuard geçişi, yapısal doğrulama, XMP şema enjeksiyonu, ek	`ZugferdEmbedResult`	`InvalidArgumentException`, `ZugferdEmbeddingException`	Hızlı yol; önerilen başlangıç noktası
`ZugferdEmbedder::minimum()`	`PdfAManager`, `FileAttachment`, `string $xmlData`	MINIMUM profilinde aynı işlem hattı	`ZugferdEmbedResult`	`InvalidArgumentException`, `ZugferdEmbeddingException`	Hızlı yol
`ZugferdEmbedder::create()`	`ZugferdProfile`, `string $xmlData`	Oluşturucu girişi; boş XML’i reddeder	`self`	`InvalidArgumentException`	`withoutValidation()`, `withDescription()` ile yapılandırın
`ZugferdEmbedder::withAfRelationship()` / `PeppolEmbedder::withAfRelationship()`	`AFRelationship\|string`	Varsayılan `/Alternative` ilişkisini geçersiz kılar; ilişkili dosya kural kitabıyla kapılanır	`self`	`InvalidArgumentException`	`Schema`, `EncryptedPayload`, `FormData` faturalar için reddedilir
`ZugferdEmbedder::embed()`	`PdfAManager`, `FileAttachment`	Sonlandırıcı oluşturucu çağrısı: XmlGuard, isteğe bağlı doğrulama, taşıyıcı denetimi, XMP, ekleme	`ZugferdEmbedResult`	`InvalidArgumentException`, `ZugferdEmbeddingException`	Doğrulama başarısızlığı ilk hatayı adlandırır
`ZugferdProfile` (enum)	—	Durumlar MINIMUM, BASIC_WL, BASIC, EN16931, EXTENDED, XRECHNUNG	—	—	XRECHNUNG `xrechnung.xml` ekler; CII profilleri `factur-x.xml` ekler
`ZugferdXmpSchema::apply()`	`XmpMetadata`, `ZugferdProfile`	Factur-X RDF açıklamasını ve PDF/A uzantı şeması girdisini kaydeder	`XmpMetadata`	Yok	`embed()` tarafından çağrılır; doğrudan da kullanılabilir
`PeppolEmbedder::invoice()` / `::creditNote()`	`PdfAManager`, `FileAttachment`, `string $ublXml`	Peppol BIS 3.0 UBL fatura veya alacak dekontu XML’ini gömer	`PeppolEmbedResult`	`InvalidArgumentException`, `PeppolEmbeddingException`	Varsayılan dosya adları `invoice.xml` / `creditnote.xml`
`PeppolEmbedder::create()`	`string $ublXml`, `string $filename = 'invoice.xml'`	Oluşturucu girişi; boş XML veya dosya adını reddeder	`self`	`InvalidArgumentException`	`withFilename()`, `withDescription()`, `withoutSanitization()` ile yapılandırın
`PeppolEmbedder::embed()`	`PdfAManager`, `FileAttachment`	XmlGuard geçişi, taşıyıcı denetimi, kural kitabı kapısı, ekleme	`PeppolEmbedResult`	`InvalidArgumentException`, `PeppolEmbeddingException`	Gömme sırasında taşıyıcı farkında kural kitabı yeniden denetimi
`InvoiceXmlValidator::validate()`	`string $xmlData`, `ZugferdProfile`, `?InvoiceValidatorMode`	EN 16931 yapısal ön denetimi; varsayılan olarak COMPAT önem derecesi	`InvoiceValidationResult`	İstisna oluşturmaz; başarısızlıklar hata bulguları olarak ortaya çıkar	Mod önce argümanı, sonra ortamı, sonra COMPAT’ı çözer
`InvoiceXmlValidator::isCrossIndustryInvoice()`	`string $xmlData`	CII yükleri için kök öğe ve ad alanı denetimi	`bool`	İstisna oluşturmaz; `false` döndürür	Ucuz algılama sondası
`InvoiceValidatorMode` (enum)	—	`COMPAT` (varsayılan), BT-24 bulgularını uyarıda tutar; `STRICT`, bunları hataya yükseltir	—	—	`fromEnvironment()`, ayarlanmamış veya tanınmayan değerlerde COMPAT’a geri döner
`InvoiceValidationResult` / `InvoiceValidationFinding`	—	Değişmez toplamlar: `isValid`, `getErrors()`, `getWarnings()`; bulgu başına düzey, kod, mesaj	—	—	`InvoiceValidationResult::fail()` tek bir hatayı sarmalar
`SchematronValidator::validate()`	`string $xsltPath`, `string $xmlData`	Önceden derlenmiş bir Schematron XSLT’sini yürütür; SVRL’yi bulgulara ayrıştırır	`SchematronResult`	Eksik veya okunamayan bir XSLT için `InvalidArgumentException`; motor başarısızlıkları bir hata sonucu döndürür	Zamanlama `durationMs` içinde yakalanır
`SchematronValidator::runRules()`	`string $xslPath`, `string $xmlPayload`	Katmanlar arası adaptör; hata bulgularını sözleşme `RuleViolation` nesnelerine eşler	`list<RuleViolation>`	`validate()` ile aynı	Bilgi düzeyi bulgular atlanır
`SchematronResult` / `SchematronFinding`	—	Karar, bulgular, süre; `getFailedAssertions()`, `getSuccessfulReports()`	—	—	`SchematronResult::error()`, motor başarısızlıklarını geçersiz olarak işaretler
`SchematronCacheInterface`	—	Kurcalama tespit eden önbellek sözleşmesi: `getVerified()`, `set()`, `computeKey()`	—	—	Özet uyuşmazlığında kapalı başarısız olur
`AtomicRenameSchematronCache`	`string $cacheDir`, `bool $atomicRename = true`, `LoggerInterface`	Atomik yeniden adlandırma yazmalı SHA-256 doğrulamalı dosya önbelleği	—	`InvalidArgumentException`, `SchematronCacheException`	Dizin var olmalı veya oluşturulabilir olmalı ve yazılabilir olmalıdır
`VersionPinRegistry`	`array $pins`, `?string $sourcePath`	SHA-256 kilitli kural paketi sabitlemeleri: `loadFromLockFile()`, `get()`, `verifyArtefact()`, `regenerateLockFile()`	—	Hatalı biçimli kilit JSON’unda `VersionPinException`, `InvalidArgumentException`, `JsonException`	Boş veya hatalı biçimli özetler kapalı başarısız olur
`InvoiceContractValidator`	`?SemanticValidator`	Katmanlar arası `ValidatorInterface` adaptörü; yapısal ön denetim artı EN 16931 derin semantik kuralları	`ContractResult`	Kapalı başarısız olur; motor hataları hata bulguları olarak ortaya çıkar	`nextpdf/premium` kuruluyken framework yollarına bağlanır
`ZugferdContractEmbedder`	`FacturXContractEmbedder`	Katmanlar arası `EmbedderInterface` adaptörü; bayt-giriş / bayt-çıkış gömme	`string` (PDF baytları)	Temsilci başarısızlıklarını yayar	Pro katmanı bayt yeniden yazma motoruna devreder
`ZugferdEmbeddingException`, `PeppolEmbeddingException`, `SchematronCacheException`, `VersionPinException`	—	Modül başarısızlık taksonomisi	—	—	Tümü `RuntimeException`’ı genişletir

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

Davranış sözleşmesi

Gömme. ZugferdEmbedder, çağıranın sağladığı bir ZUGFeRD 2.4 / Factur-X 1.08 UN/CEFACT CII XML yükünü bir PDF/A taşıyıcısına ekler. İki taşıyıcıyı destekler: tercih edilen modern taşıyıcı olan PDF/A-4f (ISO 19005-4:2020) ve geriye dönük uyumluluk için PDF/A-3b (ISO 19005-3:2012). embed(), her zaman önce bir XmlGuard güvenlik geçişi çalıştırır, ardından withoutValidation() ayarlanmadıysa yapısal doğrulama yapar, sonra taşıyıcının gömülü dosyaları desteklediğini doğrular, ZugferdXmpSchema aracılığıyla XMP uzantı şeması bildirimini enjekte eder ve XML’i ilişkili dosya olarak ekler. Ek ilişkisi, varsayılan olarak kural kitabı önerisi /Alternative’dir; geçersiz kılmalar, ISO 32000-2:2020 §14.13 ilişki kümesini ve EN 16931 fatura alt kümesini zorunlu kılan aynı kural kitabından geçer. PeppolEmbedder, çağıranın sağladığı Peppol BIS Billing 3.0 UBL 2.1 fatura veya alacak dekontu XML’i için eşdeğerini gerçekleştirir. İki gömücü de fatura XML’i üretmez.

Doğrulama. InvoiceXmlValidator, CII XML’ini EN 16931 yapısal beklentilerine göre denetler: kök öğe, gerekli bölümler, başlık kardinalitesi, profilin gerektirdiği yerlerde satır kalemleri ve BR-1 iş kuralı tarafından zorunlu kılınan BT-24 belirtim tanımlayıcısı. InvoiceValidatorMode, önem derecesini seçer. COMPAT (varsayılan), eksik veya uyumsuz bir BT-24’ü uyarı olarak raporlar; böylece boole bir geçerlilik kapısı gerilemez. STRICT, bunu bir sert hata yapar ve ayrıca harici KoSIT / Mustang doğrulayıcı semantiğini yansıtarak profil tutarlılığını bildirilen ZugferdProfile’a göre doğrular. Mod şu sırayla çözülür: açık argüman, ardından INVOICE_VALIDATOR_MODE ortam geçersiz kılması, ardından COMPAT. Sonuçlar, yapılandırılmış InvoiceValidationResult / InvoiceValidationFinding nesneleridir; doğrulayıcı, istisna oluşturmak yerine bulgular döndürür.

Schematron. SchematronValidator, önceden derlenmiş Schematron kural kümelerini — derleme zamanında XSLT’ye derlenmiş CEN EN 16931 .sch kuralları — süreç içi PHP XSLT işlemcisini kullanarak yürütür. SVRL raporunu SchematronFinding / SchematronResult nesnelerine ayrıştırır: başarısız savlar hata bulguları, başarılı raporlar bilgi bulguları olur. İsteğe bağlı bir önbellek (SchematronCacheInterface, atomik yeniden adlandırma dosya uygulamasıyla), içerik özeti artı derleyici sürümüyle anahtarlanan doğrulanmış stil sayfası baytlarını sunar. VersionPinRegistry, her harici kural paketini SHA-256 kilitli bir sürüme sabitler ve kayma veya hatalı biçimli özetlerde kapalı başarısız olur.

Bu modül, yapılandırılmış fatura verisi üretir ve denetler. Herhangi bir belgenin hukuken uyumlu bir fatura olduğunu, vergi otoritesince onaylandığını veya herhangi bir otorite tarafından kabul edileceğinin garanti olduğunu öne sürmez. Doğrulayıcı yalnızca EN 16931 semantik modelini ve ZUGFeRD / Factur-X / UBL kapsayıcısını denetler; ulusal uzantıları (örneğin İtalyan SDI, Fransız Chorus Pro, Alman XRechnung taşıması) dışında tutar. EN 16931-1’in belirttiği gibi, fatura düzenleyicisi ilgili mevzuat kurallarını karşılamaktan sorumludur; bu bir vergi otoritesi doğrulayıcısı değildir. Bir standart için destek, ona uygunluk anlamına gelmez.

Uç durumlar ve başarısızlık modları

Boş XML hızla başarısız olur: oluşturucular InvalidArgumentException oluşturur; InvoiceXmlValidator::validate(), başarısız bir sonuç döndürür.
XmlGuard, DOCTYPE bildirimlerini, varlık açmayı, aşırı büyük yükleri ve kontrol karakterlerini reddeder. Gömücüler bunu, neden korunarak ZugferdEmbeddingException veya PeppolEmbeddingException olarak ortaya çıkarır.
withoutValidation() ve withoutSanitization(), XmlGuard güvenlik geçişini asla atlamaz. Yalnızca yapısal iş terimi denetimleri atlanabilir.
Gömülü dosya desteği olmayan bir taşıyıcı (PDF/A-4f veya PDF/A-3b dışında herhangi bir şey), kabul edilen sürümleri adlandıran bir InvalidArgumentException oluşturur.
İzin verilmeyen bir AFRelationship değeri, oluşturucu sınırında reddedilir; embed() içinde taşıyıcı farkında bir kural kitabı yeniden denetimi tekrar çalışır.
COMPAT, eksik bir BT-24’ü uyarı önem derecesinde tutar; STRICT, eksik ve profille uyumsuz BT-24 değerlerini sert hata yapar.
SchematronValidator, yalnızca eksik veya okunamayan bir XSLT yolu için istisna oluşturur. Dönüşüm veya SVRL ayrıştırma başarısızlıkları, isValid false ile SchematronResult::error() döndürür.
Depolanan baytları özet doğrulamasında başarısız olan bir önbellek girdisi çıkarılır ve stil sayfası diskten yeniden okunur; zehirlenmiş baytlar asla döndürülmez.
XSLT işlemcisi, dosya ve ağ kaynağı yüklemesi engellenmiş olarak çalışır ve asla PHP işlevleri kaydetmez; document(), xsl:include, xsl:import ve result-document kaynak yükleyemez.
VersionPinRegistry, alım sırasında ve yeniden oluşturmada boş veya hatalı biçimli SHA-256 özetlerini reddeder; verifyArtefact(), doğrulanamayan bir sabitlemeyi geçirmek yerine false döndürür.
Bu modül hiçbir kriptografik imzalama gerçekleştirmez; FIPS modu davranışı burada kapsam dışıdır (Signature modülüne bakın).

Uygunluk

Davranış	Başvuru	Durum
Temel fatura semantik modeli	EN 16931-1:2026 §4	Karşı geliştirildi; düzenleyici sorumlu kalır
Belirtim tanımlayıcısı (BT-24)	EN 16931-1:2026 BR-1	COMPAT’ta uyarı, STRICT’te hata
UN/CEFACT CII söz dizimi bağlaması	CEN/TS 16931-3-3:2020	Gömme destekleniyor
UBL 2.1 söz dizimi bağlaması	CEN/TS 16931-3-2:2020	Gömme destekleniyor
PDF/A-3 ilişkili dosya	ISO 19005-3:2012 §6.7.8	Taşıyıcı destekleniyor
PDF/A-4f gömülü dosya	ISO 19005-4:2020 Annex A	Taşıyıcı destekleniyor
İlişkili dosya ilişki değerleri	ISO 32000-2:2020 §14.13	Kural kitabıyla kapılanır
Schematron / SVRL rapor ayrıştırma	ISO/IEC 19757-3	Karşı geliştirildi (ürün temelli; standart atıf külliyatında değil)

Karşı geliştirilmiştir; bir sertifikasyon veya vergi otoritesi onayı değildir. NextPDF, bu standartların hiçbiri için sertifikasyon tutmaz. NextPDF, EN 16931 veri modeline uygun yapılandırılmış faturalar üretir ve kural bulgularını raporlar; hukuken uyumlu faturalar üretmez, vergi otoritesince onaylanmış çıktı sağlamaz veya kabulü garanti etmez. Vergi ve hukuk danışmanlarınıza başvurun.

Geliştirme notları

Schematron motoru ext-xsl PHP uzantısını gerektirir; bunu sağlamak ve etkinleştirmek operatörün sorumluluğundadır.
İşleme, süreç içinde ve yereldir. Gömme veya doğrulama sırasında giden ağ çağrısı gerçekleşmez. Ulusal e-faturalama taşıması, takas platformları ve arşivleme sistemleri bu modülün dışındadır.
Kural paketleri, derleme zamanında .sch’den XSLT’ye derlenir; çalışma zamanı yalnızca önceden derlenmiş stil sayfalarını yürütür.
Önbellek anahtarları, derleyici sürümü tuzunu (şu anda nextpdf-schxslt-1.0) içerir; bunu artırmak, bir temizleme adımı olmadan dağıtılmış önbellekleri geçersiz kılar.
Kural paketi sabitlemeleri, enterprise/config/invoice-versions.lock konumundaki kilit dosyasında bulunur (VersionPinRegistry::DEFAULT_LOCK_PATH); CI, dağıtılmış yapıtları sabitlenmiş özetlere göre doğrular.
Katmanlar arası çağıranlar InvoiceContractValidator ve ZugferdContractEmbedder kullanır; katmana özgü Enterprise çağıranlar doğrudan ZugferdEmbedder ve InvoiceXmlValidator kullanır.

Yayımlama 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ı, runbook dosya adları ve bilet önekleri kapsam dışıdır.

Ayrıca bkz.

Invoice yeteneği — bu başvurunun yetenek karşılığı.
Pro Compliance — Pro katmanı algılama/doğrulama.
Document E-Filing
Enterprise genel bakışı