تكامل الفوترة عبر API للبرمجيات المخصصة — أين يتوقف دور شفرتك

إذا كانت شركتك تشغّل برنامج فوترة خاصا بها — نظاما داخليا، أو منتجا بنيتموه، أو ERP تتحكمون به — فإن الفوترة الالكترونية لا تستبدل هذا البرنامج، بل ترسم حدا يمر عبره. جزء من العمل يبقى داخل شفرتك، وجزء ينتقل إلى مزود خدمة معتمد، وخطوة واحدة تتم على البوابة ولا تستطيع أي واجهة برمجية القيام بها عنك.

هذا الدليل يرسم ذلك الحد. وهو مكتوب للفريق الذي سيكتب التكامل فعليا، وللشخص الذي يقرر حجم ما سيُبنى منه.

أين يقع برنامجك

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

الزاوية	من	ما تعنيه لتكاملك
C1	المورّد — أنت	برنامجك. ينشئ بيانات الفاتورة.
C2	مزود الخدمة المعتمد لديك	يستقبل منك، ويتحقق، ويرسل. الطرف الوحيد الذي تخاطبه شفرتك.
C3	مزود خدمة المشتري	ليس شأنك.
C4	المشتري	يستلم الفاتورة.
C5	جهاز الضرائب العمانية	يستقبل البيانات الضريبية من المزودين. شفرتك لا تستدعيه أبدا.

مساران يخرجان عن هذا الشكل، وكلاهما يسهل اغفاله عند تحديد النطاق:

• التصدير يسير C1 ← C2 ← C5، لأن C3 وC4 خارج الشبكة.
• الاستيراد يُبلّغ عنه بالفوترة الذاتية: تُبلّغ الشركات برقم البيان، ويجب اصدار فواتير ذاتية لاستيراد السلع والخدمات. كما تُصدر فواتير الاحتساب العكسي (RCM) ذاتيا، ويحمل قاموس البيانات نوع معاملة خاصا بها.

التسلسل — بما فيه الخطوة التي لا تقوم بها أي واجهة برمجية

تحقق من فترة التطبيق الخاصة بك أولا. كل ما هنا مرتبط بالتسجيل في ضريبة القيمة المضافة وبالمرحلة التي تقع فيها. ينشر جهاز الضرائب أداة تحقق تأخذ رقم VATIN، ويلتزم بالتواصل قبل ستة أشهر على الأقل من بدء ادخالك. والمرحلة الأولى تشمل مجموعة محددة من الخاضعين للضريبة، وليس الجميع. اعرف موقعك قبل أن تخطط لأي عمل هندسي.

بعد ذلك:

1. اختر مزودا من القائمة الرسمية للمعتمدين. ينشرها جهاز الضرائب على بوابة الفوترة. وادعاء المزود نفسه ليس دليلا على الاعتماد. يغطي دليلنا عن اختيار المزود ما ينبغي سؤاله، ويغطي دليل القائمة المعتمدة كيفية قراءة السجل.
2. تفاوض ووقّع — قبل خطوة البوابة، لا بعدها. تطلب منك البوابة تسجيل مرحلة تعاملك مع المزود، ويجب اكتمال كل المراحل قبل أن يمضي الارتباط. والتسلسل مقصود: لا يمكن للارتباط أن يسبق العقد.
3. ارفع طلب الارتباط على بوابة الفوترة. هذا هو الاجراء الموثوق، وهو يدوي. يطلب الخاضعون للضريبة الارتباط بمزود خدمة معتمد عبر البوابة. ويمكنك الارتباط بـمزود واحد في المرة.
4. نفّذ التكامل. هنا تقع شفرتك — وهو تكامل خاص بالمزود بحكم التصميم. جهاز الضرائب لا يوحّد جانب المزود من الارتباط، بل يحدد كل مزود عملية التكامل الخاصة به.
5. كن متكاملا مع مزودك في موعد بدء التطبيق أو قبله. ينص جهاز الضرائب على ذلك صراحة.

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

أين يتوقف دور شفرتك

هذا هو الجدول الذي ينبغي أن تتناقشوا حوله داخليا قبل كتابة أي شيء.

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

الصف الأخير هو الأهم تجاريا. يستطيع المزود التحقق من فاتورتك وتبقى أنت المسؤول عنها. شراء التكامل لا يشتري لك ضمانا.

ملف PDF لديك لا يموت — بل يغيّر وظيفته

الصيغة المهيكلة الالزامية للفاتورة هي XML. وملف PDF ليس فاتورة الكترونية. لكن توليد المستندات لديك لا يصبح شفرة ميتة، لأن الفاتورة المقروءة يبقى لها دور، خاصة في B2C.

يصف جهاز الضرائب مسار B2C هكذا: يرسل البائع الفاتورة إلى مزود خدمته، ويرسل المزود البيانات الضريبية إلى الجهاز، ويتبادل البائع النسخة المقروءة مع المشتري بآليته الحالية — ورقية أو PDF أو غيرها — خارج شبكة الفوترة. ويجب أن تلتزم تلك النسخة المقروءة بالمواصفات التي يحددها الجهاز، وستتطلب رمز QR.

لذلك خطط لمخرجَين من نموذج مصدري واحد، لا لمخرج واحد يغيّر شكله.

حد البناء أم الشراء

طبقة واحدة فقط تعود إليك حقا: من يحوّل بيانات فاتورتك إلى PINT-OM XML.

الخيار الرقيق. ترسل لمزودك بيانات الفاتورة بالصيغة التي تقبلها واجهته، ويتولى هو بناء XML والتحقق منه. أسرع في الاطلاق. لكن التحويل — وهو الجزء الذي يرمّز قواعد عمان فعليا — يبقى داخل نظامه، وأنت مرتبط بمزود واحد في المرة.

الخيار السميك. تبني PINT-OM XML بنفسك وتسلّمه للمزود للتحقق والارسال والتبليغ. عمل أكبر. لكن التحويل يبقى أصلا تملكه ويمكنك أخذه معك.

في الحالتين ينطبق الانضباط نفسه، وهو الشيء الوحيد الجدير بالعمل اليوم: احتفظ بنموذج فاتورة مصدري داخل تطبيقك، وحوّل إلى PINT-OM عند الحد. لا تضمّن الفوترة مباشرة في شاشات الادخال أو قوالب المستندات. ويمر دليلنا PINT-OM للمطورين على الطبقات — النموذج الدلالي، وربط الصياغة، وقوائم الرموز، وSchematron — وعلى مستند البيانات الضريبية (TDD)، وهو تقرير تنظيمي منفصل لجهاز الضرائب، وليس شيئا تتبادله مع المشتري.

لماذا لا يكون بناء المحوّل عمل اليوم

المواصفة حقيقية: مواصفات عمان في بيبول منشورة، وPINT-OM له اصدار صادر. لكن ثلاثة أمور لا تزال تتحرك، وكلها تقع داخل المحوّل:

• قاموس البيانات مسودة للتشاور. يذكر جهاز الضرائب أن النسخة المتاحة من قاموس البيانات وقواعد العمل مسودة عُممت على المشاركين في المرحلة الأولى وعلى مزودي الخدمة المحتملين، وأن نسخة رسمية نهائية ستصدر بعد دراسة ملاحظات التشاور. والحقول الالزامية والاختيارية والشرطية معرّفة هناك.
• دقة المبالغ قد تتغير. تحصر مواصفات عمان حاليا المبالغ على مستوى المستند في خانتين عشريتين، مع تحديث مخطط لدعم ثلاث خانات. لا تضمّن الدقة في الشفرة.
• مواصفة محتوى QR غير منشورة، ونطاق QR متنازع عليه (انظر أدناه).

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

الارتباط الذي تختاره

ثلاث حقائق تتراكم، وتستحق أن تُقرأ معا قبل التوقيع:

• يمكنك الارتباط بـمزود معتمد واحد في المرة؛
• سطح التكامل لدى المزود غير موحّد من جهاز الضرائب، فعملك خاص به؛
• طلب الارتباط بمزود جديد هو ما يفصلك عن مزودك الحالي — التبديل لا يبدأ بفصل مرتب. ويغطي دليلنا عن الارتباط والتبديل مطبات التوقيت.

لا شيء في ذلك سبب لعدم التكامل. لكنه سبب لأن تسأل، كتابة وقبل التوقيع، كيف يبدو الخروج: هل تستطيع استرجاع XML الخاص بفواتيرك وسجل التحقق، وبأي صيغة.

هل يمكنك أن تكون مزود الخدمة الخاص بك؟

نعم — وبالنسبة لشركة برمجيات، هذا هو السؤال الاستراتيجي الحقيقي المختبئ خلف السؤال التقني. جهاز الضرائب صريح: أي شركة تستوفي معايير مزود الخدمة وتجتاز الاختبارات المقررة يمكن اعتمادها، ويمكنها بعد ذلك أن تكون مزود الخدمة الخاص بها. ولا يوجد موعد نهائي للتقدم، ويُسمح بحل بعلامة بيضاء إذا ظلت المعايير والاختبارات مستوفاة.

والمعيار خط عمل كامل، وليس اختصارا:

المتطلب	ما ينص عليه جهاز الضرائب
رأس المال	رأس مال مدفوع لا يقل عن 6,000 ريال عماني.
الأمن	شهادة ISO/IEC 27001 لنظام ادارة أمن المعلومات.
الاستمرارية	شهادة ISO 22301، أو السجل التجاري كدليل بديل.
الخبرة	سنتان من الخبرة التشغيلية — سنة واحدة لحاملي بطاقة ريادة. ويمكن للمتقدم حديث التأسيس احتساب خبرة الشركة الأم.
السجل	ينبغي أن يتضمن السجل التجاري نشاطين متعلقين بتقنية المعلومات.
الحضور	يمكن للمزودين الأجانب والخليجيين المشاركة، لكنهم يحتاجون وجودا محليا في عمان.
الاختبار	حزمة اختبار eDelivery وحزمة اختبار PINT OM لـ C2–C3، على منصة Peppol Testbed الرسمية.

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

بالنسبة لفواتير شركة واحدة، فان شهادة الأمن وحدها ستفوق عادة أي وفر. هذا المسار منطقي إذا كنت تنوي خدمة شركات أخرى، لا خدمة نفسك.

إذا كنت ضمن مجموعة ضريبية

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

ما لم يُحسم — وما يجب ألا تبني تصميمك عليه

نقطتان متنازع عليهما فعليا بين مستندين رسميين حاليين لجهاز الضرائب. كلا المستندين ساري، وكلاهما صادر عن الجهاز نفسه، ولا يلغي أحدهما الآخر.

توقيت ارسال B2C. تذكر الأسئلة الشائعة الشهرية (30 يونيو 2026) نافذة 24 ساعة لـ B2C. وتقول أسئلة مزودي الخدمة إن توقيت B2C لا يزال قيد المناقشة، ولا يوجد اطار زمني محدد بعد، وإن التوجيه سيصدر لاحقا. المصادر متعارضة. خطط للحالة الأشد إذا كنت تبيع للمستهلكين، واعتبرها مؤقتة، وتحقق مع مزودك قبل الاعتماد عليها.

نطاق QR. تذكر الأسئلة الشائعة الشهرية أن QR يسري على معاملات B2C كاملة كانت أو مبسطة. وتقول أسئلة مزودي الخدمة إن QR يُتوقع أن يكون الزاميا للفواتير المبسطة (B2C) فقط، وإن التفاصيل لم تصدر بعد. المصادر متعارضة.

فوق ذلك، مواصفة محتوى QR نفسها غير منشورة. تشير الأسئلة الشائعة الشهرية إلى ملحق في معمارية بيبول عمان لما يوضع داخل الرمز، وذلك الملحق غير متاح للعموم. فإذا كنت تبيع للمستهلكين، فهذا عمل لا تستطيع تحديد مواصفته بعد — اعتبره نطاقا مجهولا بدلا من تخمينه.

أما إذا كنت B2B فقط، فلا يمسّك أي من الثلاثة.

أسئلة تستحق أن تسألها للمزود — نسخة المطورين

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

• هل يمكننا رؤية بيئة الاختبار الخاصة بعمان لديكم قبل التوقيع، والاختبار بأمثلة فواتيرنا؟
• هل نرسل لكم PINT-OM XML أم صيغتكم الخاصة؟ وإذا أردنا ارسال XML، هل تقبلونه؟
• كيف تُظهرون فشل Schematron — هل نحصل على القاعدة الخام ورسالة مترجمة معا؟
• ما مسار الانتقال من الاختبار إلى الانتاج؟
• إذا غادرنا، ماذا نستعيد: البيانات المصدرية، وXML، وسجل التحقق، وبأي صيغة، وإلى متى نستطيع الوصول إليها؟
• أي كيان قانوني يوقّع عقدنا، وهل هو الكيان المذكور في قائمة جهاز الضرائب للمعتمدين؟

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

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

• نافذة ارسال محسومة لـ B2C، أو نطاق محسوم لـ QR؛
• محتويات رمز QR أو بنيته أو حدوده؛
• قائمة نهائية بالحقول الالزامية أو عدد نهائي لقواعد التحقق؛
• أن أي مزود أو منتج يدعم PINT-OM دعما كاملا؛
• أن قاموس البيانات الحالي هو المواصفة النهائية المعتمدة؛
• أن استخدام مزود ينقل عنك مسؤولية الامتثال أو الأرشفة.

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

تحقق من فترة التطبيق الخاصة بك. وإذا كان لديك وقت، فأنفقه على جرد البيانات المصدرية وحالات الاختبار بدلا من المحوّل — فهذه تحتفظ بقيمتها عبر أي تعديل في المواصفة. بعد ذلك خذ أسئلة المطورين أعلاه إلى المزودين المدرجين في قائمة جهاز الضرائب، واتخذ قرار البناء أم الشراء بعد أن تعرف واجهة من ستبني عليها فعلا.