منصة SMP في عمان وطبقة نقطة الوصول في بيبول — دليل تمهيدي للمطورين

ان كنت تعمل على التكامل مع نظام الفوترة، فستقابل ثلاثة مصطلحات سريعا: SMP وSML ونقطة الوصول. يهيئك هذا الدليل قبل ان تفتح المواصفة، وخاصة انه يرسم الحد بين الجزء الذي تديره من المنظومة والجزء الذي ينقل الفواتير، لان الخلط بينهما اغلى الاخطاء المبكرة.

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

اين تقع SMP في نموذج الزوايا الخمس

تعتمد الفوترة في عمان نموذج بيبول بخمس زوايا: انت وعميلك يعمل كل منكما عبر مزود خدمة معتمد، ويستلم جهاز الضرائب البيانات في الوقت نفسه. والارسال المباشر من نظامك الى الجهاز غير مسموح.

ضمن هذه الصورة:

• نقطة الوصول هي الزاوية التي ترسل وتستقبل المستندات فعليا نيابة عن المشارك؛
• وSMP (ناشر بيانات الخدمة) هي دليل العناوين: تنشر اي نقطة نهاية تخدم مشاركا معينا، واي انواع المستندات يمكنه استقبالها؛
• وSML (محدد موقع بيانات الخدمة) هي الطبقة التي تتيح للمرسل العثور على مدخل SMP الصحيح اصلا.

اذن تجيب SMP عن سؤال: الى اين اسلم، وماذا سيقبل الطرف الاخر؟ وهو سؤال توجيه وقدرات. وهي لا تحمل الفاتورة نفسها ابدا. هذا التمييز هو سبب ان الواجهة ادناه لا تشبه واجهة فوترة في شيء.

ما الذي تغطيه واجهة Oman SMP API فعلا

وفق مواصفة جهاز الضرائب، توفر واجهة Oman SMP REST API وصولا امنا ومعياريا الى موارد SMP الخاصة بـتسجيل المشارك في SML، وبيانات خدمات المشارك، ومدخلات دليل بيبول للمشارك.

عمليا يعني ذلك عمليات بهذا الشكل:

• تسجيل مشارك او ازالته (وازالته تصدر ايضا امر حذف الى SML)؛
• ادارة انواع المستندات المسجل المشارك لاستقبالها؛
• ادارة حضور المشارك في دليل بيبول.

وتتبع معرفات المشاركين مخطط بيبول المعتاد — والمثال في المواصفة نفسها بالشكل iso6523-actorid-upis::0088:123456.

وما لا تفعله: لا ترسل الفواتير، ولا تتحقق من محتواها، ولا تصدر احكام امتثال، ولا تحمل شيئا عن النسخة المقروءة للانسان من الفاتورة. ان كنت تبحث عن مسار الفاتورة فانت في المستند الخطا.

المصادقة: mTLS لا مفتاح واجهة

عمليات الكتابة على واجهة Oman SMP API مؤمنة بـmutual TLS وتتطلب شهادة عميل X.509 صالحة. ولا يوجد اختصار عبر مفتاح واجهة.

خطط لهذا مبكرا، فهو عمل بنية تحتية ومشتريات لا برمجة:

• تحتاج شهادة تثق بها منظومتك وتستطيع تقديمها من بيئة النشر؛
• ويجب ان يحافظ عميل HTTP وموزع الحمل واي وسيط خروج على شهادة العميل — وهنا يضيع اغلب الفرق اسبوعا؛
• ودورة حياة الشهادة (التجديد والتدوير والالغاء) تحتاج مالكا قبل الاطلاق لا بعده.

ولاحظ ايضا ان شهادتك الرقمية للمشاركة في بيبول تصدر من OpenPeppol — وهي مستند منفصل عن اي شهادة TLS تقدمها بنيتك التحتية. لا تفترض ان احداهما تغني عن الاخرى.

عنوان الانتاج غير موجود بعد

تنشر المواصفة مضيف SMP الاختباري، وتسجل عنوان SMP للانتاج بانه يزود عند الاطلاق.

نتيجتان جديرتان بالتصميم لهما:

1. اجعل العنوان الاساس اعدادا لا ثابتا. ستستلم مضيف الانتاج متاخرا عما تتمنى.
2. لا تستنتج اسم مضيف الانتاج من الاختباري. المضيف المخمن الذي يستجيب بالصدفة اسوا من مضيف يفشل بصوت عال.

ولن نطبع عنوان انتاج لم ينشره جهاز الضرائب، ولو كان "مرجحا". راجع المواصفة والبوابة عند الاطلاق.

ماذا يعني هذا لمعمارك

• لن تكون SMP الخاصة بك. منصة SMP في عمان مركزية لدى جهاز الضرائب ولا يجوز للمزودين تشغيل منصات خاصة، لذا فالتعامل معها عمل تكامل لا بنية تملكها.
• اغلب المنشات لن تلمس هذه الواجهة ابدا. انها طبقة مزود الخدمة المعتمد. وان كنت خاضعا يختار مزودا فهذه خلفية معرفية، ومزودك يتولى تسجيل المشارك.
• ويمكن لشركة ان تعتمد لتكون مزود نفسها ان استوفت معايير جهاز الضرائب واجتازت الاختبارات المقررة. وهذا هو الطريق للتعامل مع الواجهة مباشرة، ويعني استيفاء معايير الاعتماد نفسها التي يستوفيها اي مزود.
• مسؤولية الامتثال لا تنتقل. ايا كان من ينقل الفواتير، تبقى المسؤولية عنها على منشاة الخاضع.

الى اين بعد ذلك

• اقرا مواصفة SMP API من جهاز الضرائب للحقيقة على مستوى نقاط النهاية — لا تكرر هذه الصفحة المواصفة عمدا، لان نسخة متقادمة من مرجع واجهة اسوا من لا نسخة.
• اقرا مواصفات OpenPeppol لعمان الخاصة بـ PINT-OM وبـ TDD.
• ولمحتوى الفاتورة — النموذج الدلالي والحقول الالزامية — استخدم مساعد حقول PINT-OM ودليل TDD بدل هذه الصفحة.

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

لا تنشر ولا تعتمد على ما يلي دون دليل رسمي حالي:

• عنوان SMP للانتاج — لم ينشر جهاز الضرائب عنوانا؛
• بنية رمز QR او TLV او اسماء الوسوم او ترتيبها او حدود المحارف او عدد البايتات — فهي لم تصدر بعد، وخارج نطاق هذا المستند الذي لا يتضمن اي ربط لـ QR/TLV اصلا؛
• اعداد قواعد التحقق الدقيقة؛
• ان واجهة SMP ترسل الفواتير او تتحقق منها او تخلي طرفها — فهي لا تفعل؛
• ادعاءات مزود بعينه عن اداء نقطة الوصول او جاهزيتها او حالة اعتمادها.