التكاملات

افتح الإعدادات، ثم اختر مجال التكاملات لربط كسبلي بالقنوات والأدوات والتطبيقات والإضافات.

يحتوي مجال التكاملات على الأهداف التالية:

إضافة إعداد جاهز — ثبّت حزمة من المتجر.
ربط واتساب والأدوات والتطبيقات — أدر تكاملات الواجهة البرمجية وقدرات المساعد.
ربط واتساب للأعمال — أدر حسابات الأعمال والأرقام والقوالب والتحقق.
فحص صحة الاتصال — راجع فحوصات صحة القنوات والتكاملات.
تنبيهات النشاط — اختر طريقة توصيل الإشعارات والتنبيهات.
تشغيل/إيقاف الميزات — أدر علامات ميزات مساحة العمل المتقدمة.
الإضافات الصناعية — افتح الإضافات المثبّتة وإعداداتها.

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

للوصول البرمجي بمفاتيحك الخاصة، افتح هدف مفاتيح المطوّرين في مجال الأشخاص والوصول، أو راجع مفاتيح API.

عقد API لـ CRM مخصص

اختر CRM مخصص (API) عندما يوفّر CRM لديك نقطة REST. يرسل كسبلي الترويسة Authorization: Bearer <API key> وJSON إلى المسارات التالية:

GET /health (أو رابط الأساس) لفحص الاتصال.
يستقبل POST /contacts القيمة { contacts: [...] }؛ ويتضمن كل عميل id وphone وname وemail وcity وlanguage وtags وcustomFields وleadScore.
يعيد GET /contacts?since=<ISO-8601> مصفوفة أو { data: [...] } أو { contacts: [...] } أو { results: [...] } باستخدام الحقول نفسها.
يستقبل POST /deals القيمة { deals: [...] }؛ ويتضمن كل عرض id وcustomerId وcustomerPhone وcustomerEmail وcustomerName وstage وvalue وcurrency وtitle.
يعيد GET /deals?since=<ISO-8601> أحد أغلفة المصفوفة نفسها وبالحقول نفسها.
يحدّث POST /deals/{id}/stage مرحلة عرض واحد. أرسل { stageId, externalStageId } بالقيمة نفسها لمعرّف المرحلة الخارجي في الحقلين. قيمة stageId هي معرّف المرحلة الخارجي الذي تدخله في جدول ربط مراحل CRM.

ترقيم صفحات السحب

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

لاستجابة GET /contacts أو GET /deals المرقمة بالصفحات، استخدم أحد أغلفة الكائنات التالية (بحيث تكون data أو contacts أو deals أو results هي مصفوفة السجلات):

أعد { data: [...], next: "opaque-next-cursor" } للمتابعة بمؤشر. يعيد كسبلي إرسال القيمة كـ ?cursor=opaque-next-cursor، مع since عند وجوده. احذف next من الصفحة الأخيرة.
أو أعد { data: [...], cursor: "opaque-next-cursor", hasMore: true }. يعيد كسبلي إرسال cursor بالطريقة نفسها. اجعل hasMore: false (أو احذفه) في الصفحة الأخيرة.
أو أعد { data: [...], page: 1, hasMore: true }. يطلب كسبلي الصفحة التالية باستخدام ?page=2؛ أعد رقم الصفحة الرقمية الحالية في كل استجابة واجعل hasMore: false في الصفحة الأخيرة.

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

للمزامنة ثنائية الاتجاه، أعد id ثابتاً وcustomerPhone لكل عرض. عندما لا يكون للشخص المرتبط رقم هاتف، أدرج customerEmail حتى يتمكن كسبلي من مطابقة عميل موجود بالبريد الإلكتروني؛ يُتخطى الشخص غير المطابق الذي يملك بريداً فقط مع إرشاد للاسترداد في سجل المزامنة.

معرّف id الذي يرسله كسبلي عند POST /deals هو معرّف محادثة كسبلي الأصلية. أعد معرّف id نفسه دون تغيير عند GET /deals (أو أعده بشكل منفصل في kasblyRecordId أو conversationId أو kasbly_conversation_id إذا كان نظام CRM يعيّن معرّفاً خاصاً به) لكي تعيد عملية السحب التالية ربط المحادثة التي دُفع منها العرض بدلاً من إنشاء نسخة مكررة.

استخدم جدول ربط مراحل CRM لربط كل قيمة stage واردة بمرحلة دورة حياة في كسبلي. احذف الحقل الذي لا يعرفه CRM لديك بدلاً من إرسال قيمة فارغة تستبدل بيانات موجودة.

قيمة stage التي يرسلها كسبلي عند POST /deals هي معرّف المرحلة الخارجي من ذلك الجدول نفسه، وتطابق POST /deals/{id}/stage. وعندما لا توجد لمرحلة دورة الحياة خريطة صادرة، يُرسل العرض من دون stage، لذلك يحتفظ نظام CRM بالمرحلة الموجودة لديه بدلاً من تلقي اسم مرحلة من كسبلي.

خطافات الويب الواردة لـ CRM المخصص

لإرسال تغيير مرحلة أو جهة اتصال من CRM إلى كسبلي، أرسل طلب POST إلى /v1/webhooks/crm/custom. أضف في الترويسة X-Tenant-Id معرّف مساحة عمل كسبلي التي تستخدم CRM مخصص (API).

صادِق الطلب بإحدى الطريقتين التاليتين:

Authorization: Bearer <API key> باستخدام مفتاح API المضبوط لاتصال CRM المخصص.
X-Webhook-Secret: <signature>، حيث تكون signature قيمة HMAC-SHA256 بصيغة hex صغيرة لمحارف نص JSON الخام للطلب، باستخدام سر Webhook المخصص الذي يظهر مرة واحدة بعد حفظ اتصال CRM المخصص. انسخ السر قبل مغادرة صفحة الإعدادات. تبقى عمليات التكامل الحالية التي توقّع بمفتاح API المضبوط مدعومة للتوافق، لكن ينبغي أن تستخدم عمليات التكامل الجديدة سر Webhook المخصص.

يمكن أن تكون بيانات الحدث في المستوى الأعلى أو داخل data أو payload. استخدم event أو type لتحديد الحدث؛ تعامَل القيم التي تحتوي deal أو opportunity كأحداث عروض، والقيم التي تحتوي contact أو lead كأحداث جهات اتصال. لتغيير مرحلة، أرسل معرّف العرض الخارجي في أحد الحقول id أو external_id أو objectId أو object_id أو record_id أو resource_id، والمرحلة الخارجية في أحد الحقول newStageId أو new_stage_id أو newStageName أو new_stage_name أو externalStageId أو external_stage_id أو externalStageName أو external_stage_name أو externalStage أو external_stage أو stage_id أو deal_stage أو pipeline_stage أو stage أو pipeline. تقبل مطابقة جهات الاتصال phone أو phone_number أو customerPhone أو customer_phone أو person_phone أو contact_phone، كما تقبل email أو customerEmail أو customer_email أو person_email أو contact_email.

العروض وجهات الاتصال المحذوفة

لا يستنتج كسبلي الحذف من غياب سجل في GET /deals أو GET /contacts؛ فالسحب ينشئ السجلات ويحدّثها فقط. عند حذف عرض أو جهة اتصال في CRM الخاص بك، أرسل حدث حذف ليتوقف كسبلي عن مزامنة المحادثة أو العميل المطابق. وإلا فسيرسله طلب POST /deals الصادر التالي مرة أخرى وسيعيد CRM إنشاء السجل الذي حذفته.

اجعل event (أو type) قيمة تحتوي deal أو opportunity أو contact أو lead مع delete أو remove، مثل deal.deleted أو opportunity.removed أو contact.deleted. وأرسل معرّف السجل الخارجي في أحد حقول المعرّف المذكورة أعلاه (id أو external_id أو objectId أو object_id أو record_id أو resource_id). يُؤكَّد استلام حدث الحذف دون إرسال أي شيء إلى CRM الخاص بك.

HubSpot CRM

يستخدم HubSpot CRM OAuth وينشئ الخصائص التي يحتاجها كسبلي أثناء الاتصال. راجع دليل الإعداد لمعرفة معرّف الصفقة المطلوب وطريقة إعادة ربط بوابة منعت صلاحيات المسؤول فيها الإعداد.

Pipedrive CRM

يستخدم Pipedrive CRM OAuth وينشئ حقول الصفقات والأشخاص التي يحتاجها كسبلي أثناء الاتصال. راجع دليل الإعداد لمعرفة أسماء الحقول اليدوية إذا احتاج المسؤول إلى إكمال الإعداد.