سواء كنت تمثل شركة صغيرة أو مؤسسة كبيرة أو مزود برمجيات، توفر لك واجهة برمجة التطبيقات (API) من Qvalia طريقة موحدة ومستندة إلى المعايير للتكامل مع شبكة Peppol، مع دعم اختياري لتدفقات EDI إضافية ومعالجة المستندات الذكية وإثراء البيانات.

من خلال خدمة " Invoicing API"، يمكنك التعامل مع رسائل Peppol المتعلقة بالفواتير، مثل BIS Billing الفاتورة)، BIS Billing Note (إشعار الائتمان)، وBIS Self-Billing Invoice (فاتورة الفوترة الذاتية)، وBIS Self-Billing Credit Note (إشعار الائتمان للفوترة الذاتية)، BIS Invoice Response الفاتورة)، كما يمكنك، عند الحاجة، استكمالها بـ"Message Level Response" (رد على مستوى الرسالة) من أجل الإقرارات الفنية المتعلقة بالفواتير ورسائل Peppol الأخرى.

يمكن لواجهة برمجة التطبيقات (API) أن:

في هذا الدليل، ستتعلم كيفية:

توفر واجهة برمجة تطبيقات Peppol واجهة موحدة للرسائل التجارية الإلكترونية عبر Peppol وEDI. وقد صُممت لدعم السيناريوهات الأساسية مثل:

يُستخدم مبدأ تصميم مشترك في جميع نقاط النهاية:

وهذا يعني أنه يمكنك التفكير من منظور الرسائل التجارية بدلاً من الشبكات والبروتوكولات. فأنت تقوم بإنشاء مستندات صالحة تستند إلى لغة UBL؛ بينما تتولى Qvalia معالجة طبقة Peppol وEDI في الخلفية.

لا يتطلب البدء في استخدام واجهة برمجة تطبيقات Peppol من Qvalia سوى بعض الأمور الأساسية:

حساب Qvalia
تم تسجيل مؤسستكم كعميل لدى Qvalia. وستتلقون رقم تسجيل الحساب الذي يحدد هوية حسابكم بشكل فريد في جميع المعاملات.

مفتاح واجهة برمجة التطبيقات (API)
تتم عملية المصادقة عبر مفتاح واجهة برمجة التطبيقات (API)، مع وجود مفاتيح منفصلة لبيئات الاختبار والإنتاج. تتم جميع الاستدعاءات عبر بروتوكول HTTPS باستخدام بروتوكول TLS الحديث.

رقم تسجيل الحساب في مسار عنوان URL
تتضمن طلبات المعاملات رقم حسابك (accountRegNo) في المسار. على سبيل المثال:

اختيار التنسيق: JSON أو XML
يمكنك اختيار JSON أو XML عبر رؤوس HTTP القياسية (Content-Type و Accept). ويكون JSON هو التنسيق الافتراضي في حالة عدم تحديد خيار صريح.

بمجرد توفر هذه العناصر، تكون جاهزًا لبدء اختبار حركة مرور Peppol باستخدام Qvalia.

يشرح هذا القسم خطوات عملية التكامل الأولية النموذجية بين نظامك وواجهة برمجة تطبيقات المعاملات (Transaction API) الخاصة بـ Qvalia، ويغطي كلاً من إرسال واستلام فواتير Peppol.

ابدأ بالدمج مع بيئة الاختبار:

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

في ملف التكوين الخاص بك، قم بتخزين:

يجب أن يتضمن كل طلب ما يلي:

تستخدم جميع المعاملات معيار UBL 2.1 كمعيار أساسي.

يمكنك إما:

تحدد العناوين الشكل:

JSON (الافتراضي)

XML

تتيح لك هذه المرونة دمج واجهة برمجة تطبيقات Peppol في كل من البيئات التي تعتمد على JSON أولاً وتلك التي تعتمد على XML أولاً.

بعد ذلك، قم بربط نموذج الفواتير الداخلي الخاص بك بعناصر UBL. ويتوفر كل من UBL JSON وUBL XML.

والهدف هو ضمان ما يلي:

ثم تقوم بتحويل هذه البيانات إلى صيغة JSON أو XML، حسب الصيغة التي تختارها. أما بالنسبة للفواتير الواردة، فتستخدم نفس بنية UBL عند قراءة البيانات والتحقق من صحتها وتعيينها من Qvalia إلى نموذجك الداخلي.

الخطوة 5أ: إرسال فاتورة Peppol صادرة

بعد أن أصبحت الحمولة الصادرة جاهزة، مثال على نقطة النهاية:

تشمل:

تقوم Qvalia بالتحقق من صحة الفاتورة، وتوجيهها عبر شبكة Peppol أوVAN ثم ترسل ردًا يتضمن المعرّفات والحالة.

لاسترداد الفواتير الواردة من Qvalia عبر واجهة برمجة التطبيقات (API)، عادةً ما تقوم بما يلي:

اتصل بنقطة النهاية الواردة، على سبيل المثال:

ويمكنك أيضًا:

ثم يتم ربط ملف JSON أو XML الذي تم إرجاعه من UBL بنموذج البيانات الداخلي الخاص بك من أجل التسجيل أو الموافقة أو المعالجة الإضافية.

تستخدم واجهة برمجة التطبيقات الخاصة بالمعاملات رموز حالة HTTP يمكن التنبؤ بها، والتي يمكنك ربطها بالسجلات وعمليات المراقبة ورسائل المستخدمين. الأنماط الشائعة:

تنطبق هذه الأنماط سواء كنت ترسل الفواتير أو تستلمها.

بالإضافة إلى استجابات واجهة برمجة التطبيقات (API)، يمكنك دائمًا تسجيل الدخول إلى Qvalia ومراجعة الأنشطة في سجل المعاملات. يمنحك ذلك عرضًا عبر واجهة المستخدم لما يحدث في عملية التكامل الخاصة بك، بما في ذلك، على سبيل المثال:

يُعد سجل المعاملات مفيدًا في:

تقدم رموز حالة HTTP وسجل المعاملات معًا صورة شاملة: يمكن لنظامك الاستجابة برمجيًا للردود، بينما يمكن لفريقك التحقيق والمتابعة مباشرةً في Qvalia عند الحاجة.

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

تشمل الامتدادات النموذجية ما يلي:
الطلبات. استلام وإرسال الطلبات المنظمة إلكترونيًا
الردود على الطلبات وتعديلاتها. تأكيد الطلبات أو تعديلها أو إلغاؤها
الكتالوجات. حفظ معلومات المنتجات والأسعار في الكتالوجات الإلكترونية
إشعارات الشحن. إرسال معلومات الشحن
الردود على مستوى الرسائل. تتبع إقرارات الاستلام على المستوى الفني والتجاري

ونظرًا لأن كل ذلك يستخدم نفس تصميم واجهة برمجة التطبيقات (API) ونموذج المصادقة ونموذج بيانات UBL 2.1، فلن تحتاج إلى مشاريع أو بوابات منفصلة لكل نوع من أنواع المستندات. وبذلك، يمكنك تلبية حالات استخدام جديدة مع تطور متطلبات عملك أو متطلبات عملائك.

وهنا يتجسد الوعد بـ«واجهة برمجة تطبيقات Peppol واحدة مهما كانت الاحتياجات»؛ حيث يخدم نفس نظام التكامل الموردين الصغار والشركات الكبيرة، فضلاً عن سيناريوهات المنصات المعقدة.

إذا كنت مزودًا للبرمجيات — وتدير منصة لإصدار الفواتير، أو نظام تخطيط موارد المؤسسات (ERP)، أو حلًا محاسبيًّا، أو منصة تكامل — فإن متطلباتك تختلف قليلاً. باستخدام واجهة برمجة تطبيقات الشركاء (Partner API) من Qvalia، يمكنك إعداد تكوين متعدد المستأجرين لتبادل الرسائل مع المستخدمين النهائيين، بما في ذلك إدارة Peppol ID .

تكون واجهة برمجة التطبيقات (API) الخاصة بالشركاء لـ Peppol ضرورية إذا كنت بحاجة إلى:

وقد صُمم نموذج «كفاليا» الذي يركز على الشركاء خصيصًا لهذا الغرض.

يقوم تطبيقك بإنشاء أو استخدام حمولات UBL (الفواتير، الطلبات، وما إلى ذلك) بنفس الطريقة المتبعة مع واجهة برمجة تطبيقات المعاملات القياسية. لإرسال المعاملات أو استلامها نيابة عن عميل معين، يمكنك استدعاء واجهة برمجة تطبيقات المعاملات من خلال نمط URI المسبوق ببادئة الشريك:

على سبيل المثال:

تقوم Qvalia بتوجيه الرسائل واستلامها كما لو كانت قد أُرسلت أو استُلمت مباشرةً من قبل العميل، مع إمكانية تتبع كاملة لكل حساب.

بالإضافة إلى خدمات النقل والربط، توفر «كفاليا» أيضًا واجهة برمجة التطبيقات (API) الخاصة بالتنقيح، والتي يمكنها إثراء المعاملات من خلال تصنيف البنود الفردية، والمعالجة قبل وبعد إتمام المعاملة، وغير ذلك، كما يمكنها استخراج مستندات PDF وتحويلها إلى بيانات غنية ومنظمة وموثوقة بأقل جهد ممكن.

تم تصميم واجهة برمجة تطبيقات Enrichment لتكون خدمة غير متزامنة:

ويمكن أن تشمل هذه النتيجة ما يلي:

يبدو التكامل النموذجي كما يلي:

أرسل فاتورة لتعزيز البيانات
استدعِ نقطة نهاية، وأرفق ملف الفاتورة وأي بيانات وصفية ذات صلة، ثم
احفظ معرّف الاستقصاء (pollingId) الذي تم إرجاعه.

استدعاء "
" للتحقق من اكتمال العملية. يُنصح باستدعاء هذه الوظيفة على فترات زمنية مناسبة. أثناء المعالجة، تؤكد واجهة برمجة التطبيقات (API) أن المهمة لا تزال قيد التنفيذ. وعند الانتهاء، تُرجع حالة العملية ورابطًا إلى نتيجة عملية الإثراء.

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

في جميع الأحوال، يعد الوصول إلى هذه التقنية أمرًا بسيطًا: حيث يتم استخدام نفس الحساب ونموذج الأمان المطبق في واجهة برمجة التطبيقات الخاصة بالمعاملات (Transaction API)، بالإضافة إلى مجموعة صغيرة من نقاط النهاية المحددة بدقة.

تم تصميم واجهة برمجة التطبيقات (API) الخاصة بـ Qvalia لتوفر لك نقطة وصول مبسطة وقابلة للتوسع إلى شبكة Peppol، بغض النظر عن نوع شركتك:

الخطوة التالية واضحة ومباشرة: قم بالاتصال ببيئة الاختبار، وأرسل أول فاتورة تجريبية، وابدأ في التخطيط لكيفية جعل Peppol وEDI وعمليات الإثراء جزءًا لا يتجزأ من عملياتك أو منتجك — بدلاً من أن تكون مشروعًا منفصلاً ومعقدًا.