أعطال Webhooks وأخطاء API ومشكلات مزامنة CRM
عالج إخفاقات تسليم Webhooks، وأخطاء الصلاحيات 401/403 في واجهة API، ومشكلات مزامنة أنظمة CRM، واختبر أدوات الربط المتصلة بحسابك في Teammates.ai.
أبرز مشكلات أدوات الربط وحلولها السريعة
يوضّح الجدول التالي أكثر مشكلات أدوات الربط شيوعًا وأسبابها المحتملة وأسرع حل لكل منها.
| المشكلة الظاهرة | السبب المحتمل | الحل السريع |
|---|---|---|
| عدم انطلاق إشعارات Webhook | الرابط غير متاح عبر الإنترنت أو اختيار نوع حدث غير مطابق | تأكد أن الرابط عام عبر HTTPS وأن نوع الحدث مطابق |
| إرجاع Webhook لخطأ 401 أو 403 | فشل التحقق من توقيع الأمان | وحّد مفتاح التوقيع السري لـ Webhook في الطرفين |
| إرجاع طلبات API لخطأ 401 Unauthorized | رمز API منتهي الصلاحية أو غير مرفق | أنشئ رمزًا جديدًا من إعدادات المؤسسة > API |
| إرجاع طلبات API لخطأ 403 Forbidden | رمز API لا يملك الصلاحيات اللازمة | راجع صلاحيات الرمز ودور المستخدم في المؤسسة |
| عدم مزامنة بيانات CRM | عدم تطابق ربط الحقول أو انتهاء صلاحية تفويض OAuth | أعد تفويض حساب CRM وراجع ربط الحقول |
عدم انطلاق إشعارات Webhook
عندما لا يستقبل عنوان Webhook لديك الأحداث من Teammates.ai، يعود السبب غالبًا إلى إتاحة الرابط على الإنترنت أو إعدادات الأحداث أو المصادقة.
- 1
تأكد من إتاحة رابط Webhook عبر الإنترنت العام
يجب أن يكون عنوان Webhook رابط HTTPS عامًا؛ فلا تعمل روابط localhost أو العناوين الداخلية أو روابط HTTP غير المشفّرة. اختبر الوصول إلى الرابط بإرسال طلب curl من جهاز خارجي.
- 2
تحقّق من تفعيل أنواع الأحداث الصحيحة
افتح إعدادات المؤسسة > Webhooks وراجع أنواع الأحداث المفعّلة على رابط Webhook لديك؛ فإذا اخترت «conversation.closed» وحده بينما تنتظر أحداث «conversation.created»، فلن يصلك إشعار عند بدء المحادثات.
- 3
افحص رموز استجابة HTTP في سجل التسليم
راجع سجل التسليم داخل إعدادات Webhook؛ إذ تعرض كل محاولة رمز حالة HTTP العائد من خادمك. ويعني الرمز 200 نجاح الاستلام، بينما تشير رموز 4xx أو 5xx إلى رفض الخادم للطلب أو إخفاقه في معالجته.
- 4
استخدم ميزة «إرسال Webhook تجريبي»
انقر على «إرسال تجريبي» في إعدادات Webhook لترسل Teammates.ai حدثًا تجريبيًا إلى عنوانك، ثم افحص سجلات خادمك للتأكد من استلام الحدث ومعالجته بنجاح.
- 5
تأكد من مطابقة مفتاح التحقق من التوقيع
إذا كان خادمك يتحقق من توقيع رسائل Webhook، فتأكد أن مفتاح التوقيع السري في كود تطبيقك يطابق المفتاح الموجود في إعدادات المؤسسة > Webhooks؛ إذ يؤدي أي اختلاف بينهما إلى رفض الأحداث الصحيحة بخطأ 401 أو 403.
أخطاء 401 و403 في واجهة API
إذا أعادت طلباتك إلى واجهة API في Teammates.ai خطأ 401 (غير مصرّح) أو 403 (محظور)، فالسبب في رمز الوصول أو الصلاحيات أو حدود معدل الطلبات.
- 1
أنشئ رمز API جديدًا
افتح إعدادات المؤسسة > API وأنشئ رمز وصول جديدًا، ثم استبدل الرمز القديم في كود تطبيقك؛ إذ قد تنتهي صلاحية الرموز أو تُلغى، لذا اعتمد الرمز الأحدث دائمًا.
- 2
تحقّق من صيغة ترويسة Authorization
تتطلب واجهة API إرسال الترويسة بالصيغة: Authorization: Bearer YOUR_TOKEN. تأكد من خلو الترويسة من أي مسافات زائدة، ومن كتابة البادئة «Bearer»، وسلامة ترميز النص في الطلب.
- 3
راجع صلاحيات الرمز ودور المستخدم
إذا ظهر لك الخطأ 403 (لا 401)، فالرمز صالح لكنه لا يملك صلاحية تنفيذ العملية المطلوبة. تأكد أن المستخدم الذي أصدر الرمز يحمل الدور المناسب (المالك أو المسؤول أو المدير) لنقطة نهاية API المستدعاة.
- 4
تحقّق من حدود معدل الطلبات
عند إرسال عدد كبير من الطلبات خلال فترة وجيزة، تعيد واجهة API الرمز 429 (طلبات كثيرة جدًا). افحص ترويسات الاستجابة لمعرفة سقف المعدل المسموح، وأضف آلية إعادة المحاولة المتدرجة (Backoff) في كود تطبيقك.
مشكلات مزامنة نظام CRM
إذا لم تظهر بيانات راية أو آدم في نظام CRM لديك (أو العكس)، فالخلل عادةً في ربط الحقول أو صلاحيات الحساب أو انتهاء تفويض OAuth.
- 1
أعد تفويض ربط نظام CRM
افتح إعدادات المؤسسة > أدوات الربط وتأكد أن حالة نظام CRM (مثل Salesforce أو HubSpot) تظهر «متصل»؛ وإذا ظهرت «غير متصل» أو «منتهي الصلاحية»، انقر على «إعادة التفويض» لتجديد رمز OAuth.
- 2
راجع مطابقة الحقول
افحص إعدادات ربط CRM وتأكد من اقتران كل حقل في Teammates.ai بالحقل المقابل له في CRM؛ إذ يؤدي ربط حقل بآخر غير مطابق (مثل ربط «البريد الإلكتروني» بحقل «الهاتف») إلى ظهور البيانات في موضع خاطئ أو فشل حفظها.
- 3
تأكد من صلاحيات مستخدم CRM
يحتاج حساب المستخدم المربوط في نظام CRM إلى صلاحيتَي القراءة والكتابة على السجلات التي تزامنها Teammates.ai (جهات الاتصال، والعملاء المحتملون، والصفقات، والأنشطة)؛ فنقص الصلاحيات يوقف المزامنة دون إتمام الحفظ.
- 4
افحص سجلات المزامنة
افتح إعدادات المؤسسة > أدوات الربط > نظام CRM المتصل وراجع سجل المزامنة؛ حيث توضّح العمليات الفاشلة سبب الخطأ بدقة (مثل «حقل إلزامي مفقود» أو «سجل مكرر» أو «صلاحية مرفوضة»).
طلب مساعدة إضافية
إذا لم تحل هذه الخطوات مشكلة الربط، اسأل راية من نافذة الدعم في مركز المساعدة أو راسل فريق الدعم على support@teammates.ai، مع ذكر نوع الربط (Webhook أو API أو CRM) ورسائل الخطأ أو رموز حالة HTTP وتفاصيل الطلب والاستجابة إن توفرت.
الأسئلة الشائعة
هل واجهة API في Teammates.ai متاحة ضمن الخطة المجانية؟
كيف أختبر رابط Webhook دون انتظار أحداث حقيقية؟
ما أنظمة CRM التي ترتبط بها Teammates.ai؟
أدلة ذات صلة
هل كان هذا المقال مفيدًا؟

تحتاج مساعدة إضافية؟
اسألنا أي شيء بأي لغة. راية (الدعم) وآدم (المبيعات) يجيبانك على مدار الساعة بأكثر من 54 لغة و19 لهجة عربية.
