وثائق واجهة برمجة التطبيقات (API)

تتيح واجهة برمجة التطبيقات (API) الخاصة بمنصة ProBase لفرق التطوير في المؤسسات بناء تكاملات برمجية متينة تربط أنظمتها الداخلية بمنصة إدارة العملاء والمبيعات والمحادثات لدينا. تعتمد الواجهة على نمط REST وتستخدم صيغة JSON في جميع الطلبات والاستجابات، مع دعم كامل للعمليات المتزامنة وغير المتزامنة عبر آلية الـ Webhooks. صُممت الواجهة لتكون متوقعة وثابتة وقابلة للتنبؤ بها، بما يمكّن مؤسستك من أتمتة سير العمل وتقليل الإدخال اليدوي.

تتوافق ممارساتنا في تأمين البيانات ومعالجتها مع متطلبات نظام حماية البيانات الشخصية (PDPL) في المملكة العربية السعودية وضوابط الهيئة السعودية للبيانات والذكاء الاصطناعي (SDAIA)، ونتبع ممارسات متوافقة مع معايير دولية مثل ISO 27001 في إدارة أمن المعلومات. تظل بياناتك ملكاً لمؤسستك، ونحن نعالجها بصفتنا معالجاً للبيانات وفق الاتفاقية المبرمة معك.

نظرة عامة على REST API

تتبع الواجهة المبادئ المعمارية لنمط REST، حيث يُمثَّل كل مورد (عميل، صفقة، عرض سعر، فاتورة، محادثة) عبر مسار مستقر، وتُستخدم أفعال HTTP القياسية للتعبير عن العمليات المطلوبة. عنوان الأساس لجميع الطلبات هو https://api.probasesolutions.com، وجميع الإصدارات مُرقَّمة في المسار لضمان التوافق الخلفي.

• GET لاسترجاع مورد أو قائمة موارد.
• POST لإنشاء مورد جديد.
• PUT أو PATCH لتحديث مورد قائم كلياً أو جزئياً.
• DELETE لحذف مورد أو إلغاء تنشيطه.

تُرسَل جميع الحمولات (payloads) بترميز UTF-8 مع ترويسة Content-Type: application/json، وتُعاد جميع الطوابع الزمنية بصيغة ISO 8601 بالتوقيت العالمي المنسق (UTC). جميع الاتصالات مشفّرة عبر TLS 1.2 أو أحدث، ولا تُقبل الطلبات عبر بروتوكول HTTP غير المشفّر.

الإصدار (Versioning)

يُحدَّد إصدار الواجهة ضمن المسار على هيئة /api/v1/. نلتزم بالحفاظ على استقرار كل إصدار منشور، ولن نُدخل تغييرات كاسرة للتوافق ضمن الإصدار نفسه. عند إصدار نسخة جديدة تتضمن تغييرات جوهرية، سنُتيح فترة تعايش بين الإصدارين ونُخطر فرق التطوير المسجّلة مسبقاً عبر البريد الإلكتروني وقنوات الإشعار قبل إيقاف أي إصدار.

• إضافة حقول جديدة اختيارية لا تُعدّ تغييراً كاسراً للتوافق.
• حذف حقل أو تغيير نوعه أو دلالته يستلزم إصداراً جديداً.
• نوصي بتصميم تكاملاتك بحيث تتجاهل الحقول غير المعروفة بأمان.

المصادقة عبر مفاتيح API

تعتمد المصادقة على مفاتيح API سرّية تُنشأ من لوحة تحكم المؤسسة. يُرفق المفتاح في كل طلب ضمن ترويسة التفويض على النحو التالي: Authorization: Bearer pb_live_xxxxxxxxxxxx. يجب التعامل مع المفتاح كبيانات اعتماد حساسة وعدم تضمينه في الشيفرة العامة أو تطبيقات الواجهة الأمامية.

• تُتاح مفاتيح منفصلة لبيئة الإنتاج (pb_live_) وبيئة الاختبار (pb_test_).
• يمكن لمسؤول المؤسسة إنشاء عدة مفاتيح وتحديد نطاق صلاحيات كل مفتاح (قراءة فقط أو قراءة وكتابة).
• يمكن إبطال أي مفتاح فوراً من اللوحة في حال الاشتباه بتسريبه، دون التأثير على بقية المفاتيح.
• نوصي بتدوير المفاتيح دورياً وتخزينها في خزائن أسرار آمنة.

يؤدي إرسال طلب بمفتاح غير صالح أو منتهٍ أو خارج نطاق الصلاحيات إلى استجابة برمز الحالة 401 أو 403. تُسجَّل جميع محاولات الوصول لأغراض التدقيق الأمني وفق سياساتنا للاحتفاظ بالسجلات.

نقطة النهاية: العملاء والعملاء المحتملون

تتيح هذه النقاط إدارة دورة حياة العميل المحتمل (Lead) وملفات العملاء. على سبيل المثال، لإنشاء عميل محتمل جديد يُرسَل طلب POST /api/v1/leads يحمل بيانات العميل بصيغة JSON.

• POST /api/v1/leads لإنشاء عميل محتمل جديد بحقول مثل الاسم ورقم الجوال والمصدر.
• GET /api/v1/leads لاسترجاع قائمة العملاء المحتملين مع دعم التصفية والترقيم.
• GET /api/v1/customers/{id} لاسترجاع ملف عميل محدد.
• PATCH /api/v1/customers/{id} لتحديث بيانات عميل قائم.

تُعاد البيانات بصيغة JSON تتضمن معرّفاً فريداً id وطابعاً زمنياً للإنشاء والتحديث. يُراعى عند تخزين أرقام الجوال السعودية اتباع الصيغة الدولية. نلتزم في معالجة البيانات الشخصية بمبادئ نظام PDPL، ولا تُجمع إلا البيانات اللازمة للغرض المعلن.

نقطة النهاية: الصفقات وعروض الأسعار

تمكّنك نقاط الصفقات من إدارة مسار المبيعات (Pipeline) ومراحله، فيما تتيح نقاط عروض الأسعار توليد عروض مسعّرة مرتبطة بالصفقة والعميل.

• POST /api/v1/deals لإنشاء صفقة جديدة وربطها بعميل ومرحلة في المسار.
• GET /api/v1/deals لاسترجاع الصفقات مع تصفية حسب المرحلة أو المالك أو التاريخ.
• PATCH /api/v1/deals/{id} لتحديث قيمة الصفقة أو نقلها بين المراحل.
• POST /api/v1/quotes لإنشاء عرض سعر ببنود ومبالغ وصلاحية زمنية.
• GET /api/v1/quotes/{id} لاسترجاع تفاصيل عرض سعر وحالته.

تتضمن استجابة عرض السعر إجمالي المبلغ قبل وبعد ضريبة القيمة المضافة، بما يتوافق مع متطلبات الهيئة العامة للزكاة والضريبة (ZATCA)، مع إظهار نسبة الضريبة المطبّقة بوضوح في الحمولة.

نقطة النهاية: الفواتير

تتكامل نقاط الفواتير مع منظومة الفوترة الإلكترونية، وتتيح إصدار الفواتير ومتابعة حالات السداد. على سبيل المثال POST /api/v1/invoices لإنشاء فاتورة من عرض سعر معتمد.

• POST /api/v1/invoices لإصدار فاتورة جديدة مرتبطة بصفقة أو عرض سعر.
• GET /api/v1/invoices لاسترجاع الفواتير مع تصفية حسب الحالة (مسوّدة، مرسلة، مدفوعة).
• GET /api/v1/invoices/{id} لاسترجاع تفاصيل فاتورة محددة.
• POST /api/v1/invoices/{id}/payments لتسجيل دفعة على فاتورة.

تُحتسب ضريبة القيمة المضافة وتُعرض حقول الفاتورة بما يتوافق مع متطلبات الفوترة الإلكترونية المعتمدة من ZATCA، بما في ذلك الرقم الضريبي وتفاصيل البائع والمشتري والطابع الزمني.

نقطة النهاية: المحادثات والرسائل

نظراً لكون المنصة قائمة على نهج WhatsApp-first، تتيح نقاط المحادثات قراءة وإرسال الرسائل عبر القنوات المتصلة، وربط كل محادثة بالعميل والصفقة المعنية.

• GET /api/v1/conversations لاسترجاع قائمة المحادثات النشطة.
• GET /api/v1/conversations/{id}/messages لاسترجاع رسائل محادثة بترتيب زمني.
• POST /api/v1/conversations/{id}/messages لإرسال رسالة نصية أو قالب معتمد.

يجب الالتزام بسياسات مزوّد الرسائل بشأن القوالب المعتمدة ونوافذ المراسلة، وتُعاد حالة تسليم كل رسالة ضمن الحمولة. تُعامَل محتويات المحادثات كبيانات حساسة وتخضع لضوابط الخصوصية ذاتها.

Webhooks للأحداث

تتيح آلية الـ Webhooks لمنصتك تلقّي إشعارات فورية عند وقوع أحداث محددة، بدلاً من الاستعلام الدوري. تُسجَّل عناوين الاستقبال (Endpoints) من لوحة التحكم، وتُرسَل الأحداث عبر طلب POST يحمل حمولة JSON تصف نوع الحدث وبياناته.

• message.received عند ورود رسالة جديدة في إحدى المحادثات.
• deal.created عند إنشاء صفقة جديدة في المسار.
• invoice.paid عند تسجيل سداد كامل لفاتورة.
• lead.created عند تسجيل عميل محتمل جديد عبر أي قناة.

يحمل كل طلب توقيعاً رقمياً في الترويسة (HMAC) للتحقق من أصالته، ونوصي بشدة بالتحقق من التوقيع قبل معالجة الحمولة. تتوقع منصتنا استجابة برمز 2xx خلال مهلة قصيرة، وفي حال الفشل نعيد المحاولة وفق سياسة تراجع أسّي (exponential backoff) لعدد محدد من المرات قبل تعليق الإشعار.

حدود المعدل (Rate Limits)

لحماية استقرار المنصة وضمان عدالة الاستخدام، تخضع الطلبات لحدود معدّل تُحتسب لكل مفتاح API. عند تجاوز الحد يُعاد رمز الحالة 429 Too Many Requests.

• تتضمن استجابة كل طلب ترويسات مثل X-RateLimit-Limit وX-RateLimit-Remaining.
• تُبيّن ترويسة Retry-After المدة المقترحة قبل إعادة المحاولة.
• نوصي بتطبيق منطق إعادة محاولة ذكي مع تراجع تدريجي بدلاً من الإلحاح المتكرر.
• يمكن مراجعة حدود أعلى للحالات ذات الحجم الكبير عبر التواصل مع فريق الحسابات المؤسسية.

ترقيم الصفحات (Pagination)

تُرقَّم نتائج القوائم الكبيرة لتجنّب تحميل حمولات ضخمة. تدعم الواجهة الترقيم القائم على المؤشر (cursor-based) لضمان الاتساق عند تغيّر البيانات أثناء التصفّح.

• يُستخدم معامل limit لتحديد عدد العناصر في الصفحة الواحدة، بحد أقصى محدد.
• يُستخدم معامل cursor للانتقال إلى الصفحة التالية.
• تتضمن الاستجابة كائن pagination يحمل مؤشر الصفحة التالية وما إذا كانت هناك نتائج إضافية.

رموز الأخطاء (Error Codes)

تعتمد الواجهة رموز حالة HTTP القياسية، وتُرفق مع كل خطأ حمولة JSON موحّدة تتضمن رمزاً دلالياً ورسالة واضحة ومعرّف الطلب لتسهيل التتبع والدعم.

• 400 طلب غير صالح أو حمولة JSON غير سليمة.
• 401 فشل المصادقة أو مفتاح مفقود.
• 403 المفتاح صالح لكنه خارج نطاق الصلاحيات المطلوبة.
• 404 المورد المطلوب غير موجود.
• 422 فشل التحقق من صحة الحقول المرسلة.
• 429 تجاوز حدود المعدل.
• 500 خطأ غير متوقع من جانب الخادم.

نوصي بتسجيل معرّف الطلب الوارد في حقل request_id ضمن الاستجابة، وإرفاقه عند مراسلة الدعم لتسريع التشخيص.

بيئة الاختبار (Sandbox)

نوفّر بيئة اختبار معزولة تماماً عن بيئة الإنتاج تتيح لفرق التطوير تجربة التكاملات دون التأثير على البيانات الحقيقية. تُستخدم مفاتيح بادئتها pb_test_ للوصول إليها.

• لا تُرسَل رسائل WhatsApp أو فواتير فعلية من بيئة الاختبار.
• تُحاكى أحداث الـ Webhooks لتمكينك من اختبار مستقبِلاتك.
• تُعاد بيانات وهمية واقعية للعملاء والصفقات والفواتير لأغراض التطوير.
• نوصي بإكمال الاختبار بالكامل في هذه البيئة قبل الانتقال إلى الإنتاج.

الأمان والامتثال

نلتزم بحماية بياناتك عبر التشفير أثناء النقل والتخزين، والفصل المنطقي بين بيانات المؤسسات، وضوابط وصول صارمة. نتبع ممارسات متوافقة مع معايير مثل ISO 27001، ونلتزم بأحكام نظام حماية البيانات الشخصية (PDPL) وضوابط الهيئة السعودية للبيانات والذكاء الاصطناعي (SDAIA) في معالجة البيانات داخل المملكة.

• تُسجَّل عمليات الوصول عبر الواجهة لأغراض التدقيق الأمني.
• تخضع مفاتيح الإنتاج لضوابط صلاحيات قابلة للتخصيص.
• نوصي بتقييد عناوين IP المسموح لها بالوصول حيثما أمكن.

التوافر والوصول إلى الواجهة

ملاحظة مهمة: يُتاح الوصول إلى واجهة برمجة التطبيقات وآلية الـ Webhooks ضمن الباقات المؤسسية فقط. إذا كانت مؤسستك على باقة أدنى وترغب في تفعيل الوصول البرمجي، يُرجى التواصل مع فريق الحسابات لترقية الاشتراك وتفعيل المفاتيح.

• يُفعَّل الوصول من لوحة تحكم المؤسسة بعد ترقية الباقة.
• تتوفر حدود معدّل ونطاقات استخدام أعلى للباقات المؤسسية الموسّعة.
• يحصل عملاء الباقات المؤسسية على دعم فني مخصص لمسائل التكامل.

الدعم والتواصل

لطلب تفعيل الوصول البرمجي، أو الإبلاغ عن مشكلة في الواجهة، أو طلب رفع حدود المعدل، أو الإبلاغ عن ثغرة أمنية، يُرجى التواصل عبر البريد الإلكتروني info@probasesolutions.com. يسعد فريق التكامل لدينا بمساعدة مطوّري مؤسستك في كل مرحلة من مراحل الربط مع منصة ProBase.