إرسال رمز تحقق
ينشئ محاولة user_verification جديدة، يلغي أي رمز نشط سابق لنفس الرقم، ويرسل رمزاً مولَّداً. لا تستخدم messages/send إذا كنت تحتاج دورة تحقق كاملة.
متى تستخدمه. تسجيل دخول، تأكيد رقم، أو أي OTP تريد التحقق منه لاحقاً عبر API.
مثال الطلب
مثال صحيح: إرسال OTP عبر SMS دولي
curl --location 'https://raselsms.com/api/v2/verification/send' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"to":"+963912345678","channel":"int_sms"}'مثال خاطئ: خطأ: قناة عامة مرفوضة
curl --location 'https://raselsms.com/api/v2/verification/send' \--header 'X-API-Key: YOUR_API_KEY' \--header 'Content-Type: application/json' \--data '{"to":"+963912345678","channel":"sms"}'قيم مثل sms أو whatsapp أو auto وحدها تُرفض.
مثال الاستجابة
200 — إرسال OTP عبر SMS دولي
{ "verificationId": "6800abc123def4567890fedc", "status": "sent", "channel": "int_sms", "expiresAt": "2026-09-05T10:10:00.000Z", "resendAvailableAt": "2026-09-05T10:01:00.000Z", "resendCount": 0}400 — خطأ: قناة عامة مرفوضة
{ "success": false, "code": "VALIDATION_ERROR", "error": "Unsupported verification channel"}قيم مثل sms أو whatsapp أو auto وحدها تُرفض.
401 — مفتاح API مفقود أو غير صالح.
{ "success": false, "requestId": "msgreq_1739012345678_abc123", "code": "UNAUTHORIZED", "error": "Missing or invalid API key"}403 — الهاتف غير موثّق أو الصلاحية غير كافية (غالباً messages:create أو api_keys:read).
{ "success": false, "requestId": "msgreq_1739012345678_abc123", "code": "FORBIDDEN", "error": "Phone not verified or missing permission"}429 — تم تجاوز حد الطلبات. انتظر Retry-After إن وُجد.
{ "success": false, "requestId": "msgreq_1739012345678_abc123", "code": "RATE_LIMITED", "error": "Rate limit exceeded", "retryAfterSeconds": 30}طلب HTTP
POST /api/v2/verification/send
ترويسات الطلب
| الترويسة | النوع | الوصف |
|---|---|---|
| X-API-Key | string | مفتاح Rasel API. أرسله في كل طلب موثّق ما عدا الويب هوك الوارد. * |
| Idempotency-Key | string | مفتاح اختياري فريد لإعادة المحاولة الآمنة. يتقدّم على idempotencyKey في الجسم. يمكن إعادة نفس الاستجابة لمدة 24 ساعة عند تفعيل خاصية Idempotency. |
جسم الطلب
| الحقل | النوع | الوصف | مثال |
|---|---|---|---|
| to | string | المستلم: رقم دولي E.164، أو بريد عندما تكون القناة email، أو معرّف مجموعة واتساب، أو معرّف محادثة تلغرام، أو مصفوفة نصوص حتى 100 مستلم للدفعة الرسمية. * | |
| channel | enum | قناة التسليم. في الإرسال الموحّد فضّل auto أو local_sms أو int_sms أو official_whatsapp أو جلسات واتساب ويب أو telegram_bot أو email_user. في التحقق احذف الحقل للاختيار التلقائي، ولا ترسل sms أو whatsapp أو auto وحدها. | |
| senderId | string | معرّف مرسل SMS معتمد. إن حُذف يُستخدم الافتراضي ثم مرسل المنصة. | |
| officialSenderId | string | معرّف مرسل واتساب الرسمي من /api/v2/official-senders. مرادف sender.officialId. استخدم platform لرقم ميتا الافتراضي عند قائمة القوالب. | |
| sender | object | تجاوز اختياري للمرسل. إن حُذف يستخدم راسل المرسل المعتمد الافتراضي ثم مرسل المنصة. | |
| sender.id | string | معرّف مرسل SMS المعتمد. احذفه لاستخدام المرسل الافتراضي. | |
| sender.officialId | string | معرّف مرسل واتساب الرسمي. نفس officialSenderId. | |
| idempotencyKey | string | بديل اختياري في الجسم لترويسة Idempotency-Key. فضّل الترويسة. |
حقول الاستجابة
| الحقل | النوع | الوصف | مثال |
|---|---|---|---|
| verificationId | string | المعرّف الراجع من خطوة إرسال التحقق. فضّله في إعادة الإرسال والتحقق. | |
| status | enum | حالة التسليم أو السجل. في الإرسال: sent أو queued أو scheduled. في الموارد الأخرى هي فلتر الحالة أو قيمتها. | |
| channel | string | قناة التسليم. في الإرسال الموحّد فضّل auto أو local_sms أو int_sms أو official_whatsapp أو جلسات واتساب ويب أو telegram_bot أو email_user. في التحقق احذف الحقل للاختيار التلقائي، ولا ترسل sms أو whatsapp أو auto وحدها. | |
| channels | string-list | أسماء القنوات العامة عندما ينجح التوزيع على أكثر من قناة متوافقة. | |
| deliveries | json | تتبع لكل قناة عند تفعيل التوزيع. | |
| expiresAt | string | وقت انتهاء رمز التحقق الحالي. | |
| resendAvailableAt | string | أقرب وقت يُسمح فيه بإعادة الإرسال. | |
| resendCount | number | عدد مرات إعادة إرسال الرمز. |
رموز الحالة
| الحالة | الوصف |
|---|---|
| 200 | نجاح. |
| 400 | طلب غير صالح، أو خطأ تحقق، أو المورد لا يمكن استخدامه في هذه الحالة. |
| 401 | مفتاح API مفقود أو غير صالح. |
| 403 | الهاتف غير موثّق، أو الصلاحية ناقصة، أو الحساب لا يستطيع تنفيذ هذا الإجراء. |
| 409 | تعارض، مثل إعادة استخدام مفتاح Idempotency بجسم مختلف، أو جلسة غير جاهزة. |
| 429 | تم تجاوز حد المعدل، أو وصل عدد محاولات التحقق إلى الحد الأقصى. |
| 402 | رصيد المحفظة أو حصة الباقة لا يكفي. |
جرّب الطلب
قد يخصم هذا الطلب من رصيد المحفظة أو حصة الباقة.
لست مسجلاً، أو رفض الخادم هذه الجلسة. القوائم تبقى فارغة إلى أن تسجّل الدخول أو تكتب مفتاحاً صالحاً، ولن يظهر حساب شخص آخر.
المتغيرات
مفتاح اختياري فريد لإعادة المحاولة الآمنة. يتقدّم على idempotencyKey في الجسم. يمكن إعادة نفس الاستجابة لمدة 24 ساعة عند تفعيل خاصية Idempotency.
قناة التسليم. في الإرسال الموحّد فضّل auto أو local_sms أو int_sms أو official_whatsapp أو جلسات واتساب ويب أو telegram_bot أو email_user. في التحقق احذف الحقل للاختيار التلقائي، ولا ترسل sms أو whatsapp أو auto وحدها.
المستلم: رقم دولي E.164، أو بريد عندما تكون القناة email، أو معرّف مجموعة واتساب، أو معرّف محادثة تلغرام، أو مصفوفة نصوص حتى 100 مستلم للدفعة الرسمية.
معرّف مرسل واتساب الرسمي من /api/v2/official-senders. مرادف sender.officialId. استخدم platform لرقم ميتا الافتراضي عند قائمة القوالب.
معرّف مرسل SMS معتمد. إن حُذف يُستخدم الافتراضي ثم مرسل المنصة.
بديل اختياري في الجسم لترويسة Idempotency-Key. فضّل الترويسة.
الطلب
{}الاستجابة
نفّذ طلباً لعرض الاستجابة.