التحقق من أرقام الهواتف
ترسل خدمة التحقق رمزا لمرة واحدة (OTP) إلى رقم هاتف وتتحقق من الرمز الذي يكتبه المستخدم. تولّد SMSFabric الرمز وترسله من هواتفك، ولا تعيده ولا تحفظه أبدا: تُحفظ تجزئة مفتاحية فقط وتُقارن في زمن ثابت. لا تحتاج إلى بناء تخزين للرموز أو انتهاء صلاحيتها أو عد المحاولات بنفسك.
مسار العمل
Section titled “مسار العمل”- يستدعي خادمك
POST /v1/verificationsبرقم المستخدم، فيعودidلعملية التحقق معstatus: "pending". - تصل المستخدم رسالة مثل
رمز التحقق الخاص بك هو 482913. ينتهي خلال 10 دقائق. لا تشاركه مع أي شخص. - يكتب المستخدم الرمز في تطبيقك، فيستدعي خادمك
POST /v1/verifications/:id/check. - القيمة
status: "approved"تعني أن الرمز صحيح، وأي قيمة أخرى تعني أنه غير صحيح.
يحتاج المفتاح إلى verify:send للإرسال وverify:check للتحقق. لا تستدع خدمة التحقق من متصفح أو تطبيق هاتف لأن المفتاح سينكشف، بل من خادمك.
إرسال رمز
Section titled “إرسال رمز”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"}'import { SMSFabric } from '@smsfabric/sdk';
const sf = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const verification = await sf.verifications.send( { to: '+201001234567', locale: 'ar' }, { idempotencyKey: 'signup-usr_8812-otp-1' },);// Keep verification.id with the user's session. The code never comes back.console.log(verification.id, verification.status, verification.expiresAt);import osimport requests
res = requests.post( "https://api.smsfabric.com/v1/verifications", headers={"X-Api-Key": os.environ["SMSFABRIC_API_KEY"], "Idempotency-Key": "signup-usr_8812-otp-1"}, json={"to": "+201001234567", "channel": "sms", "locale": "ar"}, timeout=30,)res.raise_for_status()verification = res.json()print(verification["id"], verification["status"])<?php$ch = curl_init('https://api.smsfabric.com/v1/verifications');curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode(['to' => '+201001234567', 'channel' => 'sms', 'locale' => 'ar']), CURLOPT_HTTPHEADER => [ 'X-Api-Key: ' . getenv('SMSFABRIC_API_KEY'), 'Content-Type: application/json', 'Idempotency-Key: signup-usr_8812-otp-1', ], CURLOPT_RETURNTRANSFER => true,]);$verification = json_decode(curl_exec($ch), true);echo $verification['id'] . ' ' . $verification['status'] . "\n";{ "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]": لا يرى الرمز إلا هاتف المستلم.
التحقق من الرمز
Section titled “التحقق من الرمز”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"}'import { SMSFabric } from '@smsfabric/sdk';
const sf = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const result = await sf.verifications.check('ver_k3j2h1g0f9e8d7c6b5a4z3y2', '482913');if (result.status === 'approved') { // Mark the number as verified.} else if (result.status === 'pending') { console.log(`Wrong code. ${result.attemptsLeft} attempts left.`);} else { console.log(`Verification is ${result.status}. Send a new code.`);}import osimport requests
res = requests.post( "https://api.smsfabric.com/v1/verifications/ver_k3j2h1g0f9e8d7c6b5a4z3y2/check", headers={"X-Api-Key": os.environ["SMSFABRIC_API_KEY"]}, json={"code": "482913"}, timeout=30,)res.raise_for_status()result = res.json()print(result["status"], result["attemptsLeft"])<?php$ch = curl_init('https://api.smsfabric.com/v1/verifications/ver_k3j2h1g0f9e8d7c6b5a4z3y2/check');curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode(['code' => '482913']), CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('SMSFABRIC_API_KEY'), 'Content-Type: application/json'], CURLOPT_RETURNTRANSFER => true,]);$result = json_decode(curl_exec($ch), true);echo $result['status'] . ' ' . $result['attemptsLeft'] . "\n";{ "id": "ver_k3j2h1g0f9e8d7c6b5a4z3y2", "status": "pending", "attemptsLeft": 4 }status |
المعنى | ما تقوله للمستخدم |
|---|---|---|
approved |
الرمز صحيح. | تابع. |
pending |
رمز خاطئ، وبقيت attemptsLeft محاولات. |
«الرمز غير صحيح. حاول مرة أخرى.» |
denied |
الرمز الخاطئ الخامس. مغلقة. | اعرض إرسال رمز جديد. |
expired |
انتهت المدة. مغلقة. | اعرض إرسال رمز جديد. |
canceled |
أُرسل رمز أحدث إلى الرقم. مغلقة. | اطلب أحدث رمز. |
كل تحقق يقارن رمزا يستهلك محاولة. عملية التحقق المغلقة تعيد حالتها دون مقارنة. والتحقق مجددا من عملية approved يعيد 409 verification_already_approved، فلا يُستخدم الرمز مرتين.
لا تعيد حزمة SDK محاولة التحقق تلقائيا أبدا، لأن كل محاولة تُحتسب.
الحماية من SMS pumping
Section titled “الحماية من SMS pumping”يطلق المحتالون رموز 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 الحظر.
Webhooks
Section titled “Webhooks”| الحدث | متى |
|---|---|
verification.approved |
تطابق رمز. data هي عملية التحقق. |
verification.expired |
انتهت مدة عملية تحقق معلقة. |
verification.blocked |
رفضت الحماية إرسالا. data.reason إحدى القيم country_not_allowed أو prefix_blocked أو prefix_burst أو country_velocity أو org_velocity. |
الاختبار في بيئة الاختبار
Section titled “الاختبار في بيئة الاختبار”مع مفتاح sf_test_ تعمل الإرسالات والحدود والتحقق كما في الوضع الحقيقي، لكن لا تغادر أي رسالة هاتفا. ولأن الرمز لا يُعاد أبدا، يمكنك اختبار الرمز الخاطئ وانتهاء المدة والحدود في بيئة الاختبار، واختبار الموافقة بمفتاح حقيقي على رقمك.