واجهة برمجة تطبيقات التحقق من OTP للمطورين: Node.js، بايثون، PHP، عينات كود جافا (2026)

إذا كنت مطورًا تقوم بتقييم OTP API لتطبيق يستهدف الولايات المتحدة في عام 2026، لا تريد صفحة تسويقية أخرى، فأنت تريد رمزًا يعمل. هذا الدليل عبارة عن إرشادات عملية لدمج ملف واجهة برمجة تطبيقات التحقق من رقم الهاتف في تطبيق الإنتاج: مرجع نقطة نهاية REST وعينات كود العمل في Node.js و Python و PHP و Java ومعالجة الأخطاء ومعالجة webhook واختبار وضع الحماية وقائمة مراجعة الإنتاج قبل قلب علامة الميزة.

تستخدم جميع الأمثلة نقاط نهاية REST الخاصة بـ VerifyNow، ولكن الأنماط تنتقل إلى معظمها واجهات برمجة تطبيقات OTP الحديثة (التحقق من Twilio، التحقق من الصوت، التحقق من صحة الصوت) مع الحد الأدنى من التغييرات. عندما تنطبق المخاوف الخاصة بالولايات المتحدة (توجيه 10DLC، اشتراك TCPA، الحماية من الاحتيال)، سنقوم باستدعائها عبر الإنترنت.

نقطتا النهاية اللتان تحتاجهما

يتم تقليل كل تدفق للتحقق من OTP إلى مكالمتين REST، بغض النظر عن المزود:

1. POST/التحقق/الإرسال: ينشئ OTP ويختار القناة المثلى (SMS و WhatsApp والصوت) ويرسل الرمز إلى هاتف المستخدم. تقوم بإرجاع معرف التحقق للمكالمة التالية.
2. POST/التحقق/التحقق من الصحة: يقبل معرف التحقق والرمز الذي أدخله المستخدم. يُرجع النجاح/الفشل بالإضافة إلى رمز خطأ عند الفشل.

كل شيء آخر (تفضيلات القناة وسياسات إعادة المحاولة وتبديل الحماية من الاحتيال) يتم تكوينه عند إرسال المكالمة. يعرض معظم الموفرين 8-12 معلمة اختيارية؛ الإعدادات الافتراضية معقولة لـ ~ 80٪ من حالات الاستخدام.

Node.js: إرسال OTP والتحقق منه

//التثبيت: تثبيت npm أكسيوس
المحاور الثابتة = مطلوب ('axios')؛

واجهة برمجة التطبيقات الثابتة = 'https://cpaas.messagecentral.com/verification/v3'؛
مفتاح واجهة برمجة التطبيقات الثابت = مفتاح process.env.mc_API_KEY؛

وظيفة غير متزامنة sendOTP (رقم الهاتف، القناة = 'SMS') {
استجابة ثابتة = انتظر axios.post (`$ {API_BASE} /إرسال`، {
رمز البلد: '1'،
رقم الهاتف المحمول: رقم الهاتف،
نوع التدفق: قناة،//«SMS» | «واتساب» | «صوت»
الطول: 6،
}، {
العناوين: {'AuthToken': API_KEY}
})؛
إرجاع معرف التحقق من response.data.data.data؛
}

وظيفة غير متزامنة تحقق من OTP (معرف التحقق، الرمز) {
الاستجابة الثابتة = await axios.post (`$ {API_BASE} /التحقق من الصحة»، {
معرف التحقق،
كود،
}، {
العناوين: {'AuthToken': API_KEY}
})؛
إرجاع حالة التحقق من response.data.data.data.=== «تم التحقق منه»؛
}

//الاستخدام في تدفق المصادقة الخاص بك
معرف التحقق الثابت = انتظر الإرسال إلى TP ('5551234567')؛
//... يقوم المستخدم بإدخال الرمز...
تم التحقق من const = انتظر التحقق (معرف التحقق، '482917')؛



بايثون: إرسال OTP والتحقق منه

# التثبيت: طلبات تثبيت النقاط
استيراد نظام التشغيل
طلبات الاستيراد

قاعدة واجهة برمجة التطبيقات = 'https://cpaas.messagecentral.com/verification/v3'
مفتاح واجهة برمجة التطبيقات = os.environ ['MC_API_KEY']

def send_otp (رقم الهاتف، القناة = «الرسائل القصيرة»):
الاستجابة = requests.post (
f' {API_BASE} /send'،
جايسون = {
«رمز البلد»: '1'،
«رقم الهاتف المحمول»: رقم الهاتف،
«نوع التدفق»: القناة،
«الطول الموجي»: 6،
}،
العناوين = {'رمز المصادقة': API_KEY}
)
الردود.raise_for_status ()
إرجاع response.json () ['البيانات'] ['معرف التحقق']

def verify_otp (معرف التحقق، الكود):
الاستجابة = requests.post (
f' {API_BASE} /التحقق من صحة '،
جايسون = {
«معرف التحقق»: معرف التحقق،
«الكود»: الكود،
}،
العناوين = {'رمز المصادقة': API_KEY}
)
الردود.raise_for_status ()
إرجاع response.json () ['البيانات'] ['حالة التحقق'] == «تم التحقق منه»



PHP: إرسال OTP والتحقق منه

<؟ php
//استخدام cURL - لا حاجة إلى تبعيات خارجية.

تعريف ('API_BASE'، 'https://cpaas.messagecentral.com/verification/v3')؛
حدد ('API_KEY'، واحصل على ('MC_API_KEY'))؛

وظيفة إرسال OTP ($رقم الهاتف، $channel = 'SMS') {
$ch = curl_init (API_BASE). «عند الإرسال»)؛
مصفوفة curl_setopt_array ($ch، [
تحويل CURLOPT_الإرجاع => صحيح،
CURLOPT_POST => صحيح،
عنوان CURLOPT_HTTP => [
«رمز المصادقة:». مفتاح واجهة برمجة التطبيقات،
«نوع المحتوى: التطبيق/json»،
]،
كيرلوبت_بوستفيلدز => json_encode ([
'رمز البلد' => '1'،
«رقم الهاتف المحمول» => $رقم الهاتف،
«نوع التدفق» => قناة $،
'طول الطول' => 6,
])،
])؛
$response = json_decode (curl_exec ($ch)، صحيح)؛
curl_close ($ch)؛
إرجاع $response ['البيانات'] ['معرف التحقق']؛
}

وظيفة التحقق من OTP (معرف التحقق $، رمز $) {
$ch = curl_init (API_BASE). ('التحققق')؛
مصفوفة curl_setopt_array ($ch، [
تحويل CURLOPT_الإرجاع => صحيح،
CURLOPT_POST => صحيح،
عنوان CURLOPT_HTTP => [
«رمز المصادقة:». مفتاح واجهة برمجة التطبيقات،
«نوع المحتوى: التطبيق/json»،
]،
كيرلوبت_بوستفيلدز => json_encode ([
'معرف التحقق' => $معرف التحقق،
'كود' => كود $،
])،
])؛
$response = json_decode (curl_exec ($ch)، صحيح)؛
curl_close ($ch)؛
إرجاع $response ['البيانات'] ['حالة التحقق'] === «تم التحقق منه»؛
}



Java: إرسال OTP والتحقق منه

//باستخدام java.net.http (JDK 11+).
استيراد جافا.net.uri؛
استيراد عميل جافا.net.http.http؛
استيراد طلب جافا.net.http.http؛
استيراد استجابة جافا.net.http.http؛
استيراد مخطط بيانات com.faster Xml.jackson.databind.ObjectMapper؛
استيراد com.fasterxml.jackson.databind.js على العقدة؛

فئة عامة تحقق من NowClient {
السلسلة النهائية الثابتة الخاصة API_BASE = "https://cpaas.messagecentral.com/verification/v3 «؛
السلسلة النهائية الثابتة الخاصة API_KEY = System.getEnv («MC_API_KEY»)؛
عميل HttpClient النهائي الثابت الخاص = HttpClient.NewHttpClient ()؛
مخطط مخطط الكائن النهائي الثابت الخاص = مخطط ObjectMapper الجديد ()؛

ترسل السلسلة الثابتة العامة (رقم هاتف السلسلة، قناة السلسلة) الاستثناء {
نص السلسلة = مخطط. اكتب القيمة كسلسلة (java.util.Map.of
«رمز البلد»، «1"،
«رقم الهاتف المحمول»، رقم الهاتف،
«نوع التدفق»، القناة،
«الطول العلوي»، 6
))؛
طلب HTTP = httpRequest.newBuilder ()
.uri (URI. Create (API_BASE + «/send»))
.header («رمز المصادقة»، مفتاح واجهة برمجة التطبيقات)
.header («نوع المحتوى»، «التطبيق/json»)
.POST (http://request.body Publishers.ofstring (النص الأساسي))
.build ()؛
استجابة HTTP resp <String>= client.send (req، http Response.bodyhandlers.ofstring ())؛
إرجاع mapper.readtree (resp.body ()) .get («البيانات») .get («معرف التحقق») .asText ()؛
}

يطرح التحقق المنطقي الثابت العام (معرف التحقق من السلسلة، رمز السلسلة) الاستثناء {
نص السلسلة = مخطط. اكتب القيمة كسلسلة (java.util.Map.of
«معرف التحقق»، معرف التحقق،
«كود»، كود
))؛
طلب HTTP = httpRequest.newBuilder ()
.uri (URI. Create (API_BASE + «/validate»))
.header («رمز المصادقة»، مفتاح واجهة برمجة التطبيقات)
.header («نوع المحتوى»، «التطبيق/json»)
.POST (http://request.body Publishers.ofstring (النص الأساسي))
.build ()؛
استجابة HTTP resp <String>= client.send (req، http Response.bodyhandlers.ofstring ())؛
إرجاع «تم التحقق منه» .يساوي (mapper.readtree (resp.body ())
.get («البيانات») .get («حالة التحقق») .asText ())؛
}
}



معالجة الأخطاء التي تحتاجها بالفعل

الأخطاء المهمة في الإنتاج ليست تلك الموجودة في المسار السعيد. خمسة يجب عليك التعامل معها:

صيغة رقم هاتف غير صالحة

‍تقوم بإرجاع HTTP 400 مع رمز الخطأ رقم_غير صالح. استخدم جوجل رقم هاتف ليب للتطبيع قبل استدعاء API.

عدم تطابق الكود

‍أدخل المستخدم OTP بشكل خاطئ. تقوم بإرجاع HTTP 200 مع حالة التحقق: «فشلت». اسمح بما يصل إلى 3-5 محاولات قبل إبطال معرف التحقق.

انتهت صلاحية الرمز

‍انتظر المستخدم وقتًا طويلاً. عمليات الإرجاع حالة التحقق: «منتهية الصلاحية». اعرض عبارة «إعادة إرسال الرمز» CTA في واجهة المستخدم الخاصة بك.

سعر محدود

‍طلب رقم الهاتف نفسه عددًا كبيرًا جدًا من OTPs. تقوم بإرجاع HTTP 429. لا تعيد المحاولة على الفور - تراجع بشكل كبير.

تم اكتشاف ضخ الرسائل القصيرة

‍تقوم بإرجاع HTTP 403 مع رمز الخطأ تم اكتشاف الاحتيال. لا تعيد المحاولة. ضع علامة على الطلب في خط أنابيب الكشف عن الاحتيال.

Webhooks لحالة التسليم

بالنسبة لعمليات نشر الإنتاج، استمع إلى عمليات الاسترجاعات الخاصة بالتسليم غير المتزامن بدلاً من الاستقصاء. قم بتكوين عنوان URL الخاص بـ webhook في لوحة معلومات الموفر، ثم تعامل مع:

//مثال معالج ويب هوك Express.js
app.post ('/webhooks/verifynow', (مطلوب، مطلوب) => {
const {معرف التحقق، حالة التسليم، القناة، وقت الاستجابة (SMS)} = req.body؛

//استمر في التحليلات
db.أحداث التسليم. أدخل ({
معرف التحقق،
حالة التسليم،//«تم التسليم» | «فشل» | «معلق»
قناة،//«SMS» | «واتساب» | «صوت»
زمن الوصول: السيدة،
الطابع الزمني: تاريخ جديد ()،
})؛

//اختياري: تشغيل الرجوع إلى القناة البديلة عند الفشل
إذا (حالة التسليم === «فشل» && القناة === «SMS») {
أرسل رد فعل FTP (معرف التحقق، «WHATSAPP»)؛
}

حالة القرار (200). النهاية (1);
})؛



تحقق دائمًا من أصالة webhook باستخدام عنوان التوقيع الذي يرسله مزود الخدمة - لا تثق أبدًا بخطاف الويب غير الموقّع في الإنتاج.

اختبار Sandbox قبل الإنتاج

قبل قلب علامة الميزة، تحقق من البداية إلى النهاية على وضع الحماية:

• أرقام هواتف الاختبار: معظم مزودي خدمة OTP في الولايات المتحدة تقدم أرقام الاختبار المحجوزة التي تنجح دائماً/تفشل/تنتهي المهلة بشكل حتمي.
• اختبار الشبكة: تحقق من أن جدار الحماية الخاص بك يسمح بإرسال HTTPS إلى نقاط نهاية API الخاصة بالموفر (عادةً المنفذ 443).
• اختبار حد السعر: قم بتشغيل حد معدل لكل رقم بشكل متعمد وتأكد من أن معالجة الخطأ تظهر رسالة مفيدة.
• اختبار وقت الاستجابة: قم بقياس وقت الرحلة ذهابًا وإيابًا للإرسال والتحقق تحت الحمل المعتاد.
• اختبار تسليم Webhook: استخدم خدمة مثل موقع ويب هوك لفحص عمليات الاسترجاعات قبل توجيهها إلى الإنتاج.

يستخدم صندوق الحماية الخاص بـ VerifyNow ائتمانات اختبار مجانية بدون بطاقة ائتمان، حتى تتمكن من تشغيل التكامل الكامل في مرحلة ما قبل الإنتاج دون الالتزام بعقد.

قائمة مراجعة الإنتاج قبل الإطلاق

اثنا عشر عنصرًا للتحقق منها قبل قلب علامة الميزة:

1. مفاتيح API المخزنة في مدير الأسرار (وليس التحكم في المصدر)
2. تم تثبيت libphonenumber واستخدامه للتطبيع من جانب العميل
3. واجهة برمجة تطبيقات SMS Retriever مدمجة على نظام Android (تتخطى إدخال الرمز اليدوي)
4. واجهة برمجة تطبيقات WebOTP مدمجة على الويب (الملء التلقائي من الإشعار)
5. يتم تعيين القائمة المنسدلة لرمز البلد افتراضيًا على عنوان IP الجغرافي للمستخدم
6. تم إخفاء زر «إعادة إرسال الرمز» لأول 30 ثانية، ثم تم الكشف عنه
7. تم تمكين النسخ الاحتياطي متعدد القنوات (الرسائل القصيرة ← WhatsApp ← الصوت)
8. يقوم معالج Webhook بمصادقة رأس التوقيع
9. تنبيه بفشل التسليم يتم توصيله سلكيًا إلى Slack/PagerDuty
10. تحديد معدل لكل عنوان IP ولكل رقم في طبقة التطبيق (وليس فقط الموفر)
11. تم اختبار إيقاف معالجة الكلمات الرئيسية (الامتثال لـ TCPA)
12. تمت كتابة دفتر الإنتاج لسيناريوهات «تسليم OTP معطل» وتخزينها

الأسئلة الشائعة

ما اللغة التي تحتوي على أفضل SDK لواجهات برمجة تطبيقات OTP؟‍

يقدم معظم الموفرين حزم SDK الرسمية في Node و Python و Java و PHP و Go و Ruby مع تكافؤ الميزات. الاختلافات بين حزم SDK تجميلية في الغالب - REST هي REST. اختر اللغة التي يكتب بها فريقك خدمة المصادقة. إذا كان فريقك يكتب بلغة Rust أو .NET، فإن استدعاء نقاط نهاية REST مباشرةً باستخدام عميل HTTP للغة (كما في مثال Java أعلاه) يكون أمرًا سهلاً.

كيف أتعامل مع عودة OTP إلى قناة مختلفة عند الفشل؟‍

نمطان: (أ) تكوين احتياطي تلقائي من جانب الموفر من خلال إدراج القنوات بترتيب الأولوية في مكالمة الإرسال، ويحاول الموفر كل منها بالتسلسل عند فشل التسليم؛ (ب) الاستماع إلى روابط الويب الخاصة بالتسليم وتشغيل مكالمة إرسال جديدة مع قناة مختلفة عن التطبيق الخاص بك. الأول أبسط؛ الثاني يمنحك المزيد من التحكم. تحقق الآن يدعم كلا النمطين.

هل يجب أن أقوم بتطبيق OTP UI على الويب باستخدام WebOTP؟‍

نعم، حيث تدعمها المتصفحات. واجهة برمجة تطبيقات WebOTP من Google يملأ الرمز تلقائيًا من إشعار SMS على Chrome و Edge. يجب تنسيق رسالة OTP بنمط خاص (على سبيل المثال، «الرمز الخاص بك هو 123456 #abc .example.com #482917 «) حتى تتمكن المتصفحات من التعرف عليها. يعود بأمان إلى الإدخال اليدوي على المتصفحات غير المدعومة.

احصل على مفتاح Sandbox في أقل من دقيقة

أسرع طريقة للتحقق من صحة أي من التعليمات البرمجية أعلاه هي تشغيلها مقابل وضع حماية حقيقي. تحقق الآن للولايات المتحدة الأمريكية يمنحك نقاط اختبار مجانية بدون بطاقة ائتمان ونقاط نهاية REST موثقة من البداية إلى النهاية ومجموعات SDK بست لغات. تقوم معظم الفرق بشحن أول تكامل لـ OTP في غضون ساعات قليلة من التسجيل.