🔧 استكشاف الأخطاء
حلول للمشاكل الشائعة عند استخدام Omdaa API.
📱 الجلسة غير متصلة أو QR لا يعمل
الأعراض: رسالة «الجلسة غير متصلة» أو QR منتهي أو لا يمسح.
- تأكد أن رقم واتساب المستخدم للربط متصل بالإنترنت وأن واتساب مفتوح على الجهاز.
- اطلب QR جديداً عبر
GET /api/v1/instances/:sessionId/qr— رمز QR له صلاحية محدودة. - تحقق أن
sessionIdصحيح وأن الجلسة لم تُحذف من لوحة التحكم. - إن استمرت المشكلة، جرّب إعادة تشغيل الجلسة أو إنشاء جلسة جديدة وربطها من جديد.
✉️ الرسائل لا تُرسل أو تُرجع خطأ
الأعراض: 400/404/500 أو رسالة «فشل الإرسال».
- تحقق أن الجلسة في حالة «متصل» قبل الإرسال.
- تأكد من صيغة الرقم: استخدم صيغة دولية بدون + أو مسافات (مثال: 966501234567).
- للرسائل الأولى خارج نافذة 24 ساعة، استخدم قالباً معتمداً من واتساب.
- راجع جسم الاستجابة (response body) لمعرفة رمز الخطأ والرسالة من الـ API.
🔐 401 Unauthorized أو 403 Forbidden
الأعراض: رفض الطلبات مع 401 أو 403.
- تأكد أن رأس
Authorization: Bearer YOUR_JWTأوX-API-Key: your_keyمضاف وقيمته صحيحة. - تحقق أن JWT لم ينتهِ صلاحيته — أعد تسجيل الدخول للحصول على توكن جديد.
- إن كنت تستخدم مفتاح API، تأكد أنه لم يُلغَ ولم ينتهِ تاريخه.
🔗 الويب هوك لا يستقبل أحداثاً
الأعراض: لا تصل طلبات POST إلى خادمك.
- تأكد أن رابط الويب هوك عام (يُستدعى من الإنترنت) ويدعم HTTPS.
- تحقق أن الخادم يرد بـ 2xx خلال وقت معقول (مثلاً أقل من 30 ثانية).
- راجع إعدادات الجلسة في لوحة التحكم أو عبر API أن الـ URL مسجّل والأحداث المطلوبة مفعّلة.
- استخدم أداة مثل ngrok للتجربة المحلية وتأكد أن المسار لا يُرجع 404.
⏱️ 429 Too Many Requests
الأعراض: رفض الطلبات بسبب تجاوز معدل الطلبات.
- انتظر المدة في رأس
Retry-Afterإن وُجد. - قلّل عدد الطلبات أو استخدم التخزين المؤقت والـ batching. راجع دليل معدلات الطلبات.
📞 مزيد من المساعدة
إن لم تجد الحل، راجع صفحة الأخطاء والأمان في التوثيق، أو تواصل مع الدعم الفني مع تفاصيل الطلب (رمز الحالة، رسالة الخطأ، ووقت الحدوث).