منصة المطوّرين

المصادقة والنطاقات

تُنشأ المفاتيح من الإعدادات ثم التكاملات ثم مفاتيح API، وتُعرض مرة واحدة عند الإنشاء. ويحمل كل مفتاح نطاقات، فالمفتاح الذي يحتاج إنشاء العملاء فقط يحمل leads.create وحده ولا يستطيع فعل شيء آخر إن تسرّب.

• الترويسة: x-api-key
• مفاتيح بنطاقات، مثل leads.create
• تُصدَر لكل مساحة عمل وقابلة للتدوير
• تُعرض مرة واحدة عند الإنشاء

استقبال العملاء

POST /v1/public/leads هي نقطة الدخول لأي شيء ينتج استفساراً. ويُفحص العميل ضد جهات اتصال مساحة العمل بالهاتف والبريد لمنع التكرار، ثم يُوزَّع بقواعد التوزيع لديك، فيُعامَل العميل المُنشأ عبر الواجهة تماماً كعميل وصل من منصة.

• POST /v1/public/leads
• أرسل رقم هاتف أو بريداً على الأقل
• تقبل حقول المتطلبات والمصدر وutm والميزانية وعدد الغرف واللغة
• تعيد lead_id وreference وcontact_id وعلامة duplicate
• ترد 201 عند الإنشاء و200 عند مطابقة عميل قائم

الحماية من التكرار وحدود المعدل

مرّر external_id فتصبح إعادة المحاولة آمنة: فحين يوجد عميل بذلك المعرّف يُعاد الأصلي مع duplicate بقيمة true ورمز 200، بدل إنشاء سجل ثانٍ. واستقبال العملاء محدود بـ ٢٤٠ طلباً في الدقيقة لكل مفتاح أو عنوان IP، ويعيد الطلب المتجاوز 429 مع ترويسة Retry-After.

• external_id حتى ١٢٠ حرفاً يجعل إعادة المحاولة آمنة
• التكرار يعيد السجل الأصلي
• استقبال العملاء: ٢٤٠ طلباً في الدقيقة لكل مفتاح أو IP
• 429 مع Retry-After عند التجاوز

الـ Webhooks الصادرة

سجّل نقطة استقبال واشترك بأنواع الأحداث التي تريدها. ويحمل كل تسليم نوع الحدث، ومعرّف تسليم يبقى ثابتاً عبر إعادات المحاولة لتتمكن من منع التكرار، وتوقيعاً حين يكون للنقطة سر مضبوط.

• x-clixcrm-event يسمّي نوع الحدث
• x-clixcrm-delivery ثابت عبر إعادات المحاولة
• x-clixcrm-signature هو sha256 مع HMAC SHA256 سداسي للجسم الخام
• قارن التوقيع بزمن ثابت
• أي رمز 2xx نجاح، وما عداه يُعاد
• تباعد ١ ثم ٢ ثم ٤ ثوانٍ فصاعداً، بحد أقصى ٣٠ دقيقة، وست محاولات
• بعد ست محاولات يُعلَّم التسليم ميتاً ويظهر في النظام

أنواع الأحداث الثلاثة والعشرون

العملاء وجهات الاتصال والقوائم والمنصات والاجتماعات والمعاينات والحجوزات والصفقات والمستندات والرسائل. وتشترك كل نقطة بما تحتاجه فقط.

• lead.created, lead.updated, lead.assigned, lead.stage_changed, lead.sla_breached
• contact.created
• listing.created, listing.approved, listing.published, listing.rejected
• portal.error
• meeting.created, viewing.completed
• reservation.created, reservation.expired, booking.created
• deal.created, deal.updated, deal.won, deal.lost, deal.cancelled
• document.generated, message.received

تغذيات المنصات والصور

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

• رابط تغذية لكل حساب منصة، بصيغة تلك المنصة
• الرمز قابل للتدوير من النظام
• روابط صور عامة دائمة مدعومة بروابط تخزين قصيرة العمر

Zapier

يعرض كليكس قائمة محفّزاته وسجلاً حقيقياً لكل محفّز، وهو ما يقرأه تطبيق Zapier لبناء محفّزاته وعرض أسماء الحقول أثناء كتابة الـ Zap. ويسمّي كل محفّز نوع حدث يمكن لنقطة Webhook صادرة الاشتراك به.

• قائمة المحفّزات معروضة لتطبيق Zapier
• سجل حقيقي لكل محفّز، أو null حين لا يوجد لدى مساحة العمل بعد
• المحفّزات تقابل أنواع أحداث الـ Webhooks الصادرة

الـ Webhooks الواردة التي يستقبلها كليكس

الاتجاه الآخر موصول أصلاً للمزوّدين الذين يتكامل معهم كليكس، لكل منها تحققه الخاص: إعلانات ميتا للعملاء، وواتساب للأعمال، ودفعات عملاء المنصات بما فيها توقيع HMAC من بروبرتي فايندر، وأحداث مغلفات التوقيع الإلكتروني، وإشعارات بريد Microsoft Graph، وأحداث فوترة Stripe.

• إعلانات ميتا للعملاء، مع مصافحة التحقق
• رسائل واتساب للأعمال وحالات التسليم
• دفعات عملاء المنصات، نقطة لكل حساب منصة
• أحداث مغلفات التوقيع: مرسل، مُشاهَد، موقّع، مرفوض
• إشعارات بريد Microsoft Graph
• أحداث فوترة Stripe

لماذا السطح العام ضيّق عن قصد

تعرض الواجهة العامة استقبال العملاء وتغذيات المنصات وروابط الصور ودعم Zapier والـ Webhooks الصادرة. وهي ليست واجهة قراءة وكتابة كاملة على كل موارد النظام، وهذا قرار أمني لا ميزة ناقصة. فالمفتاح الذي يتسرّب يجب ألا يستطيع قراءة قاعدة عملاء شركة وساطة، ولذلك تبقى العمليات الحساسة داخل التطبيق المُصادَق خلف صلاحيات مبنية على الأدوار، ويُبقى السطح العام عند أضيق مجموعة تكفي لربط موقعك وحسابك الإعلاني وأنظمتك.

• كل مفتاح عام محصور بالعملية التي يحتاجها
• القراءات والكتابات الحساسة تبقى داخل التطبيق المُصادَق
• الـ Webhooks الصادرة تغطي معظم ما يحتاج التكامل مراقبته
• بيانات الاعتماد وتفاصيل النقاط الداخلية تُشارَك باتفاقية لا تُنشَر

إن احتجت أكثر من ذلك

أخبرنا بحالتك. فبعض ما يطلبه الناس موجود أصلاً خلف المصادقة ويحتاج نطاقاً فقط، وبعضه يُحل بالاشتراك في Webhook أفضل من نقطة سحب دوري، وبعضه غير موجود فعلاً. ونفضّل إجراء تلك المحادثة على نشر سطح لا نستطيع تأمينه. راسل sales@clix-crm.com بما تحاول ربطه.