> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fatorly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# نظرة عامة على واجهة برمجة التطبيقات

> ما هي واجهة 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` — ولا يمكن إنشاؤها أو تعديلها عبر الواجهة.
</Note>

## ما الذي يمكنك فعله

* إنشاء فواتير ضريبية وإشعارات خصم **كمسودّات** عبر `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`** كي لا تُنشئ إعادات المحاولة
نسخًا مكرّرة — راجع [معرّف عدم التكرار](/ar/developers/idempotency).

## خريطة الأدلة

<CardGroup cols={2}>
  <Card title="المصادقة" icon="key" href="/ar/developers/authentication">
    أنشئ مفتاح API وأرسله في ترويسة `X-Api-Key`.
  </Card>

  <Card title="البدء السريع" icon="rocket" href="/ar/developers/quickstart">
    انتقل من إنشاء المفتاح إلى أول فاتورة مُرسَلة من البداية إلى النهاية.
  </Card>

  <Card title="معرّف عدم التكرار" icon="arrows-rotate" href="/ar/developers/idempotency">
    اجعل كل عملية كتابة آمنة لإعادة المحاولة باستخدام `Idempotency-Key`.
  </Card>

  <Card title="الأخطاء" icon="triangle-exclamation" href="/ar/developers/errors">
    نموذج الأخطاء ورموز الحالة الشائعة التي ستواجهها.
  </Card>
</CardGroup>

للاطّلاع على الفهرس التفاعلي الكامل لنقاط النهاية مع طلبات "Try it" الحيّة، افتح
[مرجع الواجهة](/ar/developers/api-reference).

## ابدأ من هنا

1. [المصادقة](/ar/developers/authentication) — احصل على مفتاح.
2. [البدء السريع](/ar/developers/quickstart) — أنشئ فاتورة وأرسلها.