نظرة عامة على واجهة برمجة تطبيقات Peppol
من مفتاح واجهة برمجة التطبيقات (API) إلى الطلب الأول
يقدم فريق التهيئة لدينا الدعم لك خلال مراحل الدمج والاختبار.
export ACCOUNT_REG_NO=YOUR_ACCOUNT_REGISTRATION_NUMBER
# Identifies the account in every Transaction API requestاستخدم هذه القيمة في مسار الطلب لكل استدعاء لواجهة برمجة تطبيقات المعاملات.
export QVALIA_API_KEY=YOUR_SANDBOX_API_KEY
export QVALIA_BASE_URL=https://api-test.qvalia.comاحرص على الفصل بين بيانات اعتماد بيئة الاختبار وبيانات اعتماد بيئة الإنتاج.
curl -X POST \
${QVALIA_BASE_URL}/transaction/${ACCOUNT_REG_NO}/invoices/outgoing \
-H Authorization:${QVALIA_API_KEY} \
-H Content-Type:application/json \
-d @invoice.jsonيؤكد الرد استلام المستند. وتُرسل نتائج التحقق وحالة التسليم عبر «ويب هوكس» أو من خلال حالة المستند.
export QVALIA_API_KEY=YOUR_PRODUCTION_API_KEY
export QVALIA_BASE_URL=https://api.qvalia.comتتبع عملية المعالجة والتسليم من خلال «webhooks» أو حالة المستند.
حساب واحد، ست واجهات برمجة تطبيقات
API الفوترة
إرسال واستلام الفواتير ومذكرات الائتمان عبر Peppol، مع التحقق من صحتها قبل التسليم.
API الطلبات
إرسال واستلام أوامر الشراء عبر Peppol، بما في ذلك الردود على الأوامر والتعديلات والإلغاءات، وذلك لتغطية مسار عملية الطلب بالكامل.
واجهة برمجة التطبيقات للشركاء
قم بإنشاء وإدارة حسابات العملاء النهائيين ومعرّفات Peppol من منصتك الخاصة، مع استخدام «webhooks» لمتابعة أحداث المستندات.
API التعرف الضوئي على الحروف
استخراج البيانات المنظمة من فواتير PDF لمراجعتها ومعالجتها لاحقًا.
API إثراء البيانات
تصنيف المستندات والبنود، وإثراء المعاملات بالبيانات المنظمة.
API المحاسبة
إنشاء اقتراحات للتسجيل من الفواتير الواردة لتسريع عملية المراجعة والتسجيل.
طرق أخرى للتواصل
عندما لا يكون تكامل واجهة برمجة التطبيقات (API) هو الحل المناسب، أو عندما تحتاج إلى ما هو أكثر من مجرد تبادل المستندات.
- SFTP
تبادل الملفات بتنسيق XML أو CSV عبر SFTP عندما لا يكون تكامل واجهة برمجة التطبيقات (API) خيارًا متاحًا. - موصلات أنظمة تخطيط موارد المؤسسات (ERP)
موصلات جاهزة للاستخدام لأنظمة تخطيط موارد المؤسسات (ERP) وأنظمة المحاسبة الشائعة. - خادم Peppol MCP
يمنح وكلاء الذكاء الاصطناعي وعملاء MCP وصولاً منظماً إلى المعاملات، والبنود التفصيلية، وحالة التسليم، والتحقق من الصحة. - Punchout
ربط كتالوج المورد بنظام المشتريات الخاص بالمشتري. - عملية الدفع بين الشركات (B2B)
أضف خيار الدفع والفوترة بين الشركات (B2B) إلى متجر WooCommerce، مع التسليم عبر Peppol.
مرجع Peppol للمطورين
تتناول هذه الصفحة واجهات برمجة التطبيقات (API) الخاصة بـ Qvalia ووثائق Peppol التي تنقلها. أما معيار Peppol الذي تستند إليه هذه الواجهات، بما في ذلك المواصفات وقواعد التحقق من الصحة وقوائم الرموز، فيتم تناوله في وثائق Peppol ودليل التنفيذ الخاص بنا. ويمكن الاطلاع على المرجع الكامل لنقاط النهاية على api.qvalia.io. وتُنشر مواصفات Peppol المعيارية من قِبل OpenPeppol على docs.peppol.eu.
وثائق Peppol وواجهات برمجة التطبيقات (API) الخاصة بها
| وثيقة | مواصفات Peppol | واجهة برمجة تطبيقات Qvalia |
| الفاتورة | Peppol BIS Billing .0 | واجهات برمجة التطبيقات الخاصة بالفواتير |
| مذكرة ائتمان | Peppol BIS Billing 3.0، إشعار ائتمان | واجهات برمجة التطبيقات الخاصة بمذكرات الائتمان |
| الطلب والاستجابة للطلب | Peppol BIS Ordering | واجهات برمجة التطبيقات الخاصة بالطلبات، واجهات برمجة التطبيقات الخاصة باستجابات الطلبات |
| اتفاقية الطلب | Peppol BIS Order Agreement | طلب واجهات برمجة التطبيقات (API) الخاصة بالاتفاقيات |
| تغيير الطلب وإلغاؤه | Peppol BIS Advanced Ordering | واجهات برمجة التطبيقات (API) لتعديل الطلبات، واجهات برمجة التطبيقات (API) لإلغاء الطلبات |
| إشعار الشحن | Peppol BIS Despatch Advice | واجهات برمجة التطبيقات الخاصة بإشعارات الشحن |
| الكتالوج | Peppol BIS Catalogue مع الرد | واجهات برمجة التطبيقات الخاصة بالكتالوجات |
| حالة التسليم | الاستجابة على مستوى الرسالة والحالة على مستوى الرسالة | واجهات برمجة التطبيقات (API) للاستجابة على مستوى الرسالة، واجهات برمجة التطبيقات (API) للحالة على مستوى الرسالة |
التحقق من الصحة والأخطاء
قوائم الأكواد
التوجيه والبحث
الاختبار والتشغيل
صندوق الرمل
اختبر عملية التكامل مع أنظمتك الخاصة دون التأثير على العملاء الفعليين أو التدفقات المالية.
إدارة الإصدارات
يتم إصدار التغييرات الجذرية كإصدار جديد من واجهة برمجة التطبيقات (API)، مع إخطار مسبق مدته شهر واحد على الأقل.
حالة النظام
اطلع على حالة توفر الخدمة الحالية وآخر المستجدات بشأن الأعطال.
الأمن
اقرأ عن كيفية تعامل شركة «كفاليا» مع أمن المعلومات واستمرارية الأعمال والثقة.
هل تستخدم «بيبول» لأعمالك أم لعملائك؟
Peppol Access Point
هل ترغب في إرسال واستلام مستندات Peppol لشركتك؟ اتصل بنقطة وصول Peppol الخاصة بـ Qvalia وقم بدمجها مع نظام تخطيط موارد المؤسسة (ERP) الخاص بك أو من خلال واجهة برمجة التطبيقات (API).
حلول الشركاء
قدم خدمة Peppol لعملائك من خلال النموذج الذي يتناسب مع دورك. استخدم خدمة Peppol المدمجة في منتجك عبر واجهة برمجة التطبيقات (API) الخاصة بـ Qvalia، أو قم بتشغيل نقطة وصول مستضافة تحت هوية مزود خدمة Peppol الخاصة بك.
الأسئلة التي يطرحها المطورون
يمكنك الاطلاع على المزيد من إرشادات التنفيذ في قاعدة المعرفة الخاصة بنا.
هل توجد بيئة اختبار؟
نعم. تستخدم بيئة الاختبار على api-test.qvalia.com مفتاح API منفصل، مما يتيح لك إجراء الاختبارات دون التأثير على العملاء الفعليين أو التدفقات المالية. اتبع الدليل التفصيلي لـ Peppol API المتوفر في قاعدة المعرفة.
ما هي التنسيقات التي تقبلها واجهة برمجة التطبيقات (API)؟
JSON بشكل افتراضي، أو XML. ويستخدم كلاهما هياكل تستند إلى UBL 2.1 لنقاط نهاية مستندات Peppol ذات الصلة. قم بتعيين Content-Type و Accept على application/json أو application/xml. راجع أنواع رسائل Peppol الخاصة بالمستندات والعمليات التجارية التي تدعمها الشبكة.
كيف يمكنني إتمام عملية المصادقة؟
باستخدام مفتاح API في رأس «Authorization»، أو باستخدام رمز مميز قصير الأمد (JWT) تحصل عليه من نقطة النهاية /token باستخدام مفتاحك. تحصل على مفاتيح منفصلة للاختبار والإنتاج.
كيف أعرف ما إذا كان المستند قد تم تسليمه أم لا؟
اشترك في إشعارات الويب (webhooks)، أو قم باستعلام واجهة برمجة التطبيقات (API). ترسل Qvalia أحداثًا عند وصول المستند، وعند تسليمه، وعند فشل التسليم. بالنسبة لرسائل الاستجابة على مستوى Peppol، راجع «حالة مستوى الرسالة» في قاعدة المعرفة.
هل يتعين عليّ تنفيذ نقل البيانات عبر Peppol بنفسي؟
لا. تقوم شركة Qvalia بتشغيل نقطة الوصول (Access Point) وتولي عملية البحث عن المستلم ونقل البيانات عبر AS4 وتسليمها. ما عليك سوى إرسال المستند إلى واجهة برمجة التطبيقات (API). اقرأ كيف تحدد خدمات اكتشاف الخدمات SMP وSML نقطة النهاية المستلمة.
هل يمكنني إجراء التكامل دون كتابة كود برمجي؟
نعم. استخدم موصل نظام تخطيط موارد المؤسسة (ERP)، أو قم بتبادل ملفات XML أو CSV عبر بروتوكول SFTP.
ما هي مستندات Peppol التي يمكنني تبادلها؟
الفواتير، ومذكرات الائتمان، والطلبات، وردود الطلبات، واتفاقيات الطلبات، وتعديلات الطلبات وإلغاءاتها، وإشعارات الشحن، والكتالوجات، وردود مستوى الرسائل. يوضح الجدول الموجود تحت عنوان «مرجع Peppol للمطورين» المواصفات الخاصة بكل نوع من هذه الأنواع. وتعتمد أنواع المستندات التي يشملها إعدادك على الخدمة والتكامل المحددين. راجع «ما هي أنواع الرسائل في Peppol؟» للحصول على نظرة عامة.
كيف تحدد واجهة برمجة التطبيقات (API) نقطة النهاية الخاصة بالمستلم؟
تستخدم «كفاليا» عنوان « Peppol ID » الخاص بالمستلم لتحديد موقع «ناشر بيانات تعريف الخدمة» (SMP) الخاص بها من خلال «محدد موقع بيانات تعريف الخدمة» (SML). ويقوم «ناشر بيانات تعريف الخدمة» (SMP) بإرجاع إمكانيات المستند ونقطة النهاية الخاصة بالعملية والنقل اللازمة للتسليم. اقرأ «Peppol SMP وSML: كيف يعمل اكتشاف الخدمة».
ماذا يحدث عندما تفشل وثيقة ما في اجتياز عملية التحقق من صحة Peppol؟
يجب تصحيح أي مستند يحتوي على خطأ فادح في عملية التحقق من الصحة قبل إرساله. ويحدد رمز الخطأ مجموعة القواعد والجزء من المستند الذي يحتاج إلى فحص. انظر «كيفية عمل عملية التحقق من الصحة في Peppol » و«رموز قواعد التحقق من الصحة في Peppol».
كيف يمكنني التحقق من إمكانيات المستلم في مجال « Peppol ID » والمستندات؟
استخدم أداة البحث «Peppol ID » من Qvalia للعثور على المشاركين وإمكانيات المستندات المنشورة في الدليل. لمعرفة المزيد عن بنية المعرّفات وأنظمتها، راجع المقالة «ما هو نظام تعريف المستندات ( Peppol ID)؟» في قاعدة المعرفة.