الانتقال إلى المحتوى الرئيسي
الانتقال إلى المحتوى الرئيسي

أعطال Webhooks وأخطاء API ومشكلات مزامنة CRM

عالج إخفاقات تسليم Webhooks، وأخطاء الصلاحيات 401/403 في واجهة API، ومشكلات مزامنة أنظمة CRM، واختبر أدوات الربط المتصلة بحسابك في Teammates.ai.

7 دقائقمحدّث 2026-11-08

أبرز مشكلات أدوات الربط وحلولها السريعة

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

المشكلة الظاهرةالسبب المحتملالحل السريع
عدم انطلاق إشعارات Webhookالرابط غير متاح عبر الإنترنت أو اختيار نوع حدث غير مطابقتأكد أن الرابط عام عبر HTTPS وأن نوع الحدث مطابق
إرجاع Webhook لخطأ 401 أو 403فشل التحقق من توقيع الأمانوحّد مفتاح التوقيع السري لـ Webhook في الطرفين
إرجاع طلبات API لخطأ 401 Unauthorizedرمز API منتهي الصلاحية أو غير مرفقأنشئ رمزًا جديدًا من إعدادات المؤسسة > API
إرجاع طلبات API لخطأ 403 Forbiddenرمز API لا يملك الصلاحيات اللازمةراجع صلاحيات الرمز ودور المستخدم في المؤسسة
عدم مزامنة بيانات CRMعدم تطابق ربط الحقول أو انتهاء صلاحية تفويض OAuthأعد تفويض حساب CRM وراجع ربط الحقول

عدم انطلاق إشعارات Webhook

عندما لا يستقبل عنوان Webhook لديك الأحداث من Teammates.ai، يعود السبب غالبًا إلى إتاحة الرابط على الإنترنت أو إعدادات الأحداث أو المصادقة.

  1. 1

    تأكد من إتاحة رابط Webhook عبر الإنترنت العام

    يجب أن يكون عنوان Webhook رابط HTTPS عامًا؛ فلا تعمل روابط localhost أو العناوين الداخلية أو روابط HTTP غير المشفّرة. اختبر الوصول إلى الرابط بإرسال طلب curl من جهاز خارجي.

  2. 2

    تحقّق من تفعيل أنواع الأحداث الصحيحة

    افتح إعدادات المؤسسة > Webhooks وراجع أنواع الأحداث المفعّلة على رابط Webhook لديك؛ فإذا اخترت «conversation.closed» وحده بينما تنتظر أحداث «conversation.created»، فلن يصلك إشعار عند بدء المحادثات.

  3. 3

    افحص رموز استجابة HTTP في سجل التسليم

    راجع سجل التسليم داخل إعدادات Webhook؛ إذ تعرض كل محاولة رمز حالة HTTP العائد من خادمك. ويعني الرمز 200 نجاح الاستلام، بينما تشير رموز 4xx أو 5xx إلى رفض الخادم للطلب أو إخفاقه في معالجته.

  4. 4

    استخدم ميزة «إرسال Webhook تجريبي»

    انقر على «إرسال تجريبي» في إعدادات Webhook لترسل Teammates.ai حدثًا تجريبيًا إلى عنوانك، ثم افحص سجلات خادمك للتأكد من استلام الحدث ومعالجته بنجاح.

  5. 5

    تأكد من مطابقة مفتاح التحقق من التوقيع

    إذا كان خادمك يتحقق من توقيع رسائل Webhook، فتأكد أن مفتاح التوقيع السري في كود تطبيقك يطابق المفتاح الموجود في إعدادات المؤسسة > Webhooks؛ إذ يؤدي أي اختلاف بينهما إلى رفض الأحداث الصحيحة بخطأ 401 أو 403.

أخطاء 401 و403 في واجهة API

إذا أعادت طلباتك إلى واجهة API في Teammates.ai خطأ 401 (غير مصرّح) أو 403 (محظور)، فالسبب في رمز الوصول أو الصلاحيات أو حدود معدل الطلبات.

  1. 1

    أنشئ رمز API جديدًا

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

  2. 2

    تحقّق من صيغة ترويسة Authorization

    تتطلب واجهة API إرسال الترويسة بالصيغة: Authorization: Bearer YOUR_TOKEN. تأكد من خلو الترويسة من أي مسافات زائدة، ومن كتابة البادئة «Bearer»، وسلامة ترميز النص في الطلب.

  3. 3

    راجع صلاحيات الرمز ودور المستخدم

    إذا ظهر لك الخطأ 403 (لا 401)، فالرمز صالح لكنه لا يملك صلاحية تنفيذ العملية المطلوبة. تأكد أن المستخدم الذي أصدر الرمز يحمل الدور المناسب (المالك أو المسؤول أو المدير) لنقطة نهاية API المستدعاة.

  4. 4

    تحقّق من حدود معدل الطلبات

    عند إرسال عدد كبير من الطلبات خلال فترة وجيزة، تعيد واجهة API الرمز 429 (طلبات كثيرة جدًا). افحص ترويسات الاستجابة لمعرفة سقف المعدل المسموح، وأضف آلية إعادة المحاولة المتدرجة (Backoff) في كود تطبيقك.

مشكلات مزامنة نظام CRM

إذا لم تظهر بيانات راية أو آدم في نظام CRM لديك (أو العكس)، فالخلل عادةً في ربط الحقول أو صلاحيات الحساب أو انتهاء تفويض OAuth.

  1. 1

    أعد تفويض ربط نظام CRM

    افتح إعدادات المؤسسة > أدوات الربط وتأكد أن حالة نظام CRM (مثل Salesforce أو HubSpot) تظهر «متصل»؛ وإذا ظهرت «غير متصل» أو «منتهي الصلاحية»، انقر على «إعادة التفويض» لتجديد رمز OAuth.

  2. 2

    راجع مطابقة الحقول

    افحص إعدادات ربط CRM وتأكد من اقتران كل حقل في Teammates.ai بالحقل المقابل له في CRM؛ إذ يؤدي ربط حقل بآخر غير مطابق (مثل ربط «البريد الإلكتروني» بحقل «الهاتف») إلى ظهور البيانات في موضع خاطئ أو فشل حفظها.

  3. 3

    تأكد من صلاحيات مستخدم CRM

    يحتاج حساب المستخدم المربوط في نظام CRM إلى صلاحيتَي القراءة والكتابة على السجلات التي تزامنها Teammates.ai (جهات الاتصال، والعملاء المحتملون، والصفقات، والأنشطة)؛ فنقص الصلاحيات يوقف المزامنة دون إتمام الحفظ.

  4. 4

    افحص سجلات المزامنة

    افتح إعدادات المؤسسة > أدوات الربط > نظام CRM المتصل وراجع سجل المزامنة؛ حيث توضّح العمليات الفاشلة سبب الخطأ بدقة (مثل «حقل إلزامي مفقود» أو «سجل مكرر» أو «صلاحية مرفوضة»).

طلب مساعدة إضافية

إذا لم تحل هذه الخطوات مشكلة الربط، اسأل راية من نافذة الدعم في مركز المساعدة أو راسل فريق الدعم على support@teammates.ai، مع ذكر نوع الربط (Webhook أو API أو CRM) ورسائل الخطأ أو رموز حالة HTTP وتفاصيل الطلب والاستجابة إن توفرت.

الأسئلة الشائعة

هل واجهة API في Teammates.ai متاحة ضمن الخطة المجانية؟
نعم، تتوفر واجهة API ودعم Webhooks في جميع الخطط بما فيها الخطة المجانية.
كيف أختبر رابط Webhook دون انتظار أحداث حقيقية؟
استخدم زر «إرسال Webhook تجريبي» من إعدادات المؤسسة > Webhooks؛ إذ يرسل بيانات حدث نموذجية إلى عنوانك لتتأكد من سلامة الاستلام والمعالجة دون المساس ببياناتك الفعلية.
ما أنظمة CRM التي ترتبط بها Teammates.ai؟
ترتبط Teammates.ai مع Salesforce وHubSpot وغيرها من أنظمة CRM عبر الربط المباشر وZapier؛ حيث يزامن كل من راية وآدم بيانات المحادثات والعملاء المحتملين وسجلات النشاط مع نظام CRM تلقائيًا.

أدلة ذات صلة

هل كان هذا المقال مفيدًا؟

Raya
Adam

تحتاج مساعدة إضافية؟

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