المستندات
الفواتير ومذكرات الائتمان
Plus الفوترة الذاتية والردود على الفواتير
التنسيقات
JSON أو UBL XML
يعتمد على UBL 2.1، مستند واحد لكل طلب
الأحداث
الويب هوكس الموقعة
تم الاستلام، تم التسليم، تأخر التسليم، وفشل التسليم
التوافر
99.8% شهريًّا
تعاقدي، مع أرصدة خدمة
إرسال فاتورة مع طلب واحد
أرسل الفاتورة بتنسيق JSON أو UBL XML إلى نقطة النهاية الصادرة لحسابك. تقوم Qvalia بالتحقق من صحتها، والبحث عن المستلم على Peppol، ثم تسليمها. وتتبع مذكرات الائتمان ووثائق الفوترة الذاتية وردود الفواتير نفس النمط.
- بيئة الاختبار على api-test.qvalia.com، والبيئة الإنتاجية على api.qvalia.com
- مفتاح API في رأس «Authorization»، أو رمز مميز قصير الأمد (JWT)
- رأس «مفتاح الإيدمبوتنسي» يجعل عمليات إعادة المحاولة آمنة
● ● ●
طلب "Sandbox": إرسال فاتورة
curl -X POST \
"https://api-test.qvalia.com/transaction/$ACCOUNT_REG_NO/invoices/outgoing" \
-H "Authorization: $QVALIA_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d @invoice.jsonكيف تمر الفاتورة عبر واجهة برمجة التطبيقات (API)
يعمل نظامكم من خلال واجهة برمجة تطبيقات واحدة. وتقوم شركة Qvalia بتشغيل نقطة وصول Peppol التي تدعم هذا النظام.
1. إرسال
يرجى نشر مستند واحد لكل طلب. إذا كانت البيانات غير صالحة، أو إذا لم يكن المستلم مسجلاً لنوع المستند هذا ولم يتم تكوين أي قناة توصيل أخرى، فإن واجهة برمجة التطبيقات (API) ترد برمز الخطأ الثابت 422، قبل إرسال أي شيء.
2. التحقق من الصحة والتسليم
يقوم Qvalia بمقارنة المستند بقواعد Peppol المعمول بها، ويحدد نقطة الوصول الخاصة بالمستلم، ثم يقوم بتسليم المستند عبر AS4.
3. متابعة الحالة
تقوم «Webhooks» بالإبلاغ عن عمليات التسليم والمحاولات المتكررة الجارية وحالات الفشل. وتُرجع نقطة نهاية الحالة أحدث حالة لكل مستند دون حمولة المستند.
4. الاستلام
تنتظر الفواتير الواردة والردود على نقاط النهاية الواردة. تُرجع نقطة النهاية الخاصة بالقراءة المستندات غير المقروءة وتضع علامة «مقروءة» عليها، بحيث لا تُرجع المكالمة التالية سوى المستندات الجديدة.
مستندات الفواتير ونقاط النهاية
كل مسار يبدأ بـ /transaction/{accountRegNo}، رقم تسجيل حسابك. ويحتوي كل نوع من أنواع المستندات على نقاط نهاية للمرسل والمستلم، ونقطة نهاية للقراءة خاصة بالمستندات غير المقروءة، ونقطة نهاية للحالة.
| وثيقة | نقطة النهاية | مواصفات Peppol |
| الفاتورة | /invoices | Peppol BIS Billing .0 |
| مذكرة ائتمان | /creditnotes | Peppol BIS Billing .0 |
| فاتورة ذاتية الإصدار | /selfbillinginvoices | نظام الفوترة الذاتية Peppol BIS |
| مذكرة ائتمان ذاتية الفوترة | /selfbillingcreditnotes | نظام الفوترة الذاتية Peppol BIS |
| الرد على الفاتورة | /invoiceresponses | Peppol BIS Invoice Response |
| الاستجابة على مستوى الرسالة | /messagelevelresponses | Peppol BIS Message Level Response |
يعتمد نوع المستندات التي يستخدمها حسابك على الخدمة والخطة. توجد مخططات الطلبات والاستجابات في مراجع واجهة برمجة تطبيقات الفواتير (Invoice API ) وواجهة برمجة تطبيقات مذكرات الائتمان (Credit Note API). للاطلاع على جميع واجهات برمجة التطبيقات الخاصة بـ Qvalia، راجع واجهات برمجة تطبيقات Peppol وأدوات المطورين.
تأكد من هوية المستلم قبل الإرسال
قم بالبحث عن «معرف المشارك» ( Peppol ID ) قبل إرسال الفاتورة. توضح النتيجة ما إذا كان المشارك مسجلاً في Peppol وأنواع المستندات التي يمكنه استلامها، بحيث يتمكن نظامك من الإشارة إلى وجود معرف مفقود أو خاطئ قبل أن ترفض الشبكة الفاتورة.
- قم بتحديد الفحص ليقتصر على نوع واحد من المستندات باستخدام
docTypeRoot، على سبيل المثالInvoiceأوCreditNote - يُعد « Peppol ID » هو المخطط والمعرّف، على سبيل المثال
0007:1234567890 - نفس عناوين URL الأساسية ونفس طريقة المصادقة المستخدمة في واجهة برمجة تطبيقات المعاملات (Transaction API)
● ● ●
طلب "Sandbox": البحث عن مستلم
curl \
"https://api-test.qvalia.com/account/$ACCOUNT_REG_NO/action/lookup/peppol/0007:1234567890?docTypeRoot=Invoice" \
-H "Authorization: $QVALIA_API_KEY"مصمم خصيصًا لتكامل عمليات الإنتاج
التفاصيل التي تحدد ما إذا كان التكامل سيصمد عند التعامل مع أحجام كبيرة، وهي موثقة بالكامل في دليل مرجعي واجهة برمجة التطبيقات (API).
- إعادة المحاولة الآمنة
أرسل مفتاحًا متجانسًا (Idempotency-Key)، وسيؤدي تكرار الطلب إلى إرجاع الرد الأصلي بدلاً من إنشاء فاتورة ثانية. - الويب هوكس الموقعة
يحمل كل حدث معرّفًا خاصًا به، وبمجرد تعيين سر التوقيع، يصبح هناك توقيع يمكنك التحقق منه. - إعادة تشغيل الحدث لمدة 30 يومًا
يمكنك استرجاع أي حدث تم تسليمه مرة أخرى باستخدام معرّفه، على سبيل المثال بعد انقطاع الخدمة من جانبك. - الحالة بدون الحمولة
قم بالتسوية على مستوى الحجم باستخدام سجلات الحالة الموجزة، التي يتم تصفيتها حسب التاريخ أو معرّف المستند أو وقت التحديث. - حدود معدل الطلبات
يتم احتساب الحدود لكل حساب، وتوضح لك الاستجابة 429 المدة التي يجب عليك الانتظار فيها. - المرفقات
أضف ملفات PDF والصور داخل الرسالة. يجب ألا يتجاوز حجم الطلب بأكمله، بما في ذلك المرفقات والمشفرة بـ Base64، الحد الأقصى المسموح به من Peppol وهو 100 ميغابايت.
فاتورة واحدة، بالشكل الذي يحتاجه كل مستلم
أرسل الفاتورة مرة واحدة. تقوم Qvalia بالتحقق من صحتها، والبحث عن المستلم، وتسليمها عبر شبكة Peppol بتنسيق Peppol BIS Billing 3.0 أو Peppol PINT. وفي حالة عدم وجود المستلم على شبكة Peppol، يمكن لـ Qvalia التسليم عبر EDI، أو ملف PDF عبر البريد الإلكتروني، أو النسخة المطبوعة، أو الخدمات المصرفية عبر الإنترنت للعملاء الأفراد (B2C) في أسواق محددة. وتعد هذه قنوات تسليم إضافية، وليست من مواصفات Peppol. اطلع على تنسيقات الرسائل التجارية التي تدعمها Qvalia.
إذا كان نظامك غير قادر على إصدار فواتير Peppol BIS، فقم بتحميل الفاتورة بالصيغة التي يصدرها النظام بالفعل: Svefaktura 1.0، أو EDIFACT INVOIC، أو cXML، أو Finvoice 3.0، أو XRechnung، أو CII، أو ملف XML في ZUGFeRD وFactur-X. تقوم Qvalia بتحويلها إلى صيغة Peppol BIS Billing 3.0، والتحقق من صحتها، ثم إرسالها. انظر: إرسال الفواتير بالصيغة الحالية.
اختر نقطة انطلاقك
منصات البرمجيات
Peppol المدمج
قدم خدمة الفواتير الإلكترونية لعملائك. تقوم واجهة برمجة التطبيقات (API) الخاصة بالشركاء بإنشاء حساباتهم ومعرّفات Peppol الخاصة بهم، بينما تتولى واجهة برمجة التطبيقات (API) الخاصة بالفواتير نقل مستنداتهم.
فرق تخطيط موارد المؤسسات (ERP) والمالية
Peppol Access Point
قم بربط نظام تخطيط موارد المؤسسة (ERP) أو نظامك المالي بـ Peppol عبر واجهة برمجة التطبيقات (API) أو بروتوكول نقل الملفات الآمن (SFTP) أو موصل جاهز.
المطورون
دليل البدء السريع
انطلق من مفتاح واجهة برمجة التطبيقات (API) إلى أول فاتورة في بيئة الاختبار، خطوة بخطوة، مع أمثلة على الطلبات.
الأسئلة الشائعة حول واجهة برمجة تطبيقات الفواتير
ما هي واجهة برمجة التطبيقات (API) الخاصة بالفواتير الإلكترونية؟
تتيح واجهة برمجة التطبيقات (API) الخاصة بالفواتير الإلكترونية لبرنامجك إرسال واستلام فواتير إلكترونية منظمة دون الحاجة إلى إنشاء اتصال الشبكة بنفسه. باستخدام واجهة برمجة التطبيقات الخاصة بالفواتير من Qvalia، يقوم نظامك بإرسال الفواتير بتنسيق JSON أو UBL XML، وتقوم Qvalia بالتحقق من صحتها وتسليمها عبر شبكة Peppol.
ما هي مستندات الفواتير التي يمكنني إرسالها واستلامها؟
الفواتير، ومذكرات الائتمان، والفواتير ومذكرات الائتمان الذاتية، وردود الفواتير، ولكل منها نقاط نهاية صادرة وواردة. وتعتمد أنواع المستندات التي يستخدمها حسابك على الخدمة والخطة.
هل أحتاج إلى معرفة نظام Peppol BIS لاستخدام واجهة برمجة التطبيقات (API)؟
تتوافق مستنداتك مع معيار Peppol BIS Billing 3.0، بتنسيق JSON أو XML القائم على UBL 2.1. تعرض البيانات النموذجية الموجودة على api.qvalia.io فاتورة كاملة، وتشير أخطاء التحقق إلى القاعدة التي يجب تصحيحها. انظر «كيفية عمل التحقق في Peppol».
هل توجد منطقة تجارب؟
نعم. تستخدم بيئة الاختبار (sandbox) على api-test.qvalia.com مفتاح API خاص بها، لذا يمكنك إجراء الاختبارات على أنظمتك الخاصة دون التأثير على العملاء الفعليين. ويشمل خطة Connect Medium إمكانية الوصول إلى واجهة برمجة التطبيقات (API) وبيئة الاختبار (sandbox).
كيف يمكنني تجنب إرسال نفس الفاتورة مرتين؟
أرسل رأس «Idempotency-Key» مع كل عملية إرسال. إذا كررت الطلب، على سبيل المثال بعد انتهاء المهلة، فإن واجهة برمجة التطبيقات (API) تُرجع الاستجابة الأصلية بدلاً من إنشاء مستند ثانٍ. أما في حالة إرسال طلب جديد يحمل نفس معرّف المستند والمستلم، فسيتم إرجاع رمز الخطأ 409 (تعارض) ما لم تختر الكتابة فوق المستند الموجود.
كيف أعرف أن الفاتورة قد تم تسليمها؟
اشترك في خدمات «webhooks» لتلقي أحداث التسليم والأخطاء، أو اطلع على نقطة نهاية الحالة. لا يتم إعادة إرسال أي خدمة «webhook» تفشل نقطة النهاية الخاصة بك في قبولها، لذا احرص على إجراء فحص دوري للحالة كإجراء احترازي. يمكن استرداد أي حدث تم تسليمه مرة أخرى خلال 30 يومًا.
كيف يمكنني استلام الفواتير الواردة؟
اشترك في ويبهوك المستند الجديد، ثم احصل على الفاتورة من نقطة النهاية الواردة. تعرض نقطة النهاية الخاصة بالقراءة الفواتير غير المقروءة وتضع علامة «مقروءة» عليها.
ما هي تكلفة واجهة برمجة تطبيقات الفواتير (API)؟
يتضمن باقة «Connect» Medium إمكانية الوصول إلى واجهة برمجة التطبيقات (API). وتعتمد أسعار الشركاء والمؤسسات على حجم الاستخدام ونموذج التسليم. انظر «الباقات والأسعار».
