تكامل REST الخارجي (مفتاح API)

تكامل REST الخارجي هو «باب» مُدار يستطيع من خلاله نظام آخر (ERP، أو الواجهة الخلفية للموقع، أو 1C، أو طبقة تكامل وسيطة، أو تطبيقك الخاص) إنشاء المهام والفرص وتحديثها في LadVen OS عبر API قياسي بمفتاح وصول. وفي هذه الحالة لا يُمرَّر أي اسم مستخدم أو كلمة مرور، ولا يعمل أحد بصلاحيات المسؤول.

يُنفَّذ كل استدعاء باسم حساب خدمي منفصل (روبوت) بأدنى الصلاحيات اللازمة: فقط الإجراءات التي سمحت بها، وفقط داخل الأقسام والمشاريع والمسارات والمراحل التي حدّدتها. تمر كل الطلبات عبر قواعد البوابة المعتادة — الوصول، والتحقق، والأتمتة، والإشعارات — وتُسجَّل في سجل يمكن مراجعته لكل تكامل على حدة.

يُضاف الربط مرة واحدة في مركز عمليات التكامل (قسم CRM ← عمليات التكامل، المسار /crm/integrations).

متى تُستخدَم

يُحتاج تكامل REST عندما «يحدث شيء في نظام آخر — ويجب أن تظهر تلقائيًا مهمة أو فرصة في LadVen OS». السيناريوهات النموذجية:

• ينشئ ERP أو الموقع مهمة أو طلبًا عند ورود أمر شراء أو طلب أو تذكرة؛
• يبقي تطبيقك الخاص المهام والفرص متزامنة مع قاعدة بيانات خارجية؛
• يرفق نظام خارجي ملفات، أو يترك تعليقات، أو يسجّل الوقت، أو ينقل الفرصة عبر المراحل مع تقدّم العمل في الجهة الأخرى.

ما الفرق بين هذا وبين النماذج وخطافات الويب: نموذج الموقع وخطاف الويب هما استقبال أحادي الاتجاه للطلبات في CRM. أما تكامل REST فهو اتصال برمجي ثنائي الاتجاه: النظام الخارجي يقرأ (يحصل على المهام والفرص والتاريخ) ويكتب (ينشئ ويحدّث). والبوابة نفسها لا ترسل خطافات ويب صادرة عبر هذا الربط — فالطرف الخارجي هو من يتصل بالبوابة بنفسه.

كيفية الإعداد

يُنشَأ الربط عبر معالج خطوة بخطوة (CRM ← عمليات التكامل ← إضافة «تكامل REST الخارجي»). بالخطوات، وبمصطلحات العمل:

1. الاسم والتفعيل. أعطِ التكامل اسمًا واضحًا وقرّر هل تُفعّله فورًا. يمكنك تشغيل اختبار الاتصال مباشرة.
2. الحساب الخدمي. اختر روبوتًا موجودًا أو أنشئ روبوتًا جديدًا داخل المعالج مباشرة (اسم واسم دخول). هذا ليس موظفًا ولا مسؤولًا: يعمل التكامل باسمه. وإذا اخترت حسابًا بصلاحيات المسؤول، فسيحذّرك المعالج — وهذا مقصود، إذ تُمنَح عمليات التكامل أدنى الصلاحيات.
3. السيناريو ومستوى الصلاحيات. اختر مجموعة العمليات المناسبة للمهمة: «المهام و CRM»، أو «المهام فقط»، أو «CRM فقط». ثم مستوى الصلاحيات: قراءة فقط، أو إنشاء وتحرير، أو إدارة. تُطبَّق الصلاحيات على الحساب الخدمي قبل إصدار المفتاح.
4. الإجراءات المسموح بها. حدّد العمليات الدقيقة التي يُسمَح للتكامل بتنفيذها. والمبدأ هو أدنى ما يلزم: فعِّل فقط ما تحتاجه فعلًا. وكل ما لم يُحدَّد سيُرفَض قبل التنفيذ.
5. النطاق. قيّد التكامل بالأقسام والمشاريع والمسارات والمراحل اللازمة. هذا إطار فوق صلاحيات الحساب: حتى الإجراء المسموح به لن يعمل إلا داخل النطاق المحدّد.
6. الحقول والحدود. حدّد أي حقول المهام والفرص يستطيع التكامل تغييرها، وحد عدد الطلبات في الدقيقة والذروة المسموح بها، بالإضافة إلى قائمة عناوين IP البيضاء التي يُسمَح بالاستدعاء منها.
7. إنشاء المفتاح والتحقق. احفظ — وستعرض البوابة مفتاح الوصول مرة واحدة على شاشة النتيجة مع زر نسخ. ومن هنا أيضًا يمكنك تشغيل اختبار الاتصال.

بعد الإنشاء يصبح للربط سجل طلبات: أي العمليات اسْتُدعِيَت وبأي نتيجة. عرض التفاصيل فيه حاليًا سطح تشخيص تقني: لا تفتح أو تنسخ أو تنشر قيم request/response/error أو المعرّفات أو رموز السبب أو نص الخطأ. وللتحقيق، مرّر إلى مسؤول التكامل الوقت واسم الربط فقط عبر قناة آمنة معتمدة.

الأمان ومفتاح الوصول

يقوم تكامل REST على مبدأ أدنى الصلاحيات — وهذا مهم لصاحب العمل:

• يُعرَض المفتاح مرة واحدة. انسخه واحفظه فورًا في مدير أسرار. لن تعرض البوابة هذا المفتاح مرة أخرى ولا تخزّنه بصيغة مكشوفة. وإذا احتجت إلى تغيير المفتاح — فأعِد إصداره بالمرور من جديد عبر معالج هذا الربط.
• حساب خدمي منفصل. لا يعمل التكامل باسم شخص أو مسؤول؛ بل له نطاق مسؤوليته وصلاحياته الخاصة.
• حدود الوصول. الإجراءات المسموح بها، والنطاق (الأقسام، والمشاريع، والمسارات، والمراحل)، والقائمة البيضاء للحقول، وحد الطلبات، والقائمة البيضاء لعناوين IP تحدّد ما يمكن للتكامل فعله ومن أين.
• السجل. كل استدعاء مسجَّل — فيمكن تتبّع من غيّر ماذا عبر التكامل.

لا تعرض أبدًا في لقطات الشاشة ولا تنشر المفتاح الحقيقي، أو ترويسة التفويض، أو عناوين IP من القائمة البيضاء، أو اسم دخول الحساب الخدمي. واستخدم للتوضيح قيمًا غير حقيقية بوضوح.

الأخطاء الشائعة

• منح التكامل حساب مسؤول بدلًا من روبوت خدمي.
• تفعيل إجراءات أكثر من اللازم بدلًا من المجموعة الدنيا الضرورية.
• عدم نسخ المفتاح ذي الاستخدام الواحد عند الإنشاء.
• عدم ضبط القائمة البيضاء لعناوين IP وحد الطلبات.
• تحديد نطاق واسع أكثر من اللازم — البوابة كاملةً بدلًا من مسار واحد مطلوب.
• توقّع أن تبدأ البوابة بنفسها إرسال خطافات ويب صادرة: يعمل التكامل باستدعاءات واردة، والنظام الخارجي هو من يتصل بالبوابة.

كيفية التحقق من أنه يعمل

1. شغّل اختبار الاتصال في نهاية المعالج (أو فعّل تشغيل الاختبار مباشرة).
2. تأكد من أن بطاقة الربط تعرض حالة نشطة وسليمة.
3. راجع سجل الطلبات — يجب أن تكون فيه استدعاءات ناجحة.
4. تحقق من أن المهمة أو الفرصة التجريبية ظهرت بالمسؤول والمسار والمرحلة الصحيحة، وأن الأتمتة والإشعارات عملت كالمعتاد.

صفحات ذات صلة

• النماذج واستقبال الطلبات
• النماذج
• CRM: نظرة عامة
• المهام

قواعد إضافية للمعالج

يتطلب الحساب الخدمي الجديد الاسم واسم الدخول والبريد الإلكتروني؛ ويُنشأ كروبوت نشط بلا صلاحيات مسؤول، بينما تُنشأ كلمة المرور لعقد الخادم فقط ولا يستخدمها المعالج. إذا كانت الصلاحيات معدّة مسبقًا فاختر الصلاحيات معدّة: لا يغيّر المعالج ACL ويتحقق من الوصول أثناء اختبار الاتصال فقط. يؤدي اختيار مرحلة CRM إلى إضافة مسارها تلقائيًا إلى نطاق التكامل؛ والقائمة الفارغة لا توسّع الصلاحيات. يُقسّم كتالوج الطرق إلى مجموعات المهام وCRM، ويسجل السجل العمليات ونتائجها.