التحقق
sms.verifications هو خدمة Verify: تولّد SMSFabric رمزًا لمرة واحدة وترسله عبر هواتفك ثم تفحص ما يكتبه المستخدم. لا يعود الرمز أبدًا من الواجهة البرمجية؛ وحده المستلم يراه. الإرسال يحتاج إلى النطاق verify:send، وكل ما عداه يحتاج إلى verify:check. المسار الكامل في دليل التحقق.
| الدالة | طلب HTTP | القيمة المعادة |
|---|---|---|
send(params, options?) |
POST /v1/verifications |
Verification |
check(id, code) |
POST /v1/verifications/:id/check |
VerificationCheck |
get(id) |
GET /v1/verifications/:id |
Verification |
list(params?) |
GET /v1/verifications |
Paginated<Verification> |
listAll(params?) |
GET /v1/verifications (كل الصفحات) |
AsyncGenerator<Verification> |
settings.get() |
GET /v1/verify/settings |
VerifySettings |
settings.update(params) |
PUT /v1/verify/settings |
VerifySettings |
ترسل رمزًا إلى رقم واحد بصيغة E.164. الإرسال الجديد إلى رقم له رمز معلق يلغي الرمز القديم.
| المعامل | النوع | ملاحظات |
|---|---|---|
to |
string |
المستلم بصيغة E.164. |
channel |
'sms' |
القيمة الافتراضية والوحيدة: sms. |
locale |
'en' | 'ar' |
لغة النص الافتراضي. الافتراضية en. |
codeLength |
number |
من 4 إلى 10 أرقام. الافتراضي 6. |
ttlSeconds |
number |
من 60 إلى 1,800. الافتراضي 600. |
template |
string |
نصك الخاص، حتى 320 حرفًا. يجب أن يحتوي على {{code}} ويمكن أن يستخدم {{minutes}}. |
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const verification = await sms.verifications.send({ to: '+201001234567', locale: 'ar', codeLength: 6, ttlSeconds: 300,});
// Keep the id with the sign-in attempt; `to` comes back masked: +20******4567console.log(verification.id, verification.to, verification.expiresAt);تعاد محاولة أخطاء الشبكة و5xx بمفتاح منع التكرار نفسه. أما 429 فلا تعاد: verify_resend_limited (ثلاثة رموز لكل رقم كل 10 دقائق) وverify_velocity_exceeded يحملان ترويسة Retry-After بالثواني، وعليك أن تعرضها للمستخدم؛ ويضعها SDK في الخطأ باسم err.retryAfter (راجع الأخطاء). حالات الرفض الأخرى هي 403 verify_country_not_allowed و403 verify_prefix_blocked و422 verify_recipient_blacklisted؛ راجع دليل التحقق.
تفحص الرمز الذي كتبه المستخدم. قيمة status في النتيجة:
status |
المعنى |
|---|---|
approved |
الرمز مطابق، وتم التحقق من الرقم. |
pending |
رمز خاطئ، وتبقى attemptsLeft محاولة. |
denied |
الرمز الخاطئ الخامس. أرسل رمزًا جديدًا. |
expired |
انتهت مدة الصلاحية. أرسل رمزًا جديدًا. |
canceled |
استبدل برمز أحدث. |
التحقق الذي سبق اعتماده يعيد 409 verification_already_approved. ولا تعاد محاولة check تلقائيًا أبدًا، لأن كل فحص يقيّم رمزًا يستهلك محاولة.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const result = await sms.verifications.check('ver_…', '482913');
if (result.status === 'approved') console.log('Verified');else if (result.status === 'pending') console.log(`Wrong code, ${result.attemptsLeft} tries left`);else console.log(`Code ${result.status}: send a new one`);عملية تحقق واحدة مع attempts وmaxAttempts والرقم مخفيًا جزئيًا.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const v = await sms.verifications.get('ver_…');console.log(v.status, `${v.attempts}/${v.maxAttempts}`, v.expiresAt);صفحة واحدة من عمليات التحقق، الأحدث أولًا. صفّ حسب status، وتنقل بين الصفحات بـ limit وcursor.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const page = await sms.verifications.list({ status: 'denied', limit: 20 });for (const v of page.data) console.log(v.createdAt, v.to);listAll
Section titled “listAll”كل عمليات التحقق المطابقة، مع تتبع المؤشرات.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
let total = 0;let approved = 0;for await (const v of sms.verifications.listAll({ limit: 200 })) { total += 1; if (v.status === 'approved') approved += 1;}console.log(`${approved} of ${total} approved`);settings.get
Section titled “settings.get”إعدادات الحماية من استنزاف الرسائل المطبقة حاليًا: الدول المسموح بإرسال الرموز إليها (allowedCountries)، وهل حفظتَ القائمة بنفسك (configured) أم اشتقت من أرقام شرائحك (sim_numbers)، وكل حد، وعدد حظر النطاقات النشط. تحتاج إلى verify:check.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const settings = await sms.verifications.settings.get();console.log(settings.allowedCountries, settings.source);console.log('Per number:', settings.limits.perNumber.limit, 'per', settings.limits.perNumber.windowSeconds, 's');settings.update
Section titled “settings.update”تستبدل الدول المسموح بها، واختياريًا الحدود: orgHourlyLimit وcountryHourlyLimit (من 1 إلى 1,000 إرسال في الساعة) وprefixBurstThreshold (من 3 إلى 50 رقمًا مختلفًا في نطاق واحد خلال 10 دقائق). القائمة الفارغة في allowedCountries تمنع الإرسال إلى أي دولة.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ accessToken: process.env.SMSFABRIC_ACCESS_TOKEN });
const settings = await sms.verifications.settings.update({ allowedCountries: ['EG', 'SA', 'AE'], countryHourlyLimit: 100,});console.log(settings.source); // configured