عنوان URL الأساسي
https://freebillgen.com/api/v1المصادقة
يستخدم كل طلب رمز حامل (Bearer token). أنشئ رمزًا من الإعدادات → مفاتيح واجهة برمجة التطبيقات (API)، وامنحه نطاقات القراءة/الكتابة المطلوبة لكل مورد، مع إمكانية تعيين تاريخ انتهاء اختياري، ثم أرسله مع كل طلب:
Authorization: Bearer <your-api-key>تتم مصادقة الطلبات استنادًا إلى الحساب الذي أنشأ المفتاح والتحقق منها وفقًا للنطاقات المحددة له. حافظ على سرية الرمز وقم بإلغائه إذا تم كشفه أو لم تعد هناك حاجة إليه.
ما يمكنك فعله
- قراءة الفواتير والعملاء والشركات والمدفوعات والجداول الزمنية المتكررة
- إنشاؤها وتحديثها (واجهة برمجة التطبيقات للكتابة - Pro)
- استخراج تقارير ضريبة القيمة المضافة وتقارير الأجل كملفات JSON
- قراءة قائمة «الإجراءات التالية» المحددة نفسها التي تستخدمها لوحة المعلومات
- قراءة ملفات الفواتير الإلكترونية للموردين التي قمت بتحميلها يدويًّا إلى صندوق الوارد (وليس نقطة نهاية استقبال Peppol/البريد الإلكتروني)
- تنزيل خرائط OASIS UBL و UN/CEFACT CII العامة للمراجعة (غير معتمدة من قبل الملف التعريفي)
- تسجيل نقاط نهاية الويب هوك لأحداث الفواتير والدفع (Pro)
- مفتاح التماثل في عمليات الكتابة المدعومة - يؤدي تغيير بيانات الطلب تحت نفس المفتاح إلى إرجاع الرمز 409
- ترقيم الصفحات باستخدام المؤشر عبر links.next، قابل للتعديل باستخدام per_page (بحد أقصى 100)
- اسمح لوكلاء الذكاء الاصطناعي بقراءة أي فاتورة تمت مشاركتها - schema.org/Invoice JSON-LD، بالإضافة إلى Accept: application/json أو text/markdown على كل رابط مشاركة موقّع
- خادم MCP بدون مصادقة وقراءة فقط على https://freebillgen.com/api/mcp (get_invoice، verify_invoice) لوكلاء الذكاء الاصطناعي
القواعد
- القدرة على التكرار
- في استدعاءات الإنشاء والإجراءات المدعومة، أرسل مفتاح تكرار (Idempotency-Key) فريدًا. إعادة محاولة طلب ببيانات متطابقة تؤدي إلى تكرار النجاح الأصلي؛ أما طلب البيانات المعدلة فيُرجع الرمز 409.
- ترقيم الصفحات
- قوائم الموارد الدائمة مقسمة إلى صفحات حسب المؤشر - اتبع links.next (أو مرر ?cursor=...)، واضبط ?per_page= (بحد أقصى 100). يُبلغ موجز الإجراءات المحدود عن حده وحالته المقتطعة.
- المال
- المبالغ النقدية هي سلاسل JSON دقيقة منسقة وفقًا لمقياس ISO 4217 للعملة، مثل "121.00" لليورو أو "500" لليين الياباني. يمكن أن تحتفظ أسعار الوحدات بدقة إدخال إضافية.
- المعرّفات
- يُشار إلى كل مورد برقم تعريف غير شفاف، وليس برقم تسلسلي أبدًا.
مثال: عرض فواتيرك
curl https://freebillgen.com/api/v1/invoices \
-H "Authorization: Bearer $FREEBILLGEN_API_KEY"افتح مرجع واجهة برمجة التطبيقات التفاعلي الكامل →
أسئلة حول واجهة برمجة تطبيقات الفواتير
هل واجهة برمجة تطبيقات الفواتير مجانية؟
نعم - واجهة برمجة التطبيقات (API) للقراءة مضمنة في المستوى المجاني دون أي تكلفة. أما واجهة برمجة التطبيقات (API) للكتابة وwebhooks الصادرة فهي مضمنة في باقة «49 € Lifetime Pro» شاملة الضرائب: دفعة واحدة، بدون رسوم شهرية أو تجديد سنوي.
كيف أقوم بالمصادقة؟
قم بإنشاء رمز Bearer ضمن الإعدادات -> مفاتيح API، وقم بتعيين نطاقات القراءة/الكتابة لكل مورد، وأرسله كرأس «Authorization: Bearer» في كل طلب. تقتصر نطاقات المفاتيح على حسابك الخاص ويمكن إلغاؤها أو انتهاء صلاحيتها.
هل يمكنني إنشاء فواتير برمجياً؟
نعم، عبر واجهة برمجة التطبيقات (API) للكتابة، والتي تعد جزءًا من الإضافة Pro. فهي تُصدر نفس الفواتير الاحترافية التي يصدرها التطبيق على الويب، مع ترقيم تسلسلي ومعالجة ضريبة القيمة المضافة القابلة للتكوين والتي تُطبق من جانب الخادم. لا تضمن واجهة برمجة التطبيقات (API) الامتثال للقوانين المحلية.
كيف أتجنب إنشاء فواتير مكررة عند إعادة المحاولة؟
أرسل مفتاح تكرار فريد (Idempotency-Key) عند استدعاء الإنشاء. إعادة محاولة طلب البيانات المطابقة باستخدام هذا المفتاح تُرجع النتيجة الأصلية. إعادة استخدامه مع بيانات طلب متغيرة تُرجع الرمز 409 بدلاً من إعادة إصدار فاتورة مختلفة دون إشعار.
هل يمكنني قراءة الفواتير التي تلقيتها؟
نعم، مجانًا. تعرض GET /api/v1/inbox قائمة بملفات المورّدين بتنسيق UBL/CII المدعومة التي رفعتها يدويًّا وقام FreeBillGen بتحليلها، مع الاحتفاظ بالملف الأصلي لأغراض التدقيق؛ وتُرجع GET /api/v1/inbox/{id} ملفًا واحدًا. لا يُعد التعرف على بنية الصيغة (Syntax) تحققًا من صحة ملف المواصفات (Profile validation)، ولا تجعل نقاط النهاية هذه من FreeBillGen نقطة نهاية لاستقبال Peppol أو شبكة حكومية أو بريد إلكتروني.
هل يمكن لوكيل الذكاء الاصطناعي قراءة فاتورة بدون حساب؟
نعم. كل فاتورة تشاركها عبر رابطها العام الموقّع يمكن للوكيل قراءتها عبر نفس عنوان URL: حيث تتضمن الصفحة كود schema.org/Invoice بتنسيق JSON-LD، ويؤدي إرسال Accept: application/json إلى إرجاع فاتورة مهيكلة (الأطراف، بنود الفاتورة، الإجماليات، الرصيد المستحق، خيارات الدفع)، بينما يُرجع Accept: text/markdown عرضًا نقيًّا يستهلك عددًا قليلاً من الرموز (Tokens). يوجد أيضًا خادم Model Context Protocol (MCP) للقراءة فقط وبدون مصادقة على https://freebillgen.com/api/mcp مزود بأداتي get_invoice وverify_invoice. توقيع الرابط هو رمز الوصول المميز. تعامل مع عنوان URL الكامل على أنه سرّ لأن أي شخص يحصل عليه يمكنه فتح الفاتورة.