اتبع هذه الإرشادات لضمان تكامل آمن وموثوق ومتوافق مع واجهتنا البرمجية للرسائل. يغطي هذا الدليل كل شيء من الأمان إلى الامتثال، لتطبيقات جاهزة للإنتاج.

1. استخدم HTTPS و POST في كل الطلبات دائماً

لماذا:
يشفّر HTTPS البيانات أثناء نقلها، فيحميها من التنصت والتلاعب وهجمات الوسيط. واستخدام أسلوب POST يضمن تمرير البيانات الحساسة (مثل بيانات الدخول) داخل جسم الطلب لا في الرابط، حيث قد تُسجَّل أو تُخزَّن بنص واضح.

ما الذي تفعله:

  • استخدم https:// لكل نقاط الوصول
  • أرسل كل الطلبات بأسلوب POST
  • لا تضع بيانات الدخول في نص الرابط أبداً
❌ لا تفعل هذا: 
https://www.kwtsms.com/API/send/?username=USER&password=PASS&mobile=965XXXXXXXX&message=Hello
✅ افعل هذا: 
curl -X POST https://www.kwtsms.com/API/send/ \
  -d username=USER \
  -d password=PASS \
  -d sender=YOURSENDERID \
  -d mobile=965XXXXXXXX \
  -d lang=1 \
  -d "message=Your verification code is 123456"

2. لا تضع بيانات الدخول داخل الكود أبداً

لماذا:
بيانات الدخول المكتوبة داخل الكود خطر أمني، ويصعب تغييرها، وقد تنكشف في أنظمة إدارة الإصدارات. كما أنها تمنع تحديث كلمة المرور دون تعديل الكود.

ما الذي تفعله:

  • احفظ بيانات الدخول في متغيرات بيئة أو ملفات إعداد أو خدمة آمنة لإدارة الأسرار
  • تأكد أن تطبيقك يسمح بتحديث كلمة المرور دون إعادة نشر

3. تحقق من كل المدخلات ونظّفها

أرقام الهواتف

  • أرسل الأرقام بالصيغة الدولية بلا علامة زائد وبلا أصفار بادئة. الرقم الكويتي هو 965 يتبعه 8 أرقام، مثل 96512345678
  • احذف + أو 00 قبل رمز الدولة
  • اقبل الأرقام الإنجليزية فقط (0-9). الأرقام العربية أو الهندية سترفَض
  • تحقق من الطول والبنية حسب كل دولة قبل الإرسال

محتوى الرسالة

  • احذف الإيموجي غير المدعوم والرموز الخاصة والمحارف غير UTF-8 ما لم تكن مسموحة صراحةً
  • للمحتوى العربي أو اليونيكود، تأكد من الترميز الصحيح (UTF-8) واختبره قبل التسليم

4. اختبر الرسائل بالعربية والإنجليزية قبل النشر

استخدم test=1 أثناء التطوير. إضافة test=1 إلى الطلب تشغّل المسار كاملاً، من تحقق وتوجيه وفحص اسم المرسل ورد، دون تسليم الرسالة ودون خصم رصيد. طوّر وصحّح عليه، ثم احذفه في الإنتاج.

لماذا:
مشاكل الترميز قد تجعل الرسالة تصل كطلاسم. واختبار اللغتين يضمن أن ترميزك ومعالجتك للمحارف تعمل كما يجب.

ما الذي تفعله:

  • أرسل رسائل اختبارية بالعربية والإنجليزية أثناء التطوير
  • تحقق من الوصول ومن وضوح النص على أجهزة حقيقية

5. اتبع أفضل الممارسات في رموز التحقق (OTP)

استخدم اسم مرسل خدمي خاص

لتوصيل أسرع وأكثر موثوقية لرموز التحقق، استخدم دائماً اسم مرسل خدمي مخصص بدل اسم تسويقي أو تجريبي.

اذكر اسم تطبيقك أو شركتك

امتثالاً لأنظمة الاتصالات ولتعزيز الثقة، اذكر اسم تطبيقك أو شركتك داخل رسالة رمز التحقق.

✅ مثال: 
Your verification code for MyApp is 123456.

اضبط مدة معقولة لإعادة الإرسال

  • اسمح بـ 3 إلى 4 دقائق على الأقل قبل السماح بإعادة إرسال الرمز
  • هذا يمنح المستخدم وقتاً لاستلام الرمز وإيجاده وإدخاله
  • وافق الممارسات الشائعة (مثلاً KNET يستخدم صلاحية 4 دقائق)

6. امنع الأتمتة وإساءة الاستخدام

استخدم CAPTCHA أو ما يماثلها

أضف CAPTCHA أو كشفاً صامتاً للبوتات في نماذج طلب رمز التحقق والتسجيل، لمنع الهجمات الآلية.

طبّق تحديد المعدل

  • حُدّ طلبات رمز التحقق لكل رقم في الساعة (مثلاً 3 إلى 5 محاولات كحد أقصى)
  • قيّد التسجيلات أو عمليات الإرسال حسب عنوان IP خلال نافذة زمنية متحركة
  • هذا يحمي رصيدك من الاستنزاف ويمنع إساءة استخدام الخدمة

7. حسّن استخدامك للواجهة البرمجية

تجنّب طلبات الرصيد غير الضرورية

بعد أي إرسال ناجح، يعطيك رد الواجهة الرقمين معاً أصلاً:

  • points-charged، أي كم كلفت هذه الرسالة
  • balance-after، أي ما تبقى في الحساب

وفي الرد النصي هما الحقلان الرابع والخامس من OK:msgid:count:points-charged:balance-after:submitTime. فلا حاجة لاستدعاء https://www.kwtsms.com/API/balance/ بعد كل إرسال. استدعِه بجدول زمني إن أردت، وفعّل تنبيه انخفاض الرصيد في حسابك بدل ذلك.

عالج الردود والأخطاء

  • طبّق معالجة سليمة لأخطاء حالات HTTP وأخطاء الواجهة نفسها (مثل نفاد الرصيد أو رقم غير صالح أو رفض المحتوى)
  • سجّل الأخطاء للتشخيص، لكن لا تكشف تفاصيل حساسة في الرسائل الظاهرة للمستخدم

8. اضمن الامتثال والأمان

سجّل بأمان

تجنّب تسجيل الطلبات أو الردود كاملة إن كانت تحوي بيانات دخول أو أرقام هواتف أو نص الرسائل. وإن كان التسجيل ضرورياً فأخفِ البيانات الحساسة.

حدّث المكتبات وحزم التطوير

إن كنت تستخدم حزمة تطوير رسمية فأبقها محدّثة للاستفادة من الترقيعات الأمنية وتحسينات الأداء.

راجع أنظمة الاتصالات

ابقَ مطلعاً على الأنظمة المحلية المتعلقة بأسماء المرسلين ومحتوى الرسائل وموافقة المستخدم، خصوصاً في الرسائل التسويقية.

9. راقب ونبّه

  • اضبط تنبيهات لحالات الإرسال الفاشل، أو الارتفاع المفاجئ في الأخطاء، أو حدود الرصيد
  • راقب معدلات الوصول وزمن الاستجابة لاكتشاف المشاكل مبكراً

10. استراتيجية الاختبار

قائمة الاختبار:

  • اختبارات وحدة للتحقق من أرقام الهواتف وتنظيفها
  • اختبارات تكامل مع الواجهة البرمجية (ببيانات دخول تجريبية)
  • اختبار بمجموعات محارف مختلفة (إنجليزي، عربي، رموز خاصة)
  • اختبار بمدخلات غير صالحة (أرقام مشوهة، رسائل فارغة)
  • اختبار تحديد المعدل وآليات منع البوتات
  • التحقق من صلاحية رمز التحقق ومن إعادة إرساله
  • اختبار سيناريوهات الأخطاء (انقطاع الشبكة، بيانات دخول خاطئة)

* إن كنت صاحب تطبيق فيمكنك استخدام طريقة اختبار الواجهة البرمجية لاكتشاف مشاكل التنفيذ وإصلاحها، وهو ما يوفر عليك وقتاً ومالاً.

قائمة المراجعة قبل الإطلاق

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