Solavel المستندات
العربية

التكامل

آخر تحديث

تربط علامة التبويب التكاملات في المشروع ذلك المشروع بأنظمة أخرى:

  • ترسل Webhooks الصادرة أحداث المشروع (إنشاء مهمة، بدء دورة عمل، إنشاء مستند…) إلى عنوان HTTPS تملكه، موقّعةً ليتمكن المستقبِل من الوثوق بها.
  • تتيح رموز Webhook الواردة لنظام خارجي (أداة نماذج، GitHub، برنامج نصي) إنشاء مهام أو تعليقات في المشروع.
  • تمنح رموز واجهة API العامة نظامًا آخر وصولًا محدد النطاق، للقراءة أو الكتابة، إلى مهام المشروع وأوقاته عبر واجهة SolaProjects API.
  • تعرض جاهزية التكاملات المدمجة الاتصالات الجاهزة (Slack وMicrosoft Teams وGitHub وGitLab وGoogle Calendar وGoogle Drive وOneDrive وZapier / IFTTT) وما إذا كان كل منها قابلًا للربط.

استخدمها عندما يحتاج المشروع إلى التواصل مع أداة أخرى، مثل نشر تحديثات المهام على لوحة تحكم لدى العميل، أو تحويل استفسارات الموقع الإلكتروني إلى مهام. يتولى مديرو المشاريع والمسؤولون إعدادها، وعادةً ما يُنجز ذلك مرة واحدة لكل مشروع بالتنسيق مع مسؤول تقنية المعلومات لديك.

هناك صفحتان باسم التكاملات. تتناول هذه الصفحة علامة تبويب المشروع. أما عنصر التكاملات في قسم مساحة العمل من الشريط الجانبي (/projects/settings/integrations) فهو ربط SolaCount الخاص بالمؤسسة؛ راجع ربط المؤسسة بـ SolaCount أدناه والميزانية والمالية.

#أين يمكن العثور عليه

الشريط الجانبي قسم المشروع ← التكاملات (بين الأتمتة والذكاء الاصطناعي)
URL /projects/{project}/integrations
لوحة الأوامر التكاملات · {project name} ضمن المشروع الحالي

من يراه:

  • الخطة: التكاملات ميزة في خطة Premium (وفي Enterprise أيضًا). وتُخفى علامة التبويب في الخطط الأدنى. وإذا انتهى الاشتراك المدفوع، تختفي علامة التبويب ولا تعود Webhooks متاحة حتى التجديد.
  • الدور: لا يستطيع فتح علامة التبويب إلا من يملك صلاحية تعديل المشروع (راجع الصلاحيات). ويرى الآخرون الرسالة «تعذّر تحميل التكاملات.» مع زر إعادة المحاولة.

#جولة في الشاشة

#بطاقة الترويسة

التكاملات — Webhooks الصادرة، والرموز الواردة، وسجل الإرسال.

بلاط معنى
الصادرة عدد Webhooks الصادرة النشطة.
الرموز الواردة الرموز الواردة النشطة التي لم تُبطَل.
عمليات الإرسال الأخيرة محاولات الإرسال المدرجة في عمليات الإرسال الأخيرة.
عمليات الإرسال الفاشلة المحاولات الفاشلة منها (تظهر بالأحمر إذا كانت أكثر من صفر).

#بطاقة Webhooks الصادرة

أرسل أحداث المشروع عبر POST إلى عنوان HTTPS خارجي، موقّعةً بـ HMAC-SHA256. زر Webhook جديد أعلى اليسار.

تعرض بطاقة كل Webhook الاسم ورابط العنوان المستقبِل وشارة الحالة (نشط أو معطّل أو مؤرشف) وشارة لكل حدث مشترَك فيه، و{n} عملية إرسال · {n} فاشلة. إجراءات الصف (لا تظهر في Webhooks المؤرشفة): تعديل واختبار وتجديد المفتاح السري وأرشفة.

الحالة الفارغة: لا توجد Webhooks صادرة — أنشئ واحدًا لإرسال الأحداث إلى نظام خارجي.

#بطاقة رموز Webhook الواردة

اسمح للأنظمة الخارجية بإنشاء مهام أو تعليقات بإرسال طلب POST مع رمز سري. زر رمز جديد أعلى اليسار.

تعرض بطاقة كل رمز: الاسم، والمزوّد (مخصص أو GitHub) · آخر استخدام {date} أو لم يُستخدم بعد، وشارة نشط أو غير نشط أو مُبطَل. الإجراءات (لا تظهر في الرموز المُبطَلة): تجديد وإبطال.

الحالة الفارغة: لا توجد رموز واردة — أنشئ رمزًا لاستقبال طلبات Webhook الواردة.

#بطاقة واجهة API العامة

أنشئ رموز Bearer محددة الصلاحيات لنقاط الوصول الموثّقة الخاصة بالمشاريع والمهام وقيود الوقت. الأزرار: التوثيق (يفتح مرجع OpenAPI في علامة تبويب جديدة) ورمز جديد.

تعرض بطاقة كل رمز: الاسم، وآخر استخدام {date} / لم يُستخدم بعد، وشارة الحالة، وشارة لكل صلاحية. الإجراءات: تجديد وإبطال.

الحالة الفارغة: لا توجد رموز API — أنشئ رمزًا لواجهة API العامة.

#بطاقة عمليات الإرسال الأخيرة

محاولات الإرسال الصادرة ونتائجها. مع شارة تعرض العدد.

العمود معنى
متى تاريخ الإرسال.
Webhook اسم Webhook، أو Webhook مؤرشف.
حدث نوع الحدث، مثل task.status_changed.
الحالة تم الإرسال (أخضر)، قيد الانتظار (كهرماني، بانتظار الإرسال أو إعادة المحاولة)، فشل (أحمر)، تم التخطي.
المحاولات عدد المرات التي حاول فيها SolaProjects الإرسال.
الاستجابة رمز حالة HTTP الذي أعاده عنوانك المستقبِل، أو خطأ إذا لم تصل أي استجابة، أو —.
(زر) زر إعادة المحاولة يظهر في أي عملية إرسال لم تنجح.

الحالة الفارغة: لا توجد عمليات إرسال بعد — تظهر محاولات الإرسال هنا عند وقوع حدث أو إرسال اختبار.

#بطاقة جاهزية التكاملات المدمجة

حالة الاتصال ومتطلبات الإعداد للتكاملات الخاصة بكل مزوّد. مربع واحد لكل مزوّد:

المزوّد ماذا يفعل
Slack إرسال إشعارات المشروع إلى Slack واستقبال أوامر المهام من Slack.
Microsoft Teams إرسال إشعارات المشروع إلى قنوات Teams ودعم إجراءات Teams.
GitHub ربط أحداث المستودع والتذاكر وطلبات السحب والإيداعات بمهام المشروع.
GitLab ربط طلبات الدمج والتذاكر وأحداث خطوط التنفيذ في GitLab بمهام المشروع.
Google Calendar مزامنة المراحل الرئيسية للمشروع وتواريخ المهام مع Google Calendar.
Google Drive إرفاق مستندات المشروع أو مزامنتها مع مجلدات Google Drive.
OneDrive إرفاق مستندات المشروع أو مزامنتها مع مجلدات OneDrive.
Zapier / IFTTT إتاحة مشغّلات SolaProjects وإجراءاته لمنصات الأتمتة بلا برمجة (no-code).

يعرض كل مربع الحالة (متاح أو قيد الانتظار أو نشط أو فشل)، والإمكانية، وإحدى العبارتين تم اكتشاف إعداد فعلي للمزوّد. أو المحاكي المحلي متاح؛ وبيانات اعتماد الإنتاج من إعدادات التفعيل. (أي أن المزوّد لم يُفعَّل بعد لمؤسستك). وقد يعرض أيضًا متوقف بسبب إعداد ناقص: … أو ملاحظات التفعيل: … أو بانتظار استدعاء OAuth. أو آخر خطأ: …، وآخر رسالة أو آخر حدث مستلَم.

#الأحداث التي يمكنك إرسالها

حدّد حدثًا واحدًا أو أكثر في نموذج Webhook:

حدث يُرسَل عند
task.created إنشاء مهمة (بما في ذلك عبر Webhook وارد).
task.updated تعديل مهمة.
task.status_changed تغيّر حالة مهمة.
task.completed تحديد مهمة كمكتملة.
task.blocked تحديد مهمة كمتوقفة.
comment.created إضافة تعليق على مهمة.
doc.created يُنشأ مستند في المشروع.
time_entry.created تسجيل وقت.
milestone.completed اكتمال مرحلة رئيسية.
sprint.started / sprint.completed بدء دورة عمل أو اكتمالها.
share_link.created إنشاء رابط مشاركة للضيوف.
automation.run_failed / automation.rule_failed فشل تشغيل قاعدة أتمتة.
ai.suggestion_applied تطبيق اقتراح من الذكاء الاصطناعي.

كل طلب هو POST بصيغة JSON مع الترويسات X-SolaProjects-Event (نوع الحدث) وX-SolaProjects-Delivery (معرّف الإرسال) وX-SolaProjects-Signature (توقيع HMAC-SHA256 للمحتوى الخام باستخدام مفتاح التوقيع السري لديك)، وUser-Agent: SolaProjects-Webhooks/1.0. تحقّق من التوقيع قبل الوثوق بأي طلب.

إعادة المحاولة. يُعاد الإرسال الفاشل تلقائيًا بعد نحو 1 و5 و15 و60 دقيقة، وبعد المحاولة الخامسة تبقى حالته فشل. استخدم إعادة المحاولة لإعادة الإرسال يدويًا.

#المهام

#إنشاء Webhook صادر

  1. افتح المشروع ← التكاملات ← Webhook جديد.

  2. املأ نموذج Webhook صادر جديد:

    الميدان مطلوب القواعد / القيم الافتراضية ملاحظات
    الاسم نعم حتى 160 حرفًا. مثل لوحة تحكم العميل.
    رابط العنوان المستقبِل (HTTPS) نعم رابط URL صالح بحد أقصى 2,048 حرفًا، وعنوان HTTPS عام. النص الإرشادي https://example.com/hooks/solaprojects. تُرفض العناوين المحلية وعناوين الشبكات الخاصة: «استخدم عنوان HTTPS عامًا. روابط الشبكات المحلية والخاصة غير مسموح بها.»
    الأحداث نعم حدث واحد على الأقل. راجع الجدول أعلاه.
    نشط — محدد افتراضيًا. ألغِ التحديد لحفظه بحالة معطّل.
  3. اضغط على إنشاء. تظهر الرسالة تم إنشاء Webhook الصادر. ونافذة مفتاح التوقيع السري: «احفظه الآن، فهو يُعرض مرة واحدة فقط ولا يمكن استرجاعه لاحقًا.» اضغط على نسخ (تم النسخ إلى الحافظة.)، واحفظ المفتاح في النظام المستقبِل، ثم اضغط على تم.

#تعديل Webhook واختباره وتجديد مفتاحه وأرشفته

الإجراء الخطوات النتيجة
تحرير غيّر الاسم أو الرابط (URL) أو الأحداث أو نشط ← حفظ. تم تحديث Webhook الصادر.
اختبار اضغط على اختبار. أُضيف إرسال الاختبار إلى قائمة الإرسال. ويظهر صف في عمليات الإرسال الأخيرة.
تجديد المفتاح السري أكّد تجديد المفتاح السري — «سيتوقف المفتاح السري الحالي عن العمل. حدّث الخدمات المتصلة بالمفتاح الجديد.» تم تجديد المفتاح السري. ويُعرض المفتاح الجديد مرة واحدة.
الأرشفة أكّد أرشفة Webhook — «سيتوقف Webhook الصادر هذا عن إرسال أحداث المشروع.» تمت أرشفة Webhook. تظهر شارة مؤرشف، وتتوقف عمليات الإرسال، ويُحتفظ بالسجل.

#إنشاء رمز Webhook وارد

  1. اضغط على رمز جديد في بطاقة رموز Webhook الواردة.
  2. الاسم (إلزامي، بحد أقصى 160 حرفًا) والمزوّد: مخصص (الافتراضي) أو GitHub.
  3. اضغط على إنشاء ← تم إنشاء الرمز الوارد. انسخ رمز Webhook الوارد المعروض مرة واحدة: «استخدم هذا الرمز في رابط Webhook الوارد. يُعرض مرة واحدة فقط.»

بعدها يرسل النظام الخارجي POST /api/projects/webhooks/incoming/{token} مع محتوى بصيغة JSON (بحد أقصى 60 طلبًا في الدقيقة لكل مرسِل):

المزوّد المحتوى ماذا يحدث
مخصص {"title": "...", "description": "...", "priority": "high"} ينشئ مهمة خاصة بحالة جديدة (الأولوية الافتراضية medium، ويُقتطع العنوان عند 180 حرفًا). وتتضمن الاستجابة task_key الجديد.
مخصص {"task_key": "ALN-14", "comment": "..."} يضيف تعليقًا داخليًا إلى تلك المهمة.
GitHub حدث تذكرة أو تعليق على تذكرة تتحول التذكرة إلى مهمة، والتعليق على تذكرة يحتوي عنوانها على مفتاح مهمة (مثل ALN-14) يصبح تعليقًا على تلك المهمة.

يُرفض أي طلب آخر بالرسالة «رُفض Webhook.»، ويتلقى الرمز المُبطَل أو الخاطئ الرد نفسه. وتُنسب المهام والتعليقات إلى الشخص الذي أنشأ الرمز.

ينشئ تجديد رمزًا جديدًا ويُبطل القديم فورًا (تم تجديد الرمز.). أما إبطال فيطلب التأكيد في نافذة إبطال الرمز — «لن تتمكن الطلبات التي تستخدم هذا الرمز من الوصول بعد الآن.» ← تم إبطال الرمز.

#إنشاء رمز وصول لواجهة API العامة

  1. اضغط على رمز جديد في بطاقة واجهة API العامة.

  2. الاسم (إلزامي، بحد أقصى 120 حرفًا) والصلاحيات (صلاحية واحدة على الأقل، وprojects:read وtasks:read وtime:read محددة مسبقًا):

    الصلاحية يسمح بـ
    projects:read قراءة هذا المشروع.
    tasks:read / tasks:write قراءة المهام / إنشاؤها وتحديثها.
    time:read / time:write قراءة قيود الوقت / إنشاؤها.
  3. إنشاء ← تم إنشاء رمز API. انسخ رمز API للمشروع: «استخدمه رمز Bearer مع /api/v1. يُعرض مرة واحدة فقط.»

المهام المنشأة عبر API تشغّل قواعد الأتمتة وWebhooks نفسها التي تشغّلها المهام المنشأة داخل التطبيق. تجديد ← أكّد تجديد الرمز («سيتوقف الرمز الحالي عن العمل. حدّث الخدمات المتصلة بالرمز الجديد.») ← تم تجديد رمز API. إبطال ← تم إبطال رمز API.

#إعادة محاولة إرسال فاشل

في عمليات الإرسال الأخيرة، اضغط على إعادة المحاولة في الصف ← أُعيدت محاولة الإرسال. وبعد لحظات تحقّق من الحالة والاستجابة.

#ربط تكامل مدمج

  1. في مربع المزوّد اختر القناة (مثل #projects في Slack) واضغط على ربط ← بدأ الربط مع {Provider}.
  2. أكمل نافذة التفويض تفويض {Provider} بالضغط على إتمام الاستدعاء (أو لاحقًا) ← تم ربط التكامل المدمج.
  3. بعد الربط، استخدم إرسال اختبار (أُرسلت رسالة اختبار إلى {Provider}.) أو تحديث (تم تحديث {Provider}.) أو قطع الاتصال (تم قطع الاتصال بـ {Provider}.).

في وضع المحاكاة تعرض المربعات أيضًا محاكاة حدث وخطأ لفحص الإعداد قبل تفعيل المزوّد فعليًا، ولا تتصل بالخدمة الحقيقية.

#الحالات

العنصر الحالات
Webhook صادر نشط، معطّل (حُفظ مع إلغاء تحديد «نشط»)، مؤرشف
الإرسال قيد الانتظار، تم الإرسال، فشل، تم التخطي
رمز وارد / رمز API نشط، غير نشط، مُبطَل
تكامل مدمج متاح، قيد الانتظار، نشط، فشل

#الأذونات

الدور فتح علامة التبويب إنشاء Webhooks والرموز والمزوّدين أو تغييرها
صاحب المنظمة نعم نعم
مسؤول المشاريع نعم نعم
مدير المشاريع الذي يحمل دور مدير في هذا المشروع نعم نعم
عضو المشاريع، ومشاهد المشروع، والضيوف لا لا

إذا كان تعديل التكاملات معطّلًا في مؤسستك، تصبح علامة التبويب للقراءة فقط (بلا زر جديد ولا إجراءات الصفوف ولا إعادة المحاولة). وعند رفض تغيير تظهر الرسالة «تعديل التكاملات معطّل أو غير مسموح به.»، وإذا كانت الصفحة قديمة تظهر «يُرجى إعادة تحميل الصفحة والمحاولة مجددًا.» ولا تُعرض المفاتيح السرية والرموز مرة أخرى بعد النافذة التي تظهر لمرة واحدة، ولا حتى للمالكين.

#ربط المؤسسة بـ SolaCount

عنصر التكاملات في قسم مساحة العمل بالشريط الجانبي (/projects/settings/integrations) صفحة مختلفة. فهو يعرض ما إذا كان SolaProjects مربوطًا بـ SolaCount (متصل، جاهز للربط، التكامل متوقف مؤقتًا، غير متصل — السجل محفوظ، …)، ويتيح لمالك المؤسسة أو مسؤول المالية ربطه أو إيقافه مؤقتًا أو قطعه أو فحصه. ويمكن استثناء مشروع بعينه من علامة التبويب الإعدادات الخاصة به (بطاقة التكاملات ← مشروع داخلي / المالية معطّلة). راجع الميزانية والمالية ونظرة عامة على SolaProjects.

#أمثلة عملت

#المثال 1 — تحويل الاستفسارات إلى مهام (استخدام يومي)

تريد {User 1 name} أن تصل استفسارات الموقع الإلكتروني الخاصة بمشروع {Showroom project name} (DEMO-FIT) على شكل مهام.

  1. رمز جديد ← الاسم استفسارات الموقع الإلكتروني، والمزوّد مخصص ← إنشاء، ثم تسلّم الرمز لمطوّر الموقع.
  2. يرسل الموقع الإلكتروني الطلب {"title": "Quote request – reception desk", "priority": "high"}.
  3. تظهر المهمة ALN-31 طلب عرض سعر – مكتب الاستقبال في جديدة، خاصةً وبأولوية عالية. وتعرض بطاقة الرمز آخر استخدام 6 أكتوبر.

#المثال 2 — تغذية لوحة تحكم العميل مع حدوث فشل (سيناريو كامل)

يقوم {User 2 name} بتوصيل لوحة معلومات موقع {Organization name}.

خطوة الإجراء النتيجة
1 Webhook جديد: لوحة تحكم الموقع، https://hooks.company.example.com/projects، والأحداث task.status_changed وtask.completed وmilestone.completed. تم إنشاء Webhook الصادر.، ونُسخ مفتاح التوقيع السري إلى لوحة التحكم.
2 اختبار. أُضيف إرسال الاختبار إلى قائمة الإرسال.، ويظهر الصف بحالة تم الإرسال والاستجابة 200.
3 تنقل {User 1 name} المهمة ALN-12 إلى مكتملة. عمليتا إرسال: task.status_changed وtask.completed، وكلتاهما بحالة تم الإرسال.
4 لوحة التحكم متوقفة للصيانة. يظهر الإرسال التالي بحالة قيد الانتظار ثم فشل مع الاستجابة 503، ويظهر في الترويسة عمليات الإرسال الفاشلة 1 بالأحمر، وتُعاد المحاولة بعد نحو 1 و5 و15 و60 دقيقة.
5 تعود لوحة التحكم للعمل، فيضغط {User 2 name} على إعادة المحاولة. أُعيدت محاولة الإرسال. ← تم الإرسال.
6 يشتبه قسم تقنية المعلومات في تسرّب المفتاح السري، فيضغط {User 2 name} على تجديد المفتاح السري ويؤكد. تم تجديد المفتاح السري.، ويُعرض المفتاح الجديد مرة واحدة، فيحدّث قسم تقنية المعلومات لوحة التحكم.

#كيف يتصل

أين رابط
المهام تنشئ الرموز الواردة وواجهة API المهام والتعليقات، وترسل تغييرات المهام أحداثًا.
التخطيط يرسل اكتمال المراحل الرئيسية وبدء دورات العمل واكتمالها أحداثًا.
الأتمتة تعمل داخل SolaProjects، ويمكن إرسال عمليات التشغيل الفاشلة كأحداث.
روابط مشاركة الضيوف الحدث share_link.created.
الذكاء الاصطناعي الحدث ai.suggestion_applied.
تتبع الوقت الحدث time_entry.created، وصلاحيات API الخاصة بالوقت.
الإعدادات مفتاح تفعيل المالية مع SolaCount لكل مشروع.

#نصائح ومشاكل شائعة

مشكلة السبب إصلاح
علامة التبويب غير ظاهرة. الخطة أدنى من Premium أو منتهية. رقِّ الخطة أو جدّدها.
استخدم عنوان HTTPS عامًا… عنوان URL هو http أو localhost أو عنوان خاص. استخدم رابط HTTPS عامًا.
فقدان مفتاح سري أو رمز. يُعرض مرة واحدة فقط. استخدم تجديد وحدّث النظام الآخر.
عمليات الإرسال بحالة فشل مع رمز 4xx. عنوانك المستقبِل يرفض الطلب (غالبًا بسبب التحقق من التوقيع). تأكّد من أن العنوان المستقبِل يستخدم المفتاح السري الحالي.
ظهور رُفض Webhook. في الطلبات الواردة. الرمز مُبطَل أو خاطئ، أو المحتوى لا يتضمن title أو task_key + comment. تحقّق من الرمز ومحتوى الطلب.
لم يُضف التعليق من GitHub. عنوان التذكرة لا يتضمن مفتاح مهمة. أضف المفتاح (مثل ALN-14) إلى عنوان التذكرة.
واجهة API ترفض الوصول. الرمز لا يملك الصلاحية المطلوبة أو مُبطَل. أنشئ رمزًا بالصلاحيات المناسبة.
المزوّد يعرض المحاكي المحلي متاح… لم يُفعَّل بعد لمؤسستك. تواصل مع دعم Solavel بشأن التفعيل.