تخطَّ إلى المحتوى

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

ترسل خدمة التحقق رمزا لمرة واحدة (OTP) إلى رقم هاتف وتتحقق من الرمز الذي يكتبه المستخدم. تولّد SMSFabric الرمز وترسله من هواتفك، ولا تعيده ولا تحفظه أبدا: تُحفظ تجزئة مفتاحية فقط وتُقارن في زمن ثابت. لا تحتاج إلى بناء تخزين للرموز أو انتهاء صلاحيتها أو عد المحاولات بنفسك.

  1. يستدعي خادمك POST /v1/verifications برقم المستخدم، فيعود id لعملية التحقق مع status: "pending".
  2. تصل المستخدم رسالة مثل رمز التحقق الخاص بك هو 482913. ينتهي خلال 10 دقائق. لا تشاركه مع أي شخص.
  3. يكتب المستخدم الرمز في تطبيقك، فيستدعي خادمك POST /v1/verifications/:id/check.
  4. القيمة status: "approved" تعني أن الرمز صحيح، وأي قيمة أخرى تعني أنه غير صحيح.

يحتاج المفتاح إلى verify:send للإرسال وverify:check للتحقق. لا تستدع خدمة التحقق من متصفح أو تطبيق هاتف لأن المفتاح سينكشف، بل من خادمك.

نافذة طرفيّة
curl https://api.smsfabric.com/v1/verifications \
-H "X-Api-Key: $SMSFABRIC_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: signup-usr_8812-otp-1" \
-d '{"to": "+201001234567", "channel": "sms", "locale": "ar"}'
{
"id": "ver_k3j2h1g0f9e8d7c6b5a4z3y2",
"to": "+20******4567",
"status": "pending",
"channel": "sms",
"locale": "ar",
"expiresAt": "2026-11-19T12:10:00.000Z",
"attempts": 0,
"maxAttempts": 5,
"createdAt": "2026-11-19T12:00:00.000Z",
"updatedAt": "2026-11-19T12:00:00.000Z"
}

الحقل to مقنّع دائما: رمز الدولة وآخر 4 أرقام.

الحقل الافتراضي النطاق
to رقم بصيغة E.164. إلزامي.
channel sms. إلزامي في الواجهة البرمجية المباشرة، وتملؤه حزمة SDK تلقائيا.
locale en en أو ar، لغة النص الافتراضي.
codeLength 6 من 4 إلى 10 أرقام.
ttlSeconds 600 من 60 إلى 1800 ثانية.
template نصك الخاص حتى 320 حرفا، يجب أن يحتوي {{code}} ويمكن أن يستخدم {{minutes}}.

الإرسال مرة أخرى إلى الرقم نفسه يلغي عملية التحقق المعلقة السابقة (status: "canceled")، فلا يعمل إلا أحدث رمز.

رسالة SMS نفسها رسالة عادية تحمل metadata.verificationId. كل عرض لها في الواجهة البرمجية، ومنه webhooks، يظهر body: "[verification code hidden]": لا يرى الرمز إلا هاتف المستلم.

نافذة طرفيّة
curl https://api.smsfabric.com/v1/verifications/ver_k3j2h1g0f9e8d7c6b5a4z3y2/check \
-H "X-Api-Key: $SMSFABRIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{"code": "482913"}'
{ "id": "ver_k3j2h1g0f9e8d7c6b5a4z3y2", "status": "pending", "attemptsLeft": 4 }
status المعنى ما تقوله للمستخدم
approved الرمز صحيح. تابع.
pending رمز خاطئ، وبقيت attemptsLeft محاولات. «الرمز غير صحيح. حاول مرة أخرى.»
denied الرمز الخاطئ الخامس. مغلقة. اعرض إرسال رمز جديد.
expired انتهت المدة. مغلقة. اعرض إرسال رمز جديد.
canceled أُرسل رمز أحدث إلى الرقم. مغلقة. اطلب أحدث رمز.

كل تحقق يقارن رمزا يستهلك محاولة. عملية التحقق المغلقة تعيد حالتها دون مقارنة. والتحقق مجددا من عملية approved يعيد 409 verification_already_approved، فلا يُستخدم الرمز مرتين.

لا تعيد حزمة SDK محاولة التحقق تلقائيا أبدا، لأن كل محاولة تُحتسب.

يطلق المحتالون رموز OTP إلى نطاقات أرقام مكلفة ويتقاسمون الرسوم. ترفض خدمة التحقق هذه الإرسالات قبل أن تغادر أي رسالة هواتفك. تُطبق القواعد بهذا الترتيب:

القاعدة الافتراضي الرفض
رقم في القائمة السوداء 422 verify_recipient_blacklisted
دولة غير مسموحة. حتى تحفظ قائمة، الدول المسموحة هي دول أرقام شرائحك. الأرقام غير الجغرافية (+800 و+870 و+881…) غير مسموحة أبدا. دول شرائحك 403 verify_country_not_allowed
نطاق الرقم (الرقم دون آخر 4 أرقام) محظور 403 verify_prefix_blocked
رموز إلى رقم واحد 3 كل 10 دقائق 429 verify_resend_limited مع Retry-After
رموز إلى دولة واحدة 150 في الساعة 429 verify_velocity_exceeded مع Retry-After
رموز المؤسسة 300 في الساعة 429 verify_velocity_exceeded مع Retry-After
أرقام مختلفة في نطاق واحد خلال 10 دقائق 10 403 verify_prefix_blocked، ويُحظر النطاق

غيّر الدول المسموحة والحدود بالساعة من الإعدادات ← التحقق في البوابة (شرح خطوة بخطوة). لا يغيرها إلا مستخدم مسجل الدخول: استدعاء PUT /v1/verify/settings بمفتاح API يعيد 403 api_key_not_allowed، فلا يستطيع مفتاح مسرّب فتح دول جديدة. اقرأ الإعدادات الحالية عبر GET /v1/verify/settings.

كل رفض عدا حد الرقم الواحد يكتب verify.blocked في سجل التدقيق ويرسل webhook verification.blocked. يبقى النطاق المحظور محظورا حتى يرفع دعم SMSFabric الحظر.

الحدث متى
verification.approved تطابق رمز. data هي عملية التحقق.
verification.expired انتهت مدة عملية تحقق معلقة.
verification.blocked رفضت الحماية إرسالا. data.reason إحدى القيم country_not_allowed أو prefix_blocked أو prefix_burst أو country_velocity أو org_velocity.

الاختبار في بيئة الاختبار

Section titled “الاختبار في بيئة الاختبار”

مع مفتاح sf_test_ تعمل الإرسالات والحدود والتحقق كما في الوضع الحقيقي، لكن لا تغادر أي رسالة هاتفا. ولأن الرمز لا يُعاد أبدا، يمكنك اختبار الرمز الخاطئ وانتهاء المدة والحدود في بيئة الاختبار، واختبار الموافقة بمفتاح حقيقي على رقمك.