PINT-OM للمطورين

PINT-OM هي مواءمة عمان لنموذج Peppol International الخاص بالفوترة الالكترونية. بالنسبة للمطورين، تمثل PINT-OM الشكل الفني للفوترة: نماذج المستندات، والمعرفات، وربط XML، وأدوات التحقق، ومستند التقرير الضريبي الذي يجب على الأنظمة التعامل معه.

هذا الدليل مسودة للمطورين والمنفذين. يشرح حدود الحزم وأسئلة التنفيذ التي يجب الاجابة عنها قبل كتابة كود انتاجي.

الجواب المختصر

تتكون حزمة عمان الحالية في OpenPeppol من ثلاثة أجزاء رئيسية:

الحزمة	ماذا تغطي؟
PINT OM Billing	الفواتير الالكترونية القياسية واشعارات الدائن الصادرة في عمان.
PINT OM Self-Billing	فواتير واشعارات دائن الفوترة الذاتية عندما يصدر المشتري نيابة عن المورد.
Oman Tax Data Document	مستند تقرير ضريبي منفصل يستخدم لابلاغ بيانات الفواتير إلى السلطة الضريبية.

لا تتعامل مع XML الفاتورة ومستند TDD كأنهما الشيء نفسه. هما مرتبطان، لكن لكل واحد وظيفة مختلفة.

ما هي PINT-OM؟

تستخدم PINT-OM منهجية Peppol PINT لمعاملات الفواتير واشعارات الدائن الخاصة بعمان. هي تخصيص وطني، وليست صيغة PDF عامة ولا حمولة API حرة.

تشير وثائق OpenPeppol الحالية إلى أن مواصفات عمان تحدد بنى الفوترة الالكترونية والتقرير الضريبي، وقواعد التحقق، وعمليات التبادل. وتوضح صفحة PINT OM Billing الفواتير الالكترونية القياسية الصادرة في عمان، بينما توضح صفحات TDD عملية مستند بيانات ضريبية منفصلة.

لذلك، يحتاج التنفيذ البرمجي إلى أربع طبقات على الأقل:

• بيانات الفاتورة في نظام المصدر؛
• XML الفاتورة أو اشعار الدائن وفق PINT-OM؛
• التحقق من الصيغة، وقوائم الرموز، والقواعد؛
• توليد أو تقرير TDD حيث يكون ذلك مطلوبا.

خريطة حزم المستندات

استخدم هذه الخريطة عند تخطيط المعمارية.

المسار	المستند	اهتمام المطور
Billing	Invoice	مواءمة بيانات الفاتورة المصدر إلى نموذج PINT OM والتحقق منه.
Billing	Credit note	الحفاظ على مراجع التصحيح والمبالغ متسقة مع الفاتورة الأصلية.
Self-billing	Self-billing invoice	دعم سيناريوهات الفاتورة التي يصدرها المشتري منفصلة عن الفاتورة العادية.
Self-billing	Self-billing credit note	دعم التصحيحات في مسارات الفوترة الذاتية.
Tax reporting	Tax Data Document	توليد مستند التقرير الضريبي والتحقق منه منفصلا عن تبادل الفاتورة مع المشتري.

لا يتم تبادل TDD بين مصدر الفاتورة ومستلمها. تصفه صفحة OpenPeppol الخاصة بعمان كمستند تنظيمي يرفع إلى السلطة الضريبية لأغراض التقرير الضريبي والامتثال.

التحقق ليس فحصا واحدا

التحقق في PINT-OM متعدد الطبقات. لا يكفي أن يبني المطور فحص "XML صالح" ثم يعتبر الفاتورة متوافقة.

خطط على الأقل لـ:

• سلامة XML؛
• مطابقة المخطط وربط الصيغة؛
• المصطلحات التجارية المطلوبة والشرطية؛
• القيم المسموحة من قوائم الرموز الرسمية؛
• قواعد الحساب والتقريب؛
• قواعد الأعمال الخاصة بعمان؛
• أدوات Schematron؛
• تحقق TDD حيث يكون التقرير الضريبي ضمن النطاق.

تشير ملاحظات اصدار TDD إلى أن المنفذين يجب أن يفهموا النموذج الدلالي وربط الصيغة ويلتزموا بقوائم الرموز الرسمية ويتحققوا من الأدوات المنشورة، بما في ذلك XSD وSchematron. يجب أن تشكل هذه الصرامة تنفيذ الفاتورة أيضا.

افصل نموذج بيانات المصدر

لا تثبت الفوترة مباشرة داخل نماذج الشاشة أو قوالب PDF. احتفظ بنموذج فاتورة مصدر داخل التطبيق ثم وائم هذا النموذج إلى PINT-OM عند الحدود.

ينبغي للنموذج الداخلي أن يحفظ:

• هويات البائع والمشتري؛
• VATIN ومعرفات العنوان الالكتروني؛
• حقول رأس الفاتورة؛
• نوع المستند؛
• بنود الفاتورة؛
• فئات الضريبة ونسب ضريبة القيمة المضافة؛
• المبالغ الخاضعة للضريبة والضريبة والاجماليات والخصومات والرسوم؛
• مراجع اشعارات الدائن أو المدين؛
• أعلام التصدير والاستيراد والفوترة الذاتية وB2C عند الحاجة؛
• بيانات الأرشفة وحالة التحقق.

يجب أن تكون طبقة المواءمة قابلة للاختبار وحتمية. إذا مرر مطوران الفاتورة المصدر نفسها عبر الموائم، يجب أن يحصلا على مخرج PINT-OM نفسه.

TDD اهتمام منفصل

لمستند Tax Data Document صفحة عملية ونموذج دلالي وربط صيغة وقوائم رموز وقواعد وSchematron خاصة به. تعامل معه كوحدة منفصلة.

المعاني العملية:

• لا تحصر منطق التقرير الضريبي داخل مرسل الفاتورة الموجهة للمشتري فقط.
• اجعل توليد TDD قابلا للاختبار من فاتورة مصدر محفوظة.
• احفظ الروابط بين الفاتورة المصدر وXML الفاتورة وTDD ونتيجة التحقق وسجل الأرشيف.
• تتبع حالات الارسال والتحديث والسحب والفشل إذا انطبقت على العملية النهائية.
• لا تفترض أن كل TDD مطابق لـ XML الفاتورة؛ لدى TDD بيانات وصفية ومقتطفات وقواعد تعامل مع مستندات المصدر.

هذا الفصل مهم للتصحيح. قد تفشل الفاتورة الموجهة للمشتري لسبب، ويفشل مستند التقرير الضريبي لسبب آخر.

قائمة تنفيذ للمطورين

المجال	ما الذي يجب تأكيده؟
بيانات المصدر	تحديد مصدر كل قيمة مطلوبة في الفاتورة.
المعرفات	تحديد تخزين VATIN والعنوان الالكتروني والمستند والفرع والعميل.
المواءمة	بناء موائم حتمي من بيانات المصدر إلى XML وفق PINT-OM.
قوائم الرموز	مركزية الرموز المسموحة وتحديثها من الأدوات الرسمية.
الحسابات	اختبار الاجماليات والضريبة والخصومات والرسوم والتقريب وحالات التصحيح.
التحقق	تشغيل فحوص المخطط وقوائم الرموز وقواعد الأعمال وSchematron قبل الارسال.
TDD	التعامل مع توليد TDD والتحقق منه كوحدة منفصلة.
الأخطاء	ترجمة أخطاء التحقق إلى رسائل مفهومة للمالية دون اخفاء الخطأ الخام.
الأرشفة	حفظ بيانات المصدر وXML وTDD ونتائج التحقق والطوابع وروابط التصحيح.
ضبط التغيير	اصدارات للموائم ومجموعة اختبارات لكل تحديث مواصفة.

حالات اختبار مبكرة

لا تنتظر اختبار المزود لتجهيز الحالات. ابن مجموعة fixtures محلية من حالات عملك الحقيقية.

أمثلة ضرورية:

• فاتورة B2B بسيطة؛
• فاتورة B2C بسيطة؛
• فاتورة فيها خصم؛
• فاتورة بأكثر من نسبة ضريبة؛
• اشعار دائن مرتبط بفاتورة أصلية؛
• اشعار مدين أو حالة تصحيح؛
• فاتورة تصدير؛
• حالة استيراد أو فوترة ذاتية عند الحاجة؛
• نص عربي للعميل أو الصنف؛
• مبالغ تقريب حدية؛
• فاتورة غير صالحة عمدا لكل طبقة تحقق.

يجب أن تتضمن كل حالة بيانات المصدر، ومخرج XML المتوقع، ونتيجة التحقق المتوقعة، وسبب وجود الحالة.

نقاط مراقبة حالية

يجب اعادة التحقق من عدة تفاصيل قبل نشر هذا الدليل:

• الحالة النهائية وموقع الاصدار النهائي لـ PINT-OM؛
• قاموس البيانات النهائي وقائمة الحقول الالزامية؛
• اصدارات أدوات التحقق النهائية؛
• هل تتغير دقة المبالغ على مستوى المستند من منزلتين إلى ثلاث منازل عشرية؛
• قواعد QR/TLV النهائية من Peppol Oman Architecture v1.0.2 Appendix D؛
• التشريعات النهائية وأحكام الجزاءات.

تشير صفحة OpenPeppol الحالية الخاصة بعمان إلى أن المبالغ النقدية على مستوى المستند محدودة حاليا بمنزلتين عشريتين، وأن تحديثا لدعم ثلاث منازل عشرية مخطط. لا تثبت افتراضات الدقة دون اصدارات واختبارات.

ما الذي لا يجوز الجزم به بعد

لا تنشر أو تعتمد على النقاط التالية دون دليل أولي حالي:

• أسماء الحقول النهائية الدقيقة لكل مصطلح تجاري؛
• أعداد قواعد التحقق الدقيقة؛
• ترتيب أو حدود وسوم QR/TLV الدقيقة؛
• مبالغ الجزاءات النهائية؛
• أن مزودا أو منتجا برمجيا يدعم PINT-OM بالكامل؛
• أن وثائق مرحلة المراجعة الحالية هي المواصفة النهائية النافذة.

الادعاء الآمن هو أن المطورين يجب أن يبنوا حول أدوات OpenPeppol وجهاز الضرائب الرسمية، ويفصلوا XML الفاتورة عن TDD، ويمركزوا التحقق، ويصدروا كل قرار مواءمة.

الخطوة التالية

ابدأ بجرد بيانات المصدر. اختر 10 فواتير حقيقية وحدد أين يعيش كل حقل في نظامك. ثم ابن اختبار موائم حول فاتورة B2B بسيطة وحالة تصحيح واحدة. لا تضف توليد TDD إلا بعد أن يصبح مسار مواءمة الفاتورة والتحقق واضحا.