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

التحقق

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}}.
send-code.ts
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******4567
console.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 تلقائيًا أبدًا، لأن كل فحص يقيّم رمزًا يستهلك محاولة.

check-code.ts
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 والرقم مخفيًا جزئيًا.

get-verification.ts
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.

list-verifications.ts
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);

كل عمليات التحقق المطابقة، مع تتبع المؤشرات.

approval-rate.ts
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`);

إعدادات الحماية من استنزاف الرسائل المطبقة حاليًا: الدول المسموح بإرسال الرموز إليها (allowedCountries)، وهل حفظتَ القائمة بنفسك (configured) أم اشتقت من أرقام شرائحك (sim_numbers)، وكل حد، وعدد حظر النطاقات النشط. تحتاج إلى verify:check.

verify-settings.ts
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');

تستبدل الدول المسموح بها، واختياريًا الحدود: orgHourlyLimit وcountryHourlyLimit (من 1 إلى 1,000 إرسال في الساعة) وprefixBurstThreshold (من 3 إلى 50 رقمًا مختلفًا في نطاق واحد خلال 10 دقائق). القائمة الفارغة في allowedCountries تمنع الإرسال إلى أي دولة.

update-verify-settings.ts
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