Enterprise الإصدار

الفاتورة — مرجع متعمّق

نظرة سريعة

تتضمّن وحدة الفاتورة ثلاثة أسطح مستقلّة: التضمين، والتحقّق، وتنفيذ قواعد ⁨Schematron⁩. يُرفق كلٌّ من ZugferdEmbedder وPeppolEmbedder ملف ⁨XML⁩ للفاتورة المُقدَّم من المُستدعي إلى حامل ⁨PDF/A-4f⁩ أو ⁨PDF/A-3b⁩ ويُعيد نتيجة مُهيكَلة. يُجري InvoiceXmlValidator فحصاً بنيوياً مسبقاً وفق ⁨EN 16931⁩ بخطورة قابلة للاختيار ⁨COMPAT⁩ أو ⁨STRICT⁩. يُنفّذ SchematronValidator حِزم قواعد ⁨Schematron⁩ المُترجَمة مسبقاً داخل العملية ويُحلّل نتائج ⁨SVRL⁩. لا يُنشئ ⁨NextPDF⁩ ملف ⁨XML⁩ للفاتورة؛ فالمُستدعي هو من يُقدّم الحمولة ويملكها.

التوفّر والترخيص

تُشحن هذه القدرة ضمن ⁨NextPDF Enterprise⁩ (nextpdf/enterprise) وتُفعَّل بمظروف ترخيص من فئة ⁨Enterprise⁩. أيّ نشرٍ لا يملك ذلك الاستحقاق لا يُحمِّل أصناف هذه القدرة. قارن بين الإصدارات واحصل على ترخيص.

تفصيل بحسب الفئة: كشف الفاتورة الإلكترونية والتحقّق منها هو سطح فئة ⁨Pro⁩ (وحدة ⁨Pro Compliance⁩). أمّا تضمين الفاتورة الهجينة، وملف ⁨XRechnung CIUS⁩، ومحرّك ⁨Schematron⁩ داخل العملية فهي حصرية لفئة ⁨Enterprise⁩. لا يوجد رمز قدرة منفصل لكل ميزة يتجاوز حدود حزمة nextpdf/enterprise.

سطح واجهة برمجة التطبيقات العامة

composer require nextpdf/enterprise:^3

الرمز	المُعامِلات	السلوك الافتراضي	يُعيد	يرمي أو يفشل بـ	ملاحظات
`ZugferdEmbedder::basic()`	`PdfAManager`, `FileAttachment`, `string $xmlData`	يُضمّن ⁨CII XML⁩ من ملف ⁨BASIC⁩: مرور ⁨XmlGuard⁩، وتحقّق بنيوي، وحقن مخطط ⁨XMP⁩، وإرفاق	`ZugferdEmbedResult`	`InvalidArgumentException`, `ZugferdEmbeddingException`	مسار سريع؛ نقطة بداية موصى بها
`ZugferdEmbedder::minimum()`	`PdfAManager`, `FileAttachment`, `string $xmlData`	المسار نفسه بملف ⁨MINIMUM⁩	`ZugferdEmbedResult`	`InvalidArgumentException`, `ZugferdEmbeddingException`	مسار سريع
`ZugferdEmbedder::create()`	`ZugferdProfile`, `string $xmlData`	مدخل الباني؛ يرفض ⁨XML⁩ الفارغ	`self`	`InvalidArgumentException`	اضبط عبر `withoutValidation()` و`withDescription()`
`ZugferdEmbedder::withAfRelationship()` / `PeppolEmbedder::withAfRelationship()`	`AFRelationship\|string`	يتجاوز علاقة `/Alternative` الافتراضية؛ محكوم بكتاب قواعد الملف المرتبط	`self`	`InvalidArgumentException`	`Schema` و`EncryptedPayload` و`FormData` مرفوضة للفواتير
`ZugferdEmbedder::embed()`	`PdfAManager`, `FileAttachment`	استدعاء الباني الطرفي: ⁨XmlGuard⁩، وتحقّق اختياري، وفحص الحامل، و⁨XMP⁩، والإرفاق	`ZugferdEmbedResult`	`InvalidArgumentException`, `ZugferdEmbeddingException`	إخفاق التحقّق يُسمّي أوّل خطأ
`ZugferdProfile` (enum)	—	الحالات MINIMUM, BASIC_WL, BASIC, EN16931, EXTENDED, XRECHNUNG	—	—	يُرفق ⁨XRECHNUNG⁩ الملف `xrechnung.xml`؛ وملفات ⁨CII⁩ تُرفق `factur-x.xml`
`ZugferdXmpSchema::apply()`	`XmpMetadata`, `ZugferdProfile`	يُسجّل وصف ⁨Factur-X RDF⁩ ومدخل مخطط امتداد ⁨PDF/A⁩	`XmpMetadata`	لا شيء	يُستدعى من `embed()`؛ ويمكن استخدامه مباشرةً أيضاً
`PeppolEmbedder::invoice()` / `::creditNote()`	`PdfAManager`, `FileAttachment`, `string $ublXml`	يُضمّن ⁨XML⁩ فاتورة أو إشعار دائن بصيغة ⁨Peppol BIS 3.0 UBL⁩	`PeppolEmbedResult`	`InvalidArgumentException`, `PeppolEmbeddingException`	أسماء الملفات الافتراضية `invoice.xml` / `creditnote.xml`
`PeppolEmbedder::create()`	`string $ublXml`, `string $filename = 'invoice.xml'`	مدخل الباني؛ يرفض ⁨XML⁩ أو اسم ملف فارغاً	`self`	`InvalidArgumentException`	اضبط عبر `withFilename()` و`withDescription()` و`withoutSanitization()`
`PeppolEmbedder::embed()`	`PdfAManager`, `FileAttachment`	مرور ⁨XmlGuard⁩، وفحص الحامل، وبوابة كتاب القواعد، والإرفاق	`PeppolEmbedResult`	`InvalidArgumentException`, `PeppolEmbeddingException`	إعادة فحص كتاب القواعد بمراعاة الحامل وقت التضمين
`InvoiceXmlValidator::validate()`	`string $xmlData`, `ZugferdProfile`, `?InvoiceValidatorMode`	فحص بنيوي مسبق وفق ⁨EN 16931⁩؛ خطورة ⁨COMPAT⁩ افتراضياً	`InvoiceValidationResult`	لا يرمي؛ تظهر الإخفاقات كنتائج خطأ	يُحلّ الوضع من الوسيط، ثمّ البيئة، ثمّ ⁨COMPAT⁩
`InvoiceXmlValidator::isCrossIndustryInvoice()`	`string $xmlData`	فحص العنصر الجذر ومساحة الاسم لحمولات ⁨CII⁩	`bool`	لا يرمي؛ يُعيد `false`	مِسبار كشف منخفض الكلفة
`InvoiceValidatorMode` (enum)	—	`COMPAT` (افتراضي) يُبقي نتائج ⁨BT-24⁩ عند مستوى تحذير؛ و`STRICT` يرفعها إلى خطأ	—	—	`fromEnvironment()` يعود إلى ⁨COMPAT⁩ عند القيم غير المضبوطة أو غير المعروفة
`InvoiceValidationResult` / `InvoiceValidationFinding`	—	تجميعات غير قابلة للتغيير: `isValid` و`getErrors()` و`getWarnings()`؛ مستوى ورمز ورسالة لكل نتيجة	—	—	`InvoiceValidationResult::fail()` يُغلّف خطأً واحداً
`SchematronValidator::validate()`	`string $xsltPath`, `string $xmlData`	يُنفّذ ⁨XSLT⁩ ⁨Schematron⁩ مُترجَماً مسبقاً؛ ويُحلّل ⁨SVRL⁩ إلى نتائج	`SchematronResult`	`InvalidArgumentException` عند مسار ⁨XSLT⁩ مفقود أو غير قابل للقراءة؛ وإخفاقات المحرّك تُعيد نتيجة خطأ	يُلتقط التوقيت في `durationMs`
`SchematronValidator::runRules()`	`string $xslPath`, `string $xmlPayload`	مُحوّل عبر الفئات؛ يُطابق نتائج الخطأ إلى كائنات العقد `RuleViolation`	`list<RuleViolation>`	مثل `validate()`	تُتجاوز نتائج المستوى المعلوماتي
`SchematronResult` / `SchematronFinding`	—	الحُكم، والنتائج، والمدة؛ `getFailedAssertions()` و`getSuccessfulReports()`	—	—	`SchematronResult::error()` يُعلّم إخفاقات المحرّك بأنها غير صالحة
`SchematronCacheInterface`	—	عقد ذاكرة تخزين مؤقت يكشف العبث: `getVerified()` و`set()` و`computeKey()`	—	—	يفشل بأمان عند عدم تطابق البصمة
`AtomicRenameSchematronCache`	`string $cacheDir`, `bool $atomicRename = true`, `LoggerInterface`	ذاكرة ملفات مؤقتة مُتحقَّق منها بـ ⁨SHA-256⁩ مع كتابات إعادة تسمية ذرّية	—	`InvalidArgumentException`, `SchematronCacheException`	يجب أن يكون الدليل موجوداً أو قابلاً للإنشاء، وقابلاً للكتابة
`VersionPinRegistry`	`array $pins`, `?string $sourcePath`	تثبيتات حِزم قواعد مقفلة بـ ⁨SHA-256⁩: `loadFromLockFile()` و`get()` و`verifyArtefact()` و`regenerateLockFile()`	—	`VersionPinException`, `InvalidArgumentException`, `JsonException` عند ملف قفل ⁨JSON⁩ مُشوَّه	البصمات الفارغة أو المُشوَّهة تفشل بأمان
`InvoiceContractValidator`	`?SemanticValidator`	مُحوّل `ValidatorInterface` عبر الفئات؛ فحص بنيوي مسبق إضافةً إلى قواعد ⁨EN 16931⁩ الدلالية العميقة	`ContractResult`	يفشل بأمان؛ تظهر أخطاء المحرّك كنتائج خطأ	مربوط على مسارات إطار العمل عند تثبيت `nextpdf/premium`
`ZugferdContractEmbedder`	`FacturXContractEmbedder`	مُحوّل `EmbedderInterface` عبر الفئات؛ تضمين بايت-داخل / بايت-خارج	`string` (بايتات ⁨PDF⁩)	يُمرّر إخفاقات المفوَّض	يُفوّض إلى محرّك إعادة كتابة البايتات في فئة ⁨Pro⁩
`ZugferdEmbeddingException`, `PeppolEmbeddingException`, `SchematronCacheException`, `VersionPinException`	—	تصنيف إخفاقات الوحدة	—	—	جميعها تُوسّع `RuntimeException`

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

عقد السلوك

التضمين. يُرفق ZugferdEmbedder حمولة ⁨XML⁩ من نوع ⁨ZUGFeRD 2.4⁩ / ⁨Factur-X 1.08⁩ ⁨UN/CEFACT CII⁩ مُقدَّمة من المُستدعي إلى حامل ⁨PDF/A⁩. وهو يدعم حاملَين: ⁨PDF/A-4f⁩ (⁨ISO 19005-4:2020⁩)، الحامل الحديث المُفضّل، و⁨PDF/A-3b⁩ (⁨ISO 19005-3:2012⁩) للتوافق مع الإصدارات السابقة. يُشغّل embed() دائماً مرور أمان ⁨XmlGuard⁩ أوّلاً، ثمّ التحقّق البنيوي ما لم يُضبَط withoutValidation()، ثمّ يتحقّق من أن الحامل يدعم الملفات المضمّنة، ويحقن إعلان مخطط امتداد ⁨XMP⁩ عبر ZugferdXmpSchema، ويُرفق ⁨XML⁩ كملف مرتبط. تكون علاقة الإرفاق افتراضياً وفق توصية كتاب القواعد /Alternative؛ وتمرّ التجاوزات عبر كتاب القواعد نفسه الذي يفرض مجموعة العلاقات في ⁨ISO 32000-2:2020⁩ §⁨14.13⁩ ومجموعة الفاتورة الفرعية في ⁨EN 16931⁩. يؤدّي PeppolEmbedder المكافئ لملف ⁨XML⁩ فاتورة أو إشعار دائن بصيغة ⁨Peppol BIS Billing 3.0 UBL 2.1⁩ مُقدَّم من المُستدعي. لا يُنشئ أيٌّ من المُضمِّنَين ملف ⁨XML⁩ للفاتورة.

التحقّق. يفحص InvoiceXmlValidator ملف ⁨CII XML⁩ مقابل التوقّعات البنيوية لـ ⁨EN 16931⁩: العنصر الجذر، والأقسام المطلوبة، وعدديّة الترويسة، وبنود السطور حيث يتطلّبها الملف، ومُعرِّف المواصفة ⁨BT-24⁩ الذي تُلزِم به قاعدة العمل ⁨BR-1⁩. يختار InvoiceValidatorMode الخطورة. يُبلّغ COMPAT (الافتراضي) عن ⁨BT-24⁩ مفقود أو غير مطابق بوصفه تحذيراً كي لا تتراجع بوابة الصلاحية المنطقية. يجعل STRICT كليهما خطأً صارماً ويؤكّد أيضاً اتساق الملف مقابل ZugferdProfile المُعلَن، محاكياً دلالات مُحقِّقَي ⁨KoSIT⁩ / ⁨Mustang⁩ الخارجيَّين. يُحلّ الوضع بالترتيب: الوسيط الصريح، ثمّ تجاوز البيئة INVOICE_VALIDATOR_MODE، ثمّ ⁨COMPAT⁩. النتائج كائنات مُهيكَلة InvoiceValidationResult / InvoiceValidationFinding؛ ويُعيد المُحقِّق النتائج بدلاً من الرمي.

Schematron. يُنفّذ SchematronValidator مجموعات قواعد ⁨Schematron⁩ المُترجَمة مسبقاً — قواعد ⁨CEN EN 16931⁩ بصيغة .sch المُترجَمة إلى ⁨XSLT⁩ وقت البناء — باستخدام معالج ⁨XSLT⁩ الخاص بـ ⁨PHP⁩ داخل العملية. يُحلّل تقرير ⁨SVRL⁩ إلى كائنات SchematronFinding / SchematronResult: تُصبح التوكيدات الفاشلة نتائج خطأ، وتُصبح التقارير الناجحة نتائج معلوماتية. تُقدّم ذاكرة تخزين مؤقت اختيارية (SchematronCacheInterface، مع تنفيذ ملف إعادة التسمية الذرّية) بايتات أوراق الأنماط المُتحقَّق منها مُفهرَسةً ببصمة المحتوى إضافةً إلى إصدار المُترجِم. يُثبّت VersionPinRegistry كل حزمة قواعد خارجية إلى إصدار مقفل بـ ⁨SHA-256⁩ ويفشل بأمان عند الانحراف أو البصمات المُشوَّهة.

تُنتج هذه الوحدة بيانات فاتورة مُهيكَلة وتفحصها. وهي لا تؤكّد أن أيّ مستند فاتورة متوافقة قانونياً، ولا أنه مُعتمَد من سلطة ضريبية، ولا أنه مضمون القبول لدى أيّ سلطة. يفحص المُحقِّق النموذج الدلالي لـ ⁨EN 16931⁩ وحاوية ⁨ZUGFeRD⁩ / ⁨Factur-X⁩ / ⁨UBL⁩ فقط؛ ويستثني الامتدادات الوطنية (مثل ⁨SDI⁩ الإيطالي، و⁨Chorus Pro⁩ الفرنسي، ونقل ⁨XRechnung⁩ الألماني). وكما تنصّ ⁨EN 16931-1⁩، يتحمّل مُصدِر الفاتورة مسؤولية استيفاء قواعد التشريعات ذات الصلة؛ وهذا ليس مُحقِّق سلطة ضريبية. دعم معيار ما ليس مطابقةً له.

الحالات الحدّية وأنماط الإخفاق

يفشل ⁨XML⁩ الفارغ بسرعة: يرمي البانون InvalidArgumentException؛ ويُعيد InvoiceXmlValidator::validate() نتيجة فاشلة.
يرفض ⁨XmlGuard⁩ إعلانات DOCTYPE، وتوسيع الكيانات، والحمولات المُفرطة الحجم، ومحارف التحكّم. ويُظهر المُضمِّنون ذلك بوصفه ZugferdEmbeddingException أو PeppolEmbeddingException مع الحفاظ على السبب.
لا يتجاوز withoutValidation() وwithoutSanitization() مطلقاً مرور أمان ⁨XmlGuard⁩. فقط فحوص مصطلحات العمل البنيوية قابلة للتخطّي.
أيّ حامل لا يدعم الملفات المضمّنة (أيّ شيء غير ⁨PDF/A-4f⁩ أو ⁨PDF/A-3b⁩) يرفع InvalidArgumentException مُسمّياً الإصدارات المقبولة.
تُرفض قيمة AFRelationship غير المسموح بها عند حدود الباني؛ وتُشغَّل إعادة فحص كتاب القواعد بمراعاة الحامل مرّةً أخرى داخل embed().
يُبقي COMPAT قيمة ⁨BT-24⁩ المفقودة عند خطورة التحذير؛ ويجعل STRICT قيم ⁨BT-24⁩ المفقودة وغير المطابقة للملف أخطاءً صارمة.
لا يرمي SchematronValidator إلا عند مسار ⁨XSLT⁩ مفقود أو غير قابل للقراءة. وتُعيد إخفاقات التحويل أو تحليل ⁨SVRL⁩ القيمة SchematronResult::error() مع isValid بقيمة false.
أيّ مدخل ذاكرة تخزين مؤقت تفشل بايتاته المخزّنة في التحقّق من البصمة يُطرَد، وتُعاد قراءة ورقة الأنماط من القرص؛ ولا تُعاد البايتات المسمومة مطلقاً.
يعمل معالج ⁨XSLT⁩ مع حظر تحميل موارد الملفات والشبكة ولا يُسجّل دوال ⁨PHP⁩ مطلقاً؛ فلا يمكن لـ document() وxsl:include وxsl:import وresult-document تحميل الموارد.
يرفض VersionPinRegistry بصمات ⁨SHA-256⁩ الفارغة أو المُشوَّهة عند الاستيعاب وعند إعادة التوليد؛ ويُعيد verifyArtefact() القيمة false بدلاً من تمرير تثبيت غير قابل للتحقّق.
لا تُجري هذه الوحدة أيّ توقيع تعمية؛ وسلوك وضع ⁨FIPS⁩ خارج النطاق هنا (اطّلع على وحدة التوقيع).

المطابقة

السلوك	المرجع	الحالة
النموذج الدلالي الأساسي للفاتورة	⁨EN 16931-1:2026 §4⁩	مبنيّ عليه؛ يبقى المُصدِر مسؤولاً
مُعرِّف المواصفة (⁨BT-24⁩)	⁨EN 16931-1:2026 BR-1⁩	تحذير في ⁨COMPAT⁩، وخطأ في ⁨STRICT⁩
ربط بناء الجملة ⁨UN/CEFACT CII⁩	⁨CEN/TS 16931-3-3:2020⁩	التضمين مدعوم
ربط بناء الجملة ⁨UBL 2.1⁩	⁨CEN/TS 16931-3-2:2020⁩	التضمين مدعوم
الملف المرتبط ⁨PDF/A-3⁩	⁨ISO 19005-3:2012 §6.7.8⁩	الحامل مدعوم
الملف المضمّن ⁨PDF/A-4f⁩	⁨ISO 19005-4:2020 Annex A⁩	الحامل مدعوم
قيم علاقة الملف المرتبط	⁨ISO 32000-2:2020 §14.13⁩	محكوم بكتاب القواعد
تحليل تقرير ⁨Schematron⁩ / ⁨SVRL⁩	⁨ISO/IEC 19757-3⁩	مبنيّ عليه (مستند إلى المنتج؛ المعيار غير موجود في مجموعة الاستشهادات)

مبنيّ عليه، وليس شهادةً ولا اعتماداً من سلطة ضريبية. لا يملك ⁨NextPDF⁩ أيّ شهادة لأيٍّ من هذه المعايير. يُنتج ⁨NextPDF⁩ فواتير مُهيكَلة متوافقة مع نموذج بيانات ⁨EN 16931⁩ ويُبلّغ عن نتائج القواعد؛ وهو لا يُنتج فواتير متوافقة قانونياً، ولا يُوفّر مخرجات مُعتمَدة من سلطة ضريبية، ولا يضمن القبول. استشر مستشاريك الضريبيين والقانونيين.

ملاحظات التطوير

يتطلّب محرّك ⁨Schematron⁩ امتداد ⁨PHP⁩ المسمّى ext-xsl؛ وتوفيره وتفعيله مسؤولية المُشغّل.
المعالجة داخل العملية ومحلية. لا تقع أيّ استدعاءات شبكة صادرة أثناء التضمين أو التحقّق. ونقل الفوترة الإلكترونية الوطني، ومنصّات المقاصّة، وأنظمة الأرشفة خارجة عن هذه الوحدة.
تُترجَم حِزم القواعد من .sch إلى ⁨XSLT⁩ وقت البناء؛ ولا يُنفّذ زمن التشغيل إلا أوراق الأنماط المُترجَمة مسبقاً.
تُدمج مفاتيح الذاكرة المؤقتة مِلح إصدار المُترجِم (حالياً nextpdf-schxslt-1.0)؛ ورفعه يُبطل الذواكر المؤقتة المنشورة دون خطوة تطهير.
تُوجد تثبيتات حِزم القواعد في ملف القفل عند enterprise/config/invoice-versions.lock (VersionPinRegistry::DEFAULT_LOCK_PATH)؛ ويتحقّق ⁨CI⁩ من المُنتجات المنشورة مقابل البصمات المُثبَّتة.
يستخدم المُستدعون عبر الفئات InvoiceContractValidator وZugferdContractEmbedder؛ ويستخدم مُستدعو ⁨Enterprise⁩ الأصليون لهذه الفئة ZugferdEmbedder وInvoiceXmlValidator مباشرةً.

حدود النشر

توثّق هذه الصفحة السلوك القابل للملاحظة خارجياً وسطح واجهة برمجة التطبيقات العامة المدعوم فقط. أمّا مسارات مساحات الأسماء الداخلية، وأصناف المساعدة، وجداول الآليات، وأسماء ملفات كتيّبات التشغيل، وبادئات التذاكر فهي خارج النطاق.

اطّلع أيضاً

قدرة الفاتورة — نظير القدرة لهذا المرجع.
Pro Compliance — الكشف/التحقّق في فئة ⁨Pro⁩.
التقديم الإلكتروني للمستندات
نظرة عامة على Enterprise