إرسال واستلام الفواتير عبر Peppol

شبكة Peppol هي الشبكة الأوروبية لتبادل الفواتير الإلكترونية المهيكلة بين الشركات والجهات الحكومية. تمر كل فاتورة من نقطة وصول المرسل إلى نقطة وصول المستلم. تقوم منصة Nordlet بإنشاء الفواتير وإشعارات الدائن المتوافقة مع معيار Peppol BIS Billing 3.0، وترسلها وتستقبلها من خلال حساب نقطة الوصول الخاص بشركتك.

تضع شبكة Peppol القواعد التي تحكم كيفية تبادل نقاط الوصول للمستندات فيما بينها، ولكنها لا تحدد طريقة تواصل برمجياتك مع نقطة الوصول الخاصة بك، إذ يمتلك كل مزود واجهة برمجة تطبيقات (API) خاصة به. تتكامل منصة Nordlet مع المزودين التاليين:

المزود	الإرسال	حالة التسليم	الاستلام
Recommand	نعم	عبر الخطافات (webhook) وعند الطلب	نعم
Storecove	نعم	عبر الخطافات (webhook) حصراً	نعم
e-invoice.be	نعم	عبر الخطافات (webhook) وعند الطلب	نعم

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

المتطلبات

• حساب لدى أحد المزودين المذكورين أعلاه، مع تسجيل شركتك على شبكة Peppol من خلاله. يفرض كل مزود رسوماً لقاء خدماته، لذا يُرجى مراجعة قائمة الأسعار الخاصة به.
• رقم ضريبة القيمة المضافة الخاص بالشركات، أو رقم التسجيل، أو معرف Peppol الخاص بها في منصة Nordlet (عبر: الحساب (Account) ← الشركات (Companies) ← معرف Peppol (Peppol ID)). يحتاج كل عميل ترسل إليه فواتير لاحتواء بطاقة الشريك الخاصة به على أحد هذه البيانات أيضاً.

ربط نقطة الوصول الخاصة بك

افتح المسار الحساب (Account) ← الامتثال (Compliance) ← الاتحاد الأوروبي (EU) ← نقطة وصول Peppol (Peppol access point)، ثم اختر المزود المطلوب من حقل المزود (Provider)، واملأ الحقول الخاصة بذلك المزود وفقاً للشرح الوارد أدناه واحفظ التغييرات. اترِك حقل عنوان API الأساسي (API base URL) فارغاً إلا إذا زودك مزود الخدمة بعنوان مختلف. بعد الحفظ، ستعرض الصفحة رابط الخطاف (Webhook URL) الخاص بشركتك بالشكل التالي: https://api.nordlet.com/v1/peppol/webhooks/{provider}/{companyId}، حيث يمثل {provider} اسم المزود (recommand أو storecove أو e-invoice-be)، ويمثل {companyId} معرف شركتك. تمنح منصة Nordlet لكل شركة رابط خطاف (webhook URL) خاصاً بها.

لا تقبل Nordlet استدعاءات الخطاف (webhook calls) إلا إذا أثبتت معرفتها بالرمز السري للخطاف الخاص بك، وبالتالي يتم رفض أي استدعاء لا يصدر من حساب نقطة وصولك. ولا تتواصل Nordlet مع عناوين الإنترنت العامة إلا عند استدعاء نقطة الوصول الخاصة بك.

Recommand

1. في منصة Recommand، افتح صفحة شركتك وانسخ معرف الشركة الخاص بها إلى حقل معرف الحساب في نقطة الوصول (Account ID at the access point).
2. أنشئ مفتاح API في Recommand وانسخ المفتاح والرمز السري الخاص به إلى حقلي مفتاح API (API key) والرمز السري لـ API (API secret).
3. أنشئ نصاً عشوائياً طويلاً لا يعهده سواك أنت وRecommand، وأدخله في حقل الرمز السري للخطاف (Webhook secret) ثم احفظ التغييرات.
4. أنشئ خطافاً (webhook) لشركتك في Recommand مستخدماً رابط الخطاف (Webhook URL) الذي تظهره Nordlet ونفس الرمز السري للخطاف.

تقوم Recommand بتوقيع كل عملية استدعاء للخطاف (webhook call) باستخدام هذا الرمز السري.

Storecove

1. في منصة Storecove، أنشئ كياناً قانونياً (legal entity) لشركتك، بحيث يكون مُمكّناً للإرسال والاستلام، وانسخ معرفه إلى حقل معرف الحساب في نقطة الوصول (Account ID at the access point).
2. تحت قسم مفاتيح API (API Keys) في Storecove، أنشئ مفتاح API وانسخه إلى حقل مفتاح API (API key). واترك حقل الرمز السري لـ API (API secret) فارغاً.
3. ابتكر نصاً عشوائياً طويلاً وأدخله في حقل الرمز السري للخطاف (Webhook secret) ثم احفظ التغييرات.
4. في Storecove، أعدّ خطاف دفع (push webhook) مستخدماً رابط الخطاف الذي تظهره Nordlet، مع تأمينه باستخدام مصادقة HTTP الأساسية (HTTP Basic authentication): أي اسم مستخدم، والرمز السري للخطاف بصفة كلمة المرور.

لا توفر Storecove دالة استعلام عن حالة المستندات المرسلة، لذا ترد حالة التسليم فيها حصراً عبر خطافها (webhook)، ولن يظهر زر التحقق من حالة Peppol (Check Peppol status) في صفحة الفاتورة. يُذكر أن حساب التجربة (sandbox) في Storecove يرسل البيانات عبر شبكة اختبار Peppol، بينما تُستصدَم مفاتيح API الخاصة ببيئة الإنتاج عبر دعم Storecove.

e-invoice.be

1. في تطبيق e-invoice.be، وتحت قسم إعدادات API (API Settings)، انسخ مفتاح API (API key) الخاص بشركتك إلى حقل مفتاح API (API key). واترك حقي معرف الحساب في نقطة الوصول (Account ID at the access point) والرمز السري لـ API (API secret) فارغين. ثم احفظ التغييرات.
2. أنشئ خطافاً (webhook) عبر واجهة برمجة تطبيقات e-invoice.be (باستخدام الطلب POST https://api.e-invoice.be/api/webhooks/) مستخدماً رابط الخطاف الذي تعرضه Nordlet وأحداث الخطاف التالية: document.received وdocument.sent وdocument.sent.failed.
3. انسخ القيمة secret التي تعيدها واجهة برمجة التطبيقات للخطاف الجديد، وألصقها في حقل الرمز السري للخطاف (Webhook secret) داخل منصة Nordlet، ثم احفظ التغييرات مرة أخرى.

تقوم منصة e-invoice.be بتوقيع كل استدعاء للخطاف باستخدام هذا الرمز السري. وفي الشركات التجريبية (sandbox) لدى e-invoice.be، يتم إرسال المستندات المراد إرسالها عبر البريد الإلكتروني بدلاً من إرسالها عبر شبكة Peppol.

إرسال فاتورة

1. أصدر الفاتورة أو إشعار الدائن.
2. تحقق من احتواء بطاقة الشريك الخاصة بالعميل على معرف Peppol أو رقم ضريبة القيمة المضافة أو رقم التسجيل.
3. في صفحة الفاتورة، ضمن قسم التسليم (Delivery)، انقر على إرسال عبر Peppol (Send via Peppol) وأكد العملية. يظهر قسم التسليم للفواتير الصادرة التي لم تُسدَّد بعد، بينما لا يظهر الزر إلا عند اكتمال ربط نقطة الوصول.

تُنشئ منصة Nordlet ملف Peppol وتسلمه إلى نقطة الوصول الخاصة بك. بعد ذلك، تعرض صفحة الفاتورة قسم تسليم Peppol (Peppol delivery):

الحالة	المعنى
قيد الانتظار (pending)	سُلّمت إلى نقطة الوصول؛ ولم يؤكد عميل نقطة الوصول استلامها بعد
مسلّمة (delivered)	أكدت نقطة وصول العميل استلام الفاتورة
مرفوضة (rejected)	رفض العميل الفاتورة؛ ويُعرض سبب الرفض أسفل الحالة
فاشلة (failed)	تعذر تسليم الفاتورة؛ ويُعرض السبب أسفل الحالة في حال توفيره من قِبل نقطة الوصول

تُحدث الحالة نفسها تلقائياً عندما تبلغ نقطة الوصول عن وجود تغيير عبر خطافها (webhook). يؤدي النقر على التحقق من حالة Peppol (Check Peppol status) إلى طلب الحالة الحالية فوراً من Recommand أو e-invoice.be؛ وفي حالة e-invoice.be، يقرأ الخيار أيضاً رد العميل على الفاتورة، حيث يُعرض الرفض (برمز الاستجابة RE) بحالة مرفوضة. يمكن إعادة إرسال الفاتورة المرفوضة أو الفاشلة بعد تصحيح سبب المشكلة. عندما ترفض نقطة الوصول الفاتورة صراحةً، مثلاً لعدم تسجيل العميل على شبكة Peppol، تعرض Nordlet السبب وتبقى الفاتورة غير مرسلة.

يؤدي النقر على زر ملف Peppol بصيغة XML (Peppol XML) في أعلى صفحة الفاتورة إلى تنزيل نفس ملف Peppol دون إرساله.

تحمل عمليات التوريد داخل الاتحاد الأوروبي تاريخ الإصدار بوصفه تاريخ التسليم، ودولة العميل بوصفها دولة التسليم، تماشياً مع متطلبات قواعد Peppol.

استلام الفواتير

عندما تُبلغ نقطة الوصول عن استلام مستند ما عبر خطافها، تقوم Nordlet بتنزيل ملف Peppol من نقطة الوصول. تظهر الفواتير وإشعارات الدائن التي تتلقاها شركتك تحت مسار المشتريات (Purchases) ← التقاط المستندات (Document capture)، حيث تُوسم بأنها مُستلمة عبر Peppol ومقترنة بمعرف Peppol الخاص بالمرسل. تقرأ Nordlet ملف Peppol بنفسها، وبالتالي لا تستهلك عملية الاستلام أي أرصدة للتعرف على المستندات.

1. افتح المستند المستلم.
2. راقب المورد والتواريخ والبنود؛ واختر المورد من قائمة شركائك أو أنشئ مورداً جديداً.
3. انقر على حفظ كمسودة (Save draft). تنشئ Nordlet مسودة فاتورة مشتريات، أو مسودة إشعار دائن للمشتريات في حالة استلام إشعار دائن، مع إرفاق ملف Peppol الأصلي بها. قم بتسجيلها بالطريقة التي تتبعها مع أي فاتورة مشتريات أخرى.

لا يمكن أن تكون بنود فواتير المشتريات في Nordlet سالبة القيمة. يتم توزيع الخصومات والرسوم على مستوى المستند بأكمله، وكذلك البنود سالبة القيمة، على البنود الأخرى التي تتبنى نفس معدل ضريبة القيمة المضافة. أما المبالغ التي تعجز أي من بنود ذات معدل الضريبة عن تحملها، مثل إعادة صنف يخضع لمعدل ضريبة لا توجد بنود أخرى له في الفاتورة، فتُعرض في جدول ثاني: بنود إشعار الدائن (Credit note lines) بالنسبة للفاتورة المستلمة، أو بنود الفاتورة (Invoice lines) بالنسبة لإشعار الدائن المستلم. يُحفظ هذان البندان في مستند ثانٍ لنفس المورد: إشعار دائن مشتريات مقابل الفاتورة الجديدة، برقم يبدو بالشكل "-CR"، أو فاتورة مشتريات برقم "-INV". يمثل المستندان معاً المجموع الإجمالي للمستند المستلم.

التحقق من تسجيل العميل على شبكة Peppol

يؤدي إرسال طلب POST /v1/peppol/participants/lookup مصحوباً بـ partnerId أو participantId (بالصيغة ":") إلى الاستعلام من شبكة Peppol عما إذا كان المستلم مسجلاً والمستندات التي يوافق على استلامها. تعمل هذه الميزة دون الحاجة لوجود نقطة وصول.

تنفيذ نفس العمليات عبر واجهة برمجة التطبيقات (API)

المهمة	الاستدعاء (Call)
ربط نقطة الوصول	POST /v1/declarations/configs/update مع تمرير المعلمة system: "peppol" وحقل config الذي يحتوي على provider (بقيم مثل recommand أو storecove أو e-invoice-be) وaccountId وapiKey وapiSecret وwebhookSecret بالإضافة إلى الحقل الاختياري apiBaseUrl
استلام خطاف نقطة الوصول	POST /v1/peppol/webhooks/{provider}/{companyId}، ويتم استدعاؤه بواسطة نقطة الوصول
تنزيل ملف Peppol	POST /v1/sales/invoices/peppol-xml
الإرسال	POST /v1/sales/invoices/peppol-send (يُرجع الخطأ 422 في حال عدم توفر نقطة وصول)
قراءة حالة التسليم	POST /v1/sales/invoices/peppol-status (يُرجع الخطأ 422 مع Storecove)؛ وتحمل الفواتير الحقول التالية: peppolMessageId وpeppolStatus وpeppolDetail وpeppolSentAt وpeppolCheckedAt
العثور على المستندات المستلمة	POST /v1/capture/documents/list؛ وتحمل المستندات المستلمة القيمتين provider: "peppol" وsenderId
تحويل مستند إلى فاتورة مشتريات	POST /v1/capture/documents/confirm، مع تمرير الحقل oppositeLines للمستند الثاني

أحداث الخطاف (Webhook events): sale_invoice.peppol_sent وsale_invoice.peppol_delivered وsale_invoice.peppol_rejected وsale_invoice.peppol_failed وdocument_capture.peppol_received. يُرجى مراجعة اصطلاحات واجهة برمجة التطبيقات للاطلاع على تفاصيل الأخطاء ومعاملات الحياد (idempotency) والخطافات.