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

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

ابحث حسب العرَض

ما تراه	ابدأ هنا
ليس لديك API key ولا تعرف أين تُنشئه	استدعاء API لا يعمل بعد
يفشل إصدار الرمز، أو تُعيد الطلبات 401 / 403	استدعاء API لا يعمل بعد
جهاز مفقود، أو حالته لا تبدو حديثة	بيانات الجهاز لا تبدو صحيحة
تريد مراقبة الملحقات أو حالة الانقطاع أو فقدان الطاقة باستمرار	بيانات الجهاز لا تبدو صحيحة
قُبل أمر لكن لم يستجب الجهاز أو انتهت مهلته	عملية جهاز لم تكتمل كما هو متوقّع
لا يستطيع WebSocket الاتصال، أو ينقطع كثيرًا، أو لديه فجوات في الأحداث	الاتصال الفوري غير مستقر
لست متأكدًا من استخدام REST API أم WebSocket	REST API أم WebSocket
تُعيد الطلبات 429 أو 503 أو بوابة غير متاحة	الطلبات محدودة أو الخدمة غير متاحة مؤقتًا
المشكلة مستمرة بعد اتباع التوثيق	جهّز تفاصيل حل المشكلات

استدعاء API لا يعمل بعد

كيف أنشئ API Client وأحصل على بيانات اعتماد؟

أنشئ API Client في Developer Console الخاص بـ WLTE.

1. سجّل الدخول إلى Developer Console: https://developer.svnwi.com/wlte
2. افتح تطبيقًا وانتقل إلى إدارة API Client.
3. أنشئ API Client واختر أقل الصلاحيات اللازمة للتكامل.
4. احفظ clientId وclientSecret المُولَّدين.

يوفّر إنشاء API Client قيمتَي clientId وclientSecret، تُستخدمان معًا للحصول على access token.

يُعرض clientSecret فقط عند الإنشاء أو التدوير. خزّنه فورًا في تخزين أسرار جانب الخادم. إذا فُقد، دوّر السر لأن القيمة الأصلية لا يمكن رؤيتها مجددًا. راجع الحصول على API Keys.

يفشل إصدار access token

تحقّق من هذه النقاط بالترتيب:

1. API Client موجود ونشط.
2. ينتمي clientId وclientSecret إلى العميل نفسه.
3. التطبيق والحساب نشطان.
4. يتطابق عنوان URL والطريقة وجسم الطلب مع إنشاء access token (بالإنجليزية).

لا تعِد محاولة بيانات اعتماد غير صالحة إلى ما لا نهاية، لأن المصادقة قد تخضع أيضًا لحدود تكرار.

رمز الاستجابة هو AUTH_INVALID

بيانات الاعتماد، أو حالة مالكها الحالية، غير صالحة. الأسباب الشائعة هي بيانات اعتماد خاطئة، أو API Client معطّل أو محذوف، أو تطبيق معطّل، أو حساب في حالة غير صالحة.

إذا دوّرت السر مؤخرًا، تحقّق من أنك تستخدم السر الجديد. اجعل منطق التفرّع مبنيًا على code، وليس على message.

رمز الاستجابة هو AUTH_SCOPE_DENIED

لا يملك API Client الصلاحية التي تتطلبها نقطة النهاية. يحدّد data.requiredScope الصلاحية الناقصة.

أضِف تلك الصلاحية في Developer Console، واحفظ التغيير، واحصل على رمز جديد، ثم أعد المحاولة. راجع الصلاحيات (بالإنجليزية).

هل يمكن استخدام رمز قديم بعد تعطيل API Client أو حذفه؟

لا. تتحقق نقاط النهاية المحمية من الحالة الحالية لـ API Client والتطبيق والحساب، وليس فقط من انتهاء صلاحية JWT.

بعد تعطيل العميل أو حذفه، لا يمكن إصدار رموز جديدة وتُرفض الرموز الحالية.

هل يمكن تخزين clientSecret في موقع ويب أو تطبيق جوّال؟

لا. clientSecret بيانات اعتماد خادم. لا يمكن لموارد المتصفح، ولا حزم التطبيقات، ولا سجلات العميل حمايته بشكل موثوق.

احتفظ ببيانات الاعتماد على خادم تحت سيطرتك. لا تكتب clientSecret أو access token أو تذاكر WebSocket في كود الواجهة الأمامية، أو المستودعات العامة، أو السجلات.

بيانات الجهاز لا تبدو صحيحة

جهاز مفقود من قائمة الأجهزة

تأكّد أولًا أن الجهاز ينتمي إلى الحساب الحالي وأن API Client مسموح له بالوصول إليه.

إذا ظهر الجهاز في Developer Console لكن ليس في API، تحقّق من صلاحيات الوصول الممنوحة على ذلك الجهاز ومن نطاق device:read. إذا بقي السبب غير واضح، سجّل requestId قبل التواصل مع الدعم.

حالة قائمة الأجهزة لا تطابق الجهاز الفعلي الآن

تُعيد قائمة الأجهزة حالة الجهاز المتزامنة بالفعل من قِبل المنصة. لا تُحدّث بفعالية كل جهاز فعلي مع كل طلب قائمة، وهي مخصصة لعروض القوائم، ولوحات التحكم، والقراءات الجماعية.

للتحديث الصريح من المستخدم، أو قبل وبعد تنفيذ عملية، استخدم الحصول على جهاز (بالإنجليزية) أو طلب حالة عبر WebSocket.

هل يمكنني استخدام استعلامات HTTP متكررة لمراقبة الملحقات أو الانقطاع أو الطاقة؟

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

النهج الموصى به:

1. استخدم سرد الأجهزة (بالإنجليزية) للقوائم، ولوحات التحكم، والمزامنة في الخلفية.
2. استخدم الحصول على جهاز (بالإنجليزية) أو device.state.get عبر WebSocket عندما يحدّث المستخدم صراحةً صفحة تفاصيل جهاز واحد.
3. استخدم أحداث WebSocket للمراقبة المستمرة لتغيّرات الانقطاع والطاقة والملحقات؛ بعد إعادة الاتصال، أكّد الحالة الحرجة مجددًا عبر HTTP أو device.state.get.

لا تستدعِ نقطة نهاية التحديث الفوري كل بضع ثوانٍ لكل جهاز. لا تضمن تسليم أحداث دون فقدان وقد تؤثر على طلبات عادية أخرى ضمن الحساب نفسه.

deviceType تساوي UNSUPPORTED

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

لا تستنتج القدرات من بادئة معرّف الجهاز.

كيف أعرف إن كان جهاز يدعم عملية معيّنة؟

اقرأ سرد تعريفات نوع الجهاز (بالإنجليزية) وافحص capabilities.supportedOperations.

يجب عرض أو استدعاء العمليات المُدرَجة هناك فقط. على سبيل المثال، لا تعرض نقل بيانات RS485 إلا إذا كانت device.rs485.transceive موجودة.

عملية جهاز لم تكتمل كما هو متوقّع

الاستجابة هي COMMAND_ACCEPTED، لكن الجهاز لم يتحرك

تعني COMMAND_ACCEPTED أن المنصة قبلت الطلب. لا تعني أن الجهاز أكمل العملية.

اعتمد على حالة الأمر: تعني SUCCESS أن الجهاز أكّد العملية؛ وتعني TIMEOUT أن لم يصل أي تأكيد نهائي في الوقت المناسب. استخدم الحصول على نتيجة أمر (بالإنجليزية) لاسترجاع حالة أمر سابق.

الأمر في حالة TIMEOUT. هل من المؤكد أن الجهاز لم ينفّذه؟

ليس بالضرورة. قد لا يكون الجهاز استلم الأمر، أو قد يكون نفّذه بينما تأخّر التأكيد أو فُقد.

لا تكرر الأمر دون تروٍّ. اقرأ حالة الجهاز الحالية أولًا، خصوصًا للعمليات التي لا يُؤمَن تكرارها.

رمز الاستجابة هو COMMAND_REJECTED

تحقّق من أمرَين أولًا:

1. يتضمن تعريف نوع الجهاز العملية المطلوبة.
2. تطابق المعاملات قدرة الجهاز، مثل فهرس مرحّل صالح.

إذا كانا صحيحَين، تحقّق من اتصال الجهاز والمسار الأساسي إليه.

هل يجب أن تستخدم إعادة المحاولة Idempotency-Key جديدًا؟

أعِد استخدام المفتاح الأصلي عند إعادة محاولة نفس عملية العمل بعد فشل شبكة. تتطلب الأجهزة المختلفة، أو الحالات المستهدفة المختلفة، أو عمليات العمل المختلفة مفاتيح مختلفة.

لا تستخدم مفتاحًا ثابتًا واحدًا لجميع الطلبات. راجع سلوك HTTP (بالإنجليزية).

الاتصال الفوري غير مستقر

لا يستطيع WebSocket إنشاء اتصال

تأكّد أن access token صالح، ثم أنشئ wsTicket جديدًا. التذكرة قصيرة المدة وأحادية الاستخدام ويجب ألّا تُخزَّن مؤقتًا أو تُعاد استخدامها.

راجع إنشاء WebSocket Ticket ثم إنشاء الاتصال (كلاهما بالإنجليزية).

كيف يجب أن يتعافى العميل بعد الانقطاع؟

أعِد الاتصال مع تراجع تدريجي (backoff) وأنشئ تذكرة جديدة لكل اتصال جديد. بعد إعادة الاتصال، أعِد تحميل الحالة اللازمة بدلًا من افتراض أن أحداث فترة الانقطاع ستُعاد بشكل كامل.

راجع نبض القلب وإعادة الاتصال (بالإنجليزية).

تصل أحداث مكررة، أو يبدو أن بعضها مفقود

يجب أن تكون معالجة الأحداث تماثلية (idempotent). يُخطر WebSocket العميل بالتغيّرات ويجب ألّا يكون المصدر الدائم الوحيد للحالة.

بعد إعادة تحميل الصفحة، أو إعادة الاتصال، أو اكتشاف فجوة في الحالة، استعلم عن الحالة عبر REST API أو بطلب حالة عبر WebSocket لإرساء خط أساس جديد.

الطلبات محدودة أو الخدمة غير متاحة مؤقتًا

الاستجابة هي HTTP 429

أوقف إعادة المحاولة الفورية. اقرأ Retry-After وأعد المحاولة بعد الوقت المسموح. نسّق التراجع التدريجي بين نسخ خدمتك لتجنّب موجة متزامنة أخرى.

يخضع التحديث الفوري والتحكم في الأجهزة لحدود أكثر صرامة من استعلامات الحالة المتزامنة. راجع حدود التكرار وإعادة المحاولة (بالإنجليزية).

الاستجابة هي 503 أو GATEWAY_UNAVAILABLE

المسار الفوري إلى الجهاز غير متاح مؤقتًا. سجّل requestId وأعد المحاولة عددًا محدودًا من المرات مع تراجع تدريجي.

إذا استمرت الحالة، توقّف عن إعادة المحاولة وجهّز تفاصيل حل المشكلات للدعم.

جهّز تفاصيل حل المشكلات

إذا استمرت المشكلة، اجمع:

المعلومة	مثال أو إرشاد
requestId	معرّف تتبّع الطلب من استجابة API
معرّف API Client	لا تُدرج clientSecret أبدًا
طريقة الطلب ومساره	GET /wlte/v1/devices
الطابع الزمني بتوقيت UTC	الوقت الدقيق لحدوث المشكلة
حالة HTTP وcode الخاص بالعمل	على سبيل المثال، 403 / AUTH_SCOPE_DENIED
المعاملات بعد التنقية	أزِل كلمات المرور، والرموز، والمعلومات الشخصية

ثم أرسل الحالة عبر تواصل مع الدعم.