عمليات التحقق
عملية التحقق رمز واحد لمرة واحدة يُرسل إلى رقم واحد. لا يُعاد الرمز ولا يُسجل ولا يُحفظ نصا واضحا أبدا. انظر التحقق من أرقام الهواتف لمسار العمل.
كائن عملية التحقق
Section titled “كائن عملية التحقق”| الحقل | النوع | الوصف |
|---|---|---|
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 | الأوقات. |
إرسال رمز
Section titled “إرسال رمز”/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. |
التحقق من رمز
Section titled “التحقق من رمز”/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 |
لا توجد عملية تحقق بهذا المعرّف في مؤسستك. |
قراءة عملية تحقق
Section titled “قراءة عملية تحقق”/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"}عرض عمليات التحقق
Section titled “عرض عمليات التحقق”/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}قراءة إعدادات التحقق
Section titled “قراءة إعدادات التحقق”/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 بعد الحفظ.
تحديث إعدادات التحقق
Section titled “تحديث إعدادات التحقق”/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. |