ZUGFeRD / Factur-X uyumluluğu: gömülü EN 16931 fatura profili

Bir bakışta

Kapsam beyanı. NextPDF gömülü XML profilini üretir; mali ve hukuki geçerliliğe kütüphane değil, alıcı makam karar verir.

ZUGFeRD / Factur-X melez bir faturadır: insan tarafından okunabilen bir PDF (bir PDF/A-3 arşiv tabanı) ile EN 16931 anlamsal veri modelini izleyen, makine tarafından okunabilen gömülü bir Cross-Industry-Invoice (CII) XML’inden oluşur. NextPDF Core, gömme sözleşmesini sağlar (NextPDF\Contracts\EInvoice); somut Factur-X 1.08 motoru ise Premium nextpdf/pro paketinde sunulur. Kütüphane, gömülü XML’i ve PDF/A-3 ek dosya yapısını üretir. Mali geçerliliğe bir EN 16931 / Schematron doğrulayıcısı veya alıcı vergi makamı karar verir.

Kurulum

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

Core, EmbedderInterface, ProfileInterface, ProfileType, ValidatorInterface ve ValidationResult öğelerini NextPDF\Contracts\EInvoice içinde sağlar. Arabirimin docblock’u bunu açıkça belirtir: bu sözleşmeyi Pro katmanı (Factur-X 1.08 byte-rewrite motoru) ve Enterprise katmanı (PDF/A yönetimli oluşturucu) gerçekler. Core tek başına bir faturayı gömmez. Bu katmanların karşıladığı byte-in/byte-out sözleşmesini tanımlar.

Kavramsal genel bakış

NextPDF\Contracts\EInvoice\ProfileType, EN 16931 uyumluluk ayırıcısıdır: MINIMUM, BASIC_WL, BASIC, EN16931, EXTENDED, XRECHNUNG. isEn16931Conformant() metodu, kuralı doğrudan EN 16931-1’e göre kodlar. MINIMUM ve BASIC_WL EN 16931 uyumlu değildir (BT-24 belirtim tanımlayıcısının kardinalitesini ve satır kalemi gereksinimini karşılamazlar). BASIC, EN16931, EXTENDED, XRECHNUNG ise EN 16931 uyumludur.

Gömücü (EmbedderInterface) sözleşme gereği şunları yapar:

sağlanan CII XML’ini XmlGuard üzerinden ayrıştırır (XXE’ye karşı güvenli);
bildirilen profil için Factur-X XMP uzantı şemasını ekler;
XML’i, doğru AFRelationship (Data / Alternative) ile gömülü bir dosya olarak ekler; böylece PDF/A-3 arşiv tabanı (§6.7.5 gömülü dosya gereksinimleri — F/UF anahtarları) onu taşır.

NextPDF bu yapıyı üretir. Faturanın mali açıdan geçerli olduğunu öne sürmez. Bu belirlemeyi, EN 16931 §7 iş kurallarına ve varsa ulusal CIUS’a göre alıcı makam yapar.

API yüzeyi

Sembol	Etki
`Contracts\EInvoice\EmbedderInterface`	Byte-in/byte-out sözleşmesi; bunu Pro/Enterprise gerçekler.
`Contracts\EInvoice\ProfileType` (enum)	EN 16931 profil ayırıcısı.
`ProfileType::isEn16931Conformant(): bool`	MINIMUM/BASIC_WL için false; BASIC/EN16931/EXTENDED/XRECHNUNG için true.
`Contracts\EInvoice\ValidatorInterface`	Kural ihlallerini içeren bir `ValidationResult` döndüren doğrulama sözleşmesi.

Kod örneği — hızlı başlangıç

<?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";

Kod örneği — üretim

Üretim hattı (Pro katmanı), CII XML’ini bir PDF/A-3 tabanına gömer. Ardından bir EN 16931 Schematron doğrulayıcısı çalıştırır veya alıcı makama gönderir ve ilgili raporu geçiş koşulu olarak ele alır. NextPDF gömülü XML’i ve PDF/A-3 ek dosya yapısını üretir; mali geçerliliğe doğrulayıcı veya makam karar verir. Core tek başına bu hattı çalıştıramaz. Gömme motoru için nextpdf/pro gereklidir.

Uç durumlar ve dikkat edilecekler

Core yalnızca sözleşmeleri içerir. nextpdf/pro olmadan somut bir gömücü yoktur. Çağıran kod, arabirime bağımlı olmalı ve Pro uygulaması yokken açıkça sınırlı işlevle çalışmalıdır.
MINIMUM / BASIC_WL EN 16931 değildir. isEn16931Conformant() bunlar için false döndürür; bunları kullanırken bir EN 16931 faturası olarak tanıtmayın.
PDF/A-3 tabanı. Gömülü XML bir PDF/A-3 arşiv kabında taşınır; gömülü dosya F/UF anahtarları (PDF/A §6.7.5) mevcut olmalıdır.
XML, XXE’ye karşı güvenli biçimde ayrıştırılır. Sözleşme, XmlGuard ile ayrıştırmayı zorunlu kılar; özel bir gömücü bir XXE açığı oluşturmamalıdır.
Geçerlilik, kütüphanenin vereceği bir karar değildir. Yapısal olarak doğru bir Factur-X dosyası üretmek, vergi makamının onu kabul edeceği anlamına gelmez.

Performans

Gömme işlemi, XML ekini ve XMP uzantı şemasını eklemek için PDF’yi yeniden yazar. Tipik bir fatura için bütçe: geçen süre ≤ 1500 ms, tepe bellek ≤ 128 MB.

Güvenlik notları

Gömülü XML, XmlGuard aracılığıyla XXE’ye karşı güvenli biçimde ayrıştırılır. Fatura XML’i, taraflar ve tutarlar dâhil olmak üzere ticari nitelikli kişisel olarak tanımlanabilir bilgiler (PII) içerir. Bu veri gömülüdür, şifrelenmiş değildir. Fatura gizliliği, entegratörün sorumluluğundadır.

Veri ikametgâhı ve PII azaltma önlemleri

Fatura XML’i, taraflara ve finansa ilişkin PII taşır. Gömme işlemi aynı süreç içinde yapılır; gömme sırasında hiçbir veri süreç dışına çıkmaz. Bir alıcı makama iletim kapsam dışındadır ve entegratörün veri ikametgâhına ilişkin sorumluluğundadır.

Güvenli telemetri ve günlük arındırma

CII XML’ini veya gömülü PDF baytlarını asla günlüğe yazmayın — çünkü bunlar fatura PII’si içerir. Yalnızca profil adını ve yapısal bir kararı günlüğe yazın.

Tehdit modeli

Bir Factur-X dosyası erişim denetimine tabi değildir. Gömülü XML, dosyaya sahip olan herkes tarafından okunabilir. Melez yapı, faturanın makine tarafından okunabilirliğini garanti eder; gizliliğini veya mali kabulünü değil.

FIPS modu davranışı

Gömme işlemi hiçbir kriptografi gerçekleştirmez. İmzalı bir Factur-X faturası ayrı bir imza tarifi konusudur ve o tarifin FIPS durumunu devralır. Bu sayfa hiçbir imzalama iddiasında bulunmaz.

Uyumluluk

İddia	Belirtim	Madde
Bir EN 16931 faturası, anlamsal veri modeli iş terimlerini taşır.	EN 16931-1	§6.4
EN 16931 uyumluluğu, uyumlu bir faturanın karşılaması gereken iş kuralı kardinalitesine göre belirlenir.	EN 16931-1	§7
Factur-X EN 16931 profili, CII-XML iş kuralı uyumluluğunu gerektirir.	Factur-X 1.08	EN 16931 profili
Factur-X EN 16931 profili, gerekli fatura içeriğini zorunlu kılar.	Factur-X 1.08	EN 16931 profili
Factur-X melez bir yapıdır: makine tarafından okunabilen XML, insan tarafından okunabilen PDF’nin yanına gömülür.	Factur-X 1.08	Basic
Gömülü XML, bir PDF/A arşiv tabanında taşınır (gömülü dosya F/UF anahtarları).	ISO 19005-4	§6.7.5

Alıntılar, doğrulama derlemine yönelik madde kimliği + reference_id işaretçileridir. Hiçbir standart metni yeniden üretilmez; maddeler NextPDF’in kendi ifadeleriyle özetlenir.