نظرة عامة على واجهة برمجة التطبيقات
ما هي واجهة Integration API من فاتورلي، وعنوانها الأساسي وإصدارها، وخريطة بأدلة المطوّرين ومرجع الواجهة.
تتيح لك واجهة Integration API من فاتورلي أن تُنشئ فواتيرك الإلكترونية وترسلها عبر شبكة Peppol برمجيًا من أنظمتك الخاصة — سواء كان نظام تخطيط موارد المؤسسات (ERP) أو منصة فوترة أو نظامًا خلفيًا مخصّصًا. وهي مكمّلة لتطبيق الويب: كل ما يمكنك فعله في محرّر الفواتير يمكنك فعله أيضًا عبر الواجهة، فتؤتمت العمليات عالية الحجم أو المكتبية مع استمرار استخدامك لواجهة المنصة للأعمال الفردية.
العنوان الأساسي
تعمل Fatorly في بيئتين مستقلتين، لكلٍّ منهما عنوانها الأساسي. طوّر واختبر على بيئة الاختبار (Sandbox) ببيانات اعتماد تجريبية، ثم بدّل المضيف إلى الإنتاج (Production) عند الإطلاق — دون أي تغيير آخر في تكاملك.
| البيئة | العنوان الأساسي |
|---|---|
| الإنتاج (Production) | https://integration.fatorly.com/v1 |
| الاختبار (Sandbox) | https://integration.sandbox.fatorly.com/v1 |
مفاتيح API مرتبطة بالبيئة: يعمل مفتاح الاختبار مع مضيف الاختبار فقط، ومفتاح الإنتاج مع الإنتاج فقط.
الإصدارات
الإصدار الحالي هو v1، ويُحمَل في مسار العنوان (/v1). يُبقي تثبيتك على إصدار
معيّن تكاملك مستقرًا مع تطوّر المنصة.
Note
المستندات التي تُصدرها (الفواتير الضريبية وإشعارات الخصم) تُنشأ وتُرسل عبر
الواجهة. أما المستندات التي تستقبلها عبر Peppol (فواتير وإشعارات خصم
المشتريات) فمتاحة للقراءة فقط: اسحبها من صندوق وارد نقطة الوصول عبر
POST /purchase-invoices/pull واقرأها عبر نقاط النهاية /purchase-invoices
و /purchase-credit-notes — ولا يمكن إنشاؤها أو تعديلها عبر الواجهة.
ما الذي يمكنك فعله
- إنشاء فواتير ضريبية وإشعارات خصم كمسودّات عبر
POST /invoicesوPOST /credit-notes، وتعديل مسودّة (أو مستند فشل إرساله) عبرPUT /invoices/{id}. - التحقّق قبل الإرسال عبر
POST /invoices/{id}/validate— نفس فحوص PINT-AE التي تُجريها شبكة Peppol، تُعاد كمشكلات قابلة للمعالجة دون حفظ أي شيء. - الإرسال عبر شبكة Peppol بواسطة
POST /invoices/{id}/submit، وتتبّع المستندات التي فشل تسليمها عبرGET /invoices/failed— يتضمّن كل عنصر سبب الفشل في الحقلsubmissionError. - استقبال مستندات المشتريات: يجلب
POST /purchase-invoices/pullكل ما ينتظر في صندوق وارد نقطة الوصول Peppol الخاصة بك، ثم اقرأ النتائج عبرGET /purchase-invoicesوGET /purchase-credit-notes— بتفاصيل كاملة تشمل الأسطر والإجماليات كي يستطيع نظام ERP لديك تسجيل المشتريات دون تحليل UBL. هذا الجزء للقراءة فقط: لا يمكن إنشاء المستندات المستلمة أو تعديلها عبر الواجهة. - إدارة البيانات المرجعية التي تُصدر الفواتير مقابلها — العملاء والأصناف.
- البحث عن المشاركين في شبكة Peppol.
كل عملية كتابة محميّة بترويسة Idempotency-Key كي لا تُنشئ إعادات المحاولة
نسخًا مكرّرة — راجع معرّف عدم التكرار.
خريطة الأدلة
أنشئ مفتاح API وأرسله في ترويسة X-Api-Key.
انتقل من إنشاء المفتاح إلى أول فاتورة مُرسَلة من البداية إلى النهاية.
اجعل كل عملية كتابة آمنة لإعادة المحاولة باستخدام Idempotency-Key.
نموذج الأخطاء ورموز الحالة الشائعة التي ستواجهها.
للاطّلاع على الفهرس التفاعلي الكامل لنقاط النهاية مع طلبات "Try it" الحيّة، افتح مرجع الواجهة.
ابدأ من هنا
- المصادقة — احصل على مفتاح.
- البدء السريع — أنشئ فاتورة وأرسلها.