دليل البدء

اشترك في خطة

قبل إرسال أي رسائل OTP، عليك الاشتراك في خطة.

الخطوات:

1. انتقل إلى قسم "الاشتراكات" في لوحة التحكم، ثم اضغط على "شراء خطة".
2. اختر خطة من الخطط المتاحة، ثم اضغط على "اشترك".
3. الدفع التلقائي غير متاح حالياً. اضغط على "تأكيد الطلب"، وأضف ملاحظات اختيارية إن لزم، وسيتواصل معك فريقنا عبر واتساب أو البريد الإلكتروني لتفعيل خطتك.

إرسال رسائل OTP

الخطوات:

1. انتقل إلى قسم "API Keys" في لوحة التحكم وأضف مفتاح API جديداً. تأكّد من تخزين المفتاح بشكل آمن وعدم مشاركته مع أي شخص خارج فريقك.
2. نادِ Endpoint إرسال الرسائل مع تمرير رمز OTP ورقم هاتف المستلم.
3. احتفظ بقيمة id المُعادة لتتمكن لاحقاً من الاستعلام عن حالة التسليم عبر Endpoint التحقق من حالة الرسالة.

Endpoint

المصادقة

يجب أن يتضمن كل طلب مفتاح API الخاص بك في Header الطلب X-Api-Key. تُصدَر مفاتيح API لكل client من لوحة تحكم LightOTP وقد تُمنَح تاريخ انتهاء صلاحية اختياري. تُرفَض الطلبات التي تحوي مفتاحاً مفقوداً أو غير صالح أو منتهي الصلاحية قبل أن يُستهلَك أي رصيد.

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

Headers

Body

{
  "otpCode": "123456",
  "toPhoneE164": "+966551234567",
  "languageCode": "en",
  "idempotencyKey": "a3f1c2e4-9b27-4d6a-8e5f-1c2b3d4e5f60"
}

otpCode — قواعد التحقق الكاملة

1. يجب أن يكون مضمّناً ضمن الطلب.
2. أن يكون الطول ≤ 8 محارف.
3. أن يكون كل محرف حرفاً أو رقماً. الواصلات والفراغات والنقاط وعلامات الترقيم الأخرى مرفوضة.

toPhoneE164 — صيغة رقم الهاتف

يجب أن يكون الرقم رقماً صالحاً ضمن منطقته؛ ولا يكفي أن يكون مكتوباً بشكل جيّد (مثلاً يبدأ بـ + ويملك عدد الخانات المناسب).

languageCode — اختيار اللغة

إذا أرسلت قيمة languageCode، تُرسَل الرسالة بهذه اللغة. وإن لم تتوفر لغة مطابقة، تعود المنصّة إلى اللغة الافتراضية لحسابك.

idempotencyKey — إعادة المحاولة الآمنة

حين تُرسل قيمة idempotencyKey، تخزّنها المنصّة مع الرسالة التي تُنشئها. وإذا استدعيت Endpoint نفسه لاحقاً بنفس قيمة idempotencyKey وبنفس مفتاح API، فلن تُرسَل رسالة جديدة ولن يُخصم من رصيدك مرّة أخرى — بل تُعيد المنصّة الاستجابة الأصلية، أي نفس قيمة id ونفس messageStatus اللذين أعادتهما المرّة الأولى. هذا يجعل من الآمن إعادة المحاولة عند عدم استلام الاستجابة (انتهاء المهلة، انقطاع الاتصال، أعطال الشبكة المؤقتة) دون المخاطرة بإرسال مكرّر. وإذا كانت الاستجابة المُعادة تحمل messageStatus بقيمة Failed، فهذا يعني أن الرسالة الأصلية لم تصل، وإعادة المحاولة بنفس idempotencyKey ستُعيد فقط نتيجة الفشل ذاتها؛ ولإرسال الـ OTP فعلياً في هذه الحالة، عليك توليد قيمة idempotencyKey جديدة وإعادة الطلب. ويجب أن تكون كل قيمة idempotencyKey فريدة بين جميع طلباتك السابقة؛ فبمجرّد استخدامها تبقى مرتبطة بتلك الرسالة وحدها ولا يمكن إعادة استخدامها لرسالة مختلفة. ويمكنك حذف الحقل إن لم تكن بحاجة إلى هذه الضمانة — فالمنصّة تقبل الطلب بدونه.

استجابة النجاح — 200 OK

{
  "id": "f5b2d2e9-2c1f-4f1d-9c89-2c41f3d9a4e2",
  "messageStatus": "Sent"
}

دورة حياة messageStatus

استخدم Check Message Status لقراءة آخر حالة للرسالة.

الأخطاء

تُعاد جميع الأخطاء بصيغة JSON على الشكل:

{
  "errorMessage": "InsufficientBalance"
}

رموز الخطأ

الفوترة والرصيد

كل إرسال ناجح يخصم وحدة أو أكثر من رصيد أحدث اشتراك فعّال لديك يحوي رصيداً كافياً.

• الكلفة الافتراضية: 1 رصيد لكل رسالة.
• يتم خصم الرصيد حسب الدولة المرسل إليها وفق جدول الأسعار الدولية. الدول غير المدرجة في الجدول تُخصم بالكلفة الافتراضية: 1 رصيد لكل رسالة.
• الرسائل الفاشلة لا تخصم من رصيدك، لكنها تبقى مسجلة لأغراض التتبع.
• عندما ينتهي رصيد اشتراكك بالكامل، يُعلَّم تلقائياً كمنتهي الصلاحية.
• نرسل لك بريداً إلكترونياً عندما يقترب رصيد اشتراكك من النفاد.

حماية الإرسال المكرّر

لتجنب إرسال نفس الـ OTP إلى المستلم نفسه مرات متكررة، تطبّق المنصّة فترة انتظار لكل رقم هاتف، تزداد كلما زادت إعادة الإرسال إلى الرقم نفسه:

• فترة الانتظار الأولية: 30 ثانية بعد كل إرسال ناجح.
• كل إرسال إضافي ضمن النافذة المتجدّدة لمدة 6 ساعات يُضاعف فترة الانتظار: الإرسال رقم 1 ← 30ث، رقم 2 ← 60ث، رقم 3 ← 120ث، رقم 4 ← 240ث، وهكذا.
• تُحدّ فترة الانتظار بحد أقصى 6 ساعات.
• تُعاد فترة الانتظار إلى الصفر بعد مرور 6 ساعات دون إرسال غير فاشل إلى الرقم نفسه.
• الرسائل الفاشلة لا تُحسب ضمن فترة الانتظار.

خلال فترة الانتظار، تُعيد الواجهة 400 Bad Request مع errorMessage بالشكل: "You can't send another message to the same number yet. Please wait HH:mm:ss and try again."

حدود الطلبات

تطبّق المنصّة حدوداً على عدد الطلبات لكل IP لمنع الاستخدام المفرط. عند تجاوز الحد، تُعيد الواجهة 429 Too Many Requests.

مثال (cURL)

curl -X POST "https://api.lightotp.com/SendMessage" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Accept-Language: en" \
  -d '{
    "otpCode": "482913",
    "toPhoneE164": "+966551234567",
    "languageCode": "en",
    "idempotencyKey": "a3f1c2e4-9b27-4d6a-8e5f-1c2b3d4e5f60"
  }'

التحقق من حالة الرسالة

بعد إرسال ناجح، استخدم هذا الـ Endpoint لقراءة آخر حالة لرسالة (بما في ذلك تفاصيل الفشل إن فشلت).

Body

{
  "id": "f5b2d2e9-2c1f-4f1d-9c89-2c41f3d9a4e2"
}

استجابة النجاح — 200 OK

{
  "id": "f5b2d2e9-2c1f-4f1d-9c89-2c41f3d9a4e2",
  "messageStatus": "Delivered",
  "toPhoneE164": "+966551234567",
  "createdAt": "2026-05-14T09:13:42.812Z",
  "failureCode": null,
  "failureTitle": null,
  "failureReason": null,
  "failedAt": null
}

حقول الفشل

عند فشل الرسالة، تُملأ حقول الفشل:

الأخطاء

مثال (cURL)

curl -X POST "https://api.lightotp.com/CheckMessageStatus" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{ "id": "f5b2d2e9-2c1f-4f1d-9c89-2c41f3d9a4e2" }'

جرّبها بنفسك

انتقل إلى لوحة التحكم لإنشاء مفتاح API وإرسال أول رسالة OTP، أو تواصل معنا إذا احتجت مساعدة في البدء.