توافق ZUGFeRD / Factur-X: ملف تعريف الفاتورة المضمَّن وفق EN 16931

لمحة سريعة

بيان الحدود. ينتج ⁨NextPDF⁩ ملف تعريف ⁨XML⁩ المضمَّن؛ أمّا الصلاحية الضريبية والقانونية فتقرّرها الجهة المستلِمة، وليست المكتبة.

⁨ZUGFeRD⁩ / ⁨Factur-X⁩ فاتورة هجينة: مستند ⁨PDF⁩ قابل للقراءة البشرية (ركيزة أرشفة من نوع ⁨PDF/A-3⁩) مع صيغة ⁨XML⁩ مضمَّنة قابلة للقراءة الآلية من نوع ⁨Cross-Industry-Invoice⁩ (⁨CII⁩) تتبع نموذج البيانات الدلالي ⁨EN 16931.⁩ تشحن ⁨NextPDF Core⁩ عقد المضمِّن (NextPDF\Contracts\EInvoice)؛ بينما يُشحن محرّك ⁨Factur-X 1.08⁩ الفعلي ضمن حزمة nextpdf/pro في ⁨Premium.⁩ تنتج المكتبة صيغة ⁨XML⁩ المضمَّنة وبنية مرفق ⁨PDF/A-3.⁩ أمّا الصلاحية الضريبية فيقرّرها مدقّق وفق ⁨EN 16931⁩ / ⁨Schematron⁩، أو الجهة الضريبية المستلِمة.

التثبيت

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

تشحن ⁨Core⁩ كلًّا من EmbedderInterface، وProfileInterface، وProfileType، وValidatorInterface، وValidationResult ضمن NextPDF\Contracts\EInvoice. وتوضح كتلة توثيق الواجهة ذلك صراحةً: تنفّذ هذا العقد فئة ⁨Pro⁩ (محرّك إعادة كتابة البايتات لـ ⁨Factur-X 1.08⁩) وفئة ⁨Enterprise⁩ (المُنشئ المُدار وفق ⁨PDF/A⁩). لا تضمِّن ⁨Core⁩ وحدها فاتورة مطلقًا؛ بل تعرّف عقد ⁨byte-in/byte-out⁩ الذي تستوفيه تلك الفئات.

نظرة مفاهيمية عامة

NextPDF\Contracts\EInvoice\ProfileType هو مميِّز التوافق مع ⁨EN 16931⁩: MINIMUM، وBASIC_WL، وBASIC، وEN16931، وEXTENDED، وXRECHNUNG. وترمّز دالته isEn16931Conformant() القاعدة مباشرةً من ⁨EN 16931-1.⁩ يُعدّ MINIMUM وBASIC_WL غير متوافقين مع ⁨EN 16931⁩ (لإخفاقهما في تحقيق تعدُّدية مُعرِّف المواصفة ⁨BT-24⁩ ومتطلّب بند السطر). أمّا BASIC، وEN16931، وEXTENDED، وXRECHNUNG فمتوافقة مع ⁨EN 16931.⁩

المضمِّن (EmbedderInterface) ملزَم تعاقديًّا بما يلي:

• تحليل صيغة ⁨XML⁩ الخاصة بـ ⁨CII⁩ المقدَّمة عبر XmlGuard (آمن ضدّ ⁨XXE⁩)؛
• حقن مخطَّط امتداد ⁨XMP⁩ الخاص بـ ⁨Factur-X⁩ لملف التعريف المُعلَن؛
• إرفاق صيغة ⁨XML⁩ بوصفها ملفًّا مضمَّنًا مع قيمة AFRelationship الصحيحة (Data / Alternative) كي تحملها ركيزة الأرشفة ⁨PDF/A-3⁩ (متطلّبات الملف المضمَّن في §6.7.5 — مفتاحا F/UF).

يُصدر ⁨NextPDF⁩ هذه البنية، لكنه لا يؤكّد أن الفاتورة صالحة ضريبيًّا. فالجهة المستلِمة هي من يتّخذ هذا القرار في ضوء قواعد الأعمال في ⁨EN 16931⁩ §7 وأي ⁨CIUS⁩ وطني.

سطح واجهة ⁨API⁩

الرمز	الأثر
Contracts\EInvoice\EmbedderInterface	عقد ⁨byte-in/byte-out⁩؛ تنفّذه ⁨Pro/Enterprise.⁩
Contracts\EInvoice\ProfileType (تعداد ⁨enum⁩)	مميِّز ملف تعريف ⁨EN 16931.⁩
ProfileType::isEn16931Conformant(): bool	القيمة ⁨false⁩ لـ ⁨MINIMUM/BASIC_WL⁩؛ والقيمة ⁨true⁩ لـ ⁨BASIC/EN16931/EXTENDED/XRECHNUNG.⁩
Contracts\EInvoice\ValidatorInterface	عقد التحقُّق الذي يُعيد ValidationResult يضم مخالفات القواعد.

عيّنة شيفرة — بداية سريعة

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

عيّنة شيفرة — بيئة الإنتاج

يضمِّن خط الإنتاج (فئة ⁨Pro⁩) صيغة ⁨XML⁩ الخاصة بـ ⁨CII⁩ داخل قاعدة ⁨PDF/A-3.⁩ ثم شغِّل أداة تحقُّق ⁨Schematron⁩ وفق ⁨EN 16931⁩، أو أرسلها إلى الجهة المستلِمة، وتعامل مع ذلك التقرير بوصفه البوّابة. يُصدر ⁨NextPDF⁩ صيغة ⁨XML⁩ المضمَّنة ومرفق ⁨PDF/A-3⁩؛ وأداة التحقُّق أو الجهة هي من يقرّر الصلاحية الضريبية. لا يمكن لـ ⁨Core⁩ وحدها تشغيل هذا الخط. nextpdf/pro مطلوب لمحرّك المضمِّن.

الحالات الحدّية والمزالق

• ⁨Core⁩ تحوي العقود فقط. بدون nextpdf/pro لا يوجد مضمِّن فعلي. اعتمد في الشيفرة المُستدعِية على الواجهة، واجعلها تتدهور بوضوح عند غياب تنفيذ ⁨Pro.⁩
• ⁨MINIMUM⁩ / ⁨BASIC_WL⁩ ليسا متوافقين مع ⁨EN 16931.⁩ تُعيد isEn16931Conformant() القيمة ⁨false⁩ لهذين الملفّين؛ فلا تُعلِن عن فاتورة ⁨EN 16931⁩ عند استخدامهما.
• ركيزة ⁨PDF/A-3.⁩ تُحمَل صيغة ⁨XML⁩ المضمَّنة داخل حاوية أرشفة من نوع ⁨PDF/A-3⁩؛ ويجب أن يكون مفتاحا الملف المضمَّن F/UF (⁨PDF/A⁩ §6.7.5) موجودَين.
• تُحلَّل صيغة ⁨XML⁩ على نحوٍ آمن ضدّ ⁨XXE.⁩ يتطلّب العقد التحليل عبر XmlGuard؛ فلا تُدخِل في المضمِّن المخصَّص مَصرفًا عرضةً لـ ⁨XXE.⁩
• الصلاحية ليست من حكم المكتبة. إنتاج ملف ⁨Factur-X⁩ سليم بنيويًّا لا يعني أن الجهة الضريبية ستقبله.

الأداء

يعيد التضمين كتابة مستند ⁨PDF⁩ لإضافة مرفق ⁨XML⁩ ومخطَّط امتداد ⁨XMP.⁩ الميزانية المحدَّدة: زمن جداري ≤ 1500 ⁨ms⁩، وذروة ذاكرة ≤ 128 ⁨MB⁩ لفاتورة نموذجية.

ملاحظات أمنية

تُحلَّل صيغة ⁨XML⁩ المضمَّنة على نحوٍ آمن ضدّ ⁨XXE⁩ عبر XmlGuard. تحتوي صيغة ⁨XML⁩ الخاصة بالفاتورة على معلومات تجارية تُعرِّف الأشخاص (⁨PII⁩)، بما في ذلك الأطراف والمبالغ. وهي مضمَّنة لا مشفَّرة. تقع سرّية الفاتورة على مسؤولية المُدمِج.

إقامة البيانات وإجراءات تخفيف مخاطر ⁨PII⁩

تحمل صيغة ⁨XML⁩ الخاصة بالفاتورة معلومات ⁨PII⁩ عن الأطراف والبيانات المالية. يجري التضمين داخل العملية؛ ولا تغادر أي بيانات العملية أثناء التضمين. أمّا الإرسال إلى جهة مستلِمة فهو خارج النطاق، ومن مسؤولية المُدمِج فيما يخصّ إقامة البيانات.

القياس عن بُعد الآمن وتنقية السجلّات

لا تُسجِّل مطلقًا صيغة ⁨XML⁩ الخاصة بـ ⁨CII⁩ أو بايتات مستند ⁨PDF⁩ المضمَّن — فهي تحتوي على معلومات ⁨PII⁩ الخاصة بالفاتورة. سجِّل اسم ملف التعريف والحكم البنيوي فقط.

نموذج التهديد

ملف ⁨Factur-X⁩ غير خاضع للتحكُّم في الوصول. صيغة ⁨XML⁩ المضمَّنة قابلة للقراءة من قِبل أي شخص يملك الملف. يضمن المستند الهجين قابلية الفاتورة للقراءة الآلية، لا سرّيتها ولا قبولها ضريبيًّا.

سلوك وضع ⁨FIPS⁩

لا يُجري التضمين أي عمليات تشفير. فاتورة ⁨Factur-X⁩ الموقَّعة شأن منفصل يخصّ وصفة التوقيع، وترث وضعية ⁨FIPS⁩ الخاصة بتلك الوصفة. لا تقدّم هذه الصفحة أي ادّعاء بشأن التوقيع.

التوافق

الادّعاء	المواصفة	البند	⁨reference_id⁩
تحمل فاتورة ⁨EN 16931⁩ مصطلحات الأعمال الخاصة بنموذج البيانات الدلالي.	⁨EN 16931-1⁩	§6.4
تحكم الامتثالَ لـ ⁨EN 16931⁩ تعدُّديةُ قواعد الأعمال التي يجب أن تستوفيها الفاتورة المتوافقة.	⁨EN 16931-1⁩	§7
يتطلّب ملف تعريف ⁨Factur-X EN 16931⁩ التوافق مع قواعد الأعمال الخاصة بـ ⁨CII-XML.⁩	⁨Factur-X 1.08⁩	ملف تعريف ⁨EN 16931⁩
يفرض ملف تعريف ⁨Factur-X EN 16931⁩ محتوى الفاتورة المطلوب.	⁨Factur-X 1.08⁩	ملف تعريف ⁨EN 16931⁩
⁨Factur-X⁩ مستند هجين: صيغة ⁨XML⁩ قابلة للقراءة الآلية مضمَّنة جنبًا إلى جنب مع مستند ⁨PDF⁩ القابل للقراءة البشرية.	⁨Factur-X 1.08⁩	⁨Basic⁩
تُحمَل صيغة ⁨XML⁩ المضمَّنة داخل ركيزة أرشفة من نوع ⁨PDF/A⁩ (مفتاحا الملف المضمَّن ⁨F/UF⁩).	⁨ISO 19005-4⁩	§6.7.5

الاستشهادات هي مؤشّرات ⁨clause-id⁩ + reference_id إلى مدوّنة التحقُّق. لا يُعاد إنتاج أي نص من المعايير؛ بل تُلخَّص البنود بكلمات ⁨NextPDF.⁩

انظر أيضًا

• صفحة التوافق
• توافق ⁨PDF/A-4⁩
• الأساس المرجعي لـ ⁨PDF 2.0⁩
• وحدة التوافق