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

عمليات التحقق

عملية التحقق رمز واحد لمرة واحدة يُرسل إلى رقم واحد. لا يُعاد الرمز ولا يُسجل ولا يُحفظ نصا واضحا أبدا. انظر التحقق من أرقام الهواتف لمسار العمل.

الحقل النوع الوصف
id string ver_…
to string الرقم مقنّعا: رمز الدولة وآخر 4 أرقام (+20******4567).
status string pending أو approved أو denied أو expired أو canceled.
channel string sms.
locale string en أو ar.
expiresAt string وقت توقف الرمز عن العمل.
attempts integer عمليات التحقق التي قارنت رمزا.
maxAttempts integer 5.
createdAt وupdatedAt string الأوقات.
POST/v1/verificationsverify:send

يولّد رمزا ويرسله عبر SMS من هواتفك. يعيد 201 مع عملية التحقق. يدعم Idempotency-Key. تُلغى أي عملية معلقة للرقم نفسه.

حقل المحتوى النوع إلزامي الوصف القيود
to string نعم المستلم. E.164.
channel string نعم قناة الإرسال. sms.
locale string لا لغة النص الافتراضي. en (الافتراضي) أو ar.
codeLength integer لا عدد أرقام الرمز. من 4 إلى 10، والافتراضي 6.
ttlSeconds integer لا مدة صلاحية الرمز. من 60 إلى 1800، والافتراضي 600.
template string لا نصك الخاص. حتى 320 حرفا، يجب أن يحتوي {{code}} ويمكن أن يستخدم {{minutes}}.
نافذة طرفيّة
curl https://api.smsfabric.com/v1/verifications \
-H "X-Api-Key: $SMSFABRIC_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: login-usr_8812-1732014000" \
-d '{"to": "+201001234567", "channel": "sms", "codeLength": 6, "template": "Acme: your login code is {{code}}. It expires in {{minutes}} minutes."}'
{
"id": "ver_k3j2h1g0f9e8d7c6b5a4z3y2",
"to": "+20******4567",
"status": "pending",
"channel": "sms",
"locale": "en",
"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"
}
الخطأ متى
400 validation_failed رقم غير صالح، أو حقل خارج النطاق، أو template دون {{code}}.
422 verify_recipient_blacklisted الرقم في قائمتك السوداء.
403 verify_country_not_allowed دولة الرقم غير مسموحة.
403 verify_prefix_blocked نطاق الرقم محظور.
429 verify_resend_limited 3 رموز إلى هذا الرقم خلال 10 دقائق. تعطي Retry-After مدة الانتظار بالثواني.
429 verify_velocity_exceeded بلغت الحد بالساعة للدولة أو للمؤسسة، مع Retry-After.
POST/v1/verifications/:id/checkverify:check

يقارن الرمز الذي كتبه المستخدم ويعيد 200. كل تحقق يقارن رمزا يستهلك محاولة، والعملية المغلقة تعيد حالتها دون مقارنة.

المسار النوع الوصف
id string معرّف عملية التحقق.
حقل المحتوى النوع إلزامي القيود
code string نعم من 4 إلى 10 أرقام.
نافذة طرفيّة
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": "approved", "attemptsLeft": 0 }

تكون status بالقيمة approved عند التطابق، وpending مع attemptsLeft عند الرمز الخاطئ، وdenied عند الرمز الخاطئ الخامس، وexpired بعد انتهاء المدة. تكون attemptsLeft صفرا ما لم تبق العملية pending.

الخطأ متى
409 verification_already_approved قُبلت العملية من قبل.
404 not_found لا توجد عملية تحقق بهذا المعرّف في مؤسستك.
GET/v1/verifications/:idverify:check

يعيد عملية التحقق. العملية المعلقة التي تجاوزت expiresAt تعود بالحالة expired.

نافذة طرفيّة
curl https://api.smsfabric.com/v1/verifications/ver_k3j2h1g0f9e8d7c6b5a4z3y2 \
-H "X-Api-Key: $SMSFABRIC_API_KEY"
{
"id": "ver_k3j2h1g0f9e8d7c6b5a4z3y2",
"to": "+20******4567",
"status": "approved",
"channel": "sms",
"locale": "en",
"expiresAt": "2026-11-19T12:10:00.000Z",
"attempts": 1,
"maxAttempts": 5,
"createdAt": "2026-11-19T12:00:00.000Z",
"updatedAt": "2026-11-19T12:01:12.480Z"
}
GET/v1/verificationsverify:check

من الأحدث إلى الأقدم، مقسمة إلى صفحات.

الاستعلام النوع الوصف
status string حالة واحدة.
limit integer من 1 إلى 200، والافتراضي 50.
cursor string nextCursor من الصفحة السابقة.
نافذة طرفيّة
curl "https://api.smsfabric.com/v1/verifications?status=pending" \
-H "X-Api-Key: $SMSFABRIC_API_KEY"
{
"data": [
{
"id": "ver_l4k3j2h1g0f9e8d7c6b5a4z3",
"to": "+966*****4567",
"status": "pending",
"channel": "sms",
"locale": "ar",
"expiresAt": "2026-11-19T12:20:00.000Z",
"attempts": 1,
"maxAttempts": 5,
"createdAt": "2026-11-19T12:10:00.000Z",
"updatedAt": "2026-11-19T12:11:04.003Z"
}
],
"nextCursor": null
}
GET/v1/verify/settingsverify:check

يعيد الدول المسموحة وحدود الحماية المعمول بها.

نافذة طرفيّة
curl https://api.smsfabric.com/v1/verify/settings \
-H "X-Api-Key: $SMSFABRIC_API_KEY"
{
"allowedCountries": ["EG", "SA"],
"source": "sim_numbers",
"limits": {
"perNumber": { "limit": 3, "windowSeconds": 600 },
"perCountry": { "limit": 150, "windowSeconds": 3600 },
"perOrg": { "limit": 300, "windowSeconds": 3600 },
"prefixBurst": { "limit": 10, "windowSeconds": 600 },
"maxAttempts": 5
},
"activeBlocks": 0
}

تكون source بالقيمة sim_numbers ما دمت لم تحفظ قائمة (الدول المسموحة هي دول أرقام شرائحك)، وconfigured بعد الحفظ.

PUT/v1/verify/settingssettings:manageللمستخدمين فقط

يستبدل الدول المسموحة، والحدود اختياريا. للمستخدمين المسجلين فقط، كي لا يفتح مفتاح مسرّب دولا جديدة. يُسجل في التدقيق باسم verify.settings_updated. يعيد الشكل نفسه الذي يعيده GET.

حقل المحتوى النوع إلزامي القيود
allowedCountries string[] نعم رموز ISO 3166-1 alpha-2. القائمة الفارغة تمنع الإرسال إلى كل الدول.
orgHourlyLimit integer لا من 1 إلى 1000، والافتراضي 300.
countryHourlyLimit integer لا من 1 إلى 1000، والافتراضي 150.
prefixBurstThreshold integer لا من 3 إلى 50، والافتراضي 10.
نافذة طرفيّة
curl -X PUT https://api.smsfabric.com/v1/verify/settings \
-H "Authorization: Bearer $SMSFABRIC_USER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"allowedCountries": ["EG", "SA", "AE"], "countryHourlyLimit": 200}'
الخطأ متى
403 api_key_not_allowed استُدعي بمفتاح API.