تكامل WhatsApp OTP API: أمثلة PHP وNode.js وPython

يتلخّص إرسال رمز التحقق عبر WhatsApp في استدعاءين لواجهة WapFlow OTP API: أحدهما يرسل الرمز، والآخر يتحقق مما كتبه المستخدم. في هذا الدليل نجمع طريقة عمل الواجهة، وأمثلة cURL وPHP وNode.js وPython، ومعالجة الأخطاء، ونقاط الأمان التي ينبغي الانتباه إليها. تتّبع الأمثلة الصيغة الواردة في الوثائق الرسمية للواجهة، مع إضافات بسيطة لتسهيل القراءة. وإذا كنتم تتساءلون عن طبيعة المنتج قبل البدء بالبرمجة، فاطّلعوا أولًا على ما هو WhatsApp OTP.
الأساسيات
- العنوان الأساسي:
https://wapflow.net/api/otp/v1 - المصادقة: ترويسة
Authorization: Bearer <key>في كل طلب. تبدأ المفاتيح الفعلية بـwfo_live_، ومفاتيح الاختبار بـwfo_test_. - صيغة الاستجابة: عند النجاح
{ "success": true, ... }، وعند الخطأ{ "success": false, "error": { "code": "...", "message": "..." } }. - رقم الهاتف: مع رمز الدولة، مثل
905321234567. تختزل الواجهة الرقم إلى أرقام (تُحذف علامة + والمسافات والشرطات)، وتتوقع من 10 إلى 15 رقمًا. تُعامَل الأرقام المكوّنة من 11 رقمًا التي تبدأ بـ 0 على أنها تركية، ويُضاف إليها 90 في البداية.
تنشئون مفتاح الواجهة من صفحة WapFlow OTP في لوحة WapFlow. يُعرض المفتاح مرة واحدة فقط عند إنشائه؛ احفظوه في متغير بيئة على خادمكم.
نقاط النهاية الأربع
| النقطة | المهمة |
|---|---|
| POST /send | تنشئ الرمز وترسله عبر WhatsApp. الحقل phone إلزامي، والحقول الاختيارية: code_length (من 4 إلى 8)، وttl (من 60 إلى 900 ثانية)، وlang، وapp_name. |
| POST /verify | تتحقق من الرمز الذي كتبه المستخدم. الحقلان phone وcode إلزاميان؛ وإذا مررتم request_id فسيُفحص ذلك الطلب تحديدًا. |
| GET /status/:request_id | تعيد حالة الطلب: queued وsent وdelivered وread وfailed وverified وexpired. |
| GET /me | تعرض صلاحية المفتاح، والباقة، وعدد الحسابات المتصلة، واستهلاك الحصة لهذا الشهر. |
بعد 5 محاولات خاطئة يُقفل الطلب، ولا يمكن إعادة استخدام الرمز بعد التحقق منه. وإذا لم تمرّروا request_id، فسيُفحص آخر رمز غير منتهٍ أُرسل إلى ذلك الرقم بهذا المفتاح. ولأنه قد توجد عدة جلسات، ننصح بحفظ request_id وإعادة إرساله عند التحقق.
تجربة أولى باستخدام cURL
# 1) send the code
curl -X POST https://wapflow.net/api/otp/v1/send \
-H "Authorization: Bearer wfo_live_XXXX" \
-H "Content-Type: application/json" \
-d '{"phone":"905321234567","app_name":"Acme"}'
# 2) verify the code
curl -X POST https://wapflow.net/api/otp/v1/verify \
-H "Authorization: Bearer wfo_live_XXXX" \
-H "Content-Type: application/json" \
-d '{"request_id":"req_...","phone":"905321234567","code":"123456"}'
نفّذوا المحاولة الأولى بمفتاح wfo_test_: لن تُرسل رسالة إلى WhatsApp، ولن تُستهلك الحصة، وسيعود الرمز في الحقل test_code من الاستجابة.
مثال PHP
<?php
function wapflow_otp(string $path, array $body): array {
$ch = curl_init('https://wapflow.net/api/otp/v1' . $path);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 15,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('WAPFLOW_OTP_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($body),
]);
$res = json_decode(curl_exec($ch), true) ?: [];
curl_close($ch);
return $res;
}
$sent = wapflow_otp('/send', ['phone' => '905321234567', 'app_name' => 'Acme']);
// ... when the user submits the code:
$check = wapflow_otp('/verify', ['request_id' => $sent['request_id'], 'phone' => '905321234567', 'code' => $_POST['code']]);
if (!empty($check['valid'])) { /* signed in */ }
مثال Node.js
يستخدم المثال دالة fetch المدمجة (في Node.js 18 وما بعده)، ويجب تشغيله كوحدة ES module.
const BASE = 'https://wapflow.net/api/otp/v1';
async function otp(path, body) {
const res = await fetch(BASE + path, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.WAPFLOW_OTP_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(body),
});
return res.json();
}
const sent = await otp('/send', { phone: '905321234567', app_name: 'Acme' });
// ... when the user submits the code:
const check = await otp('/verify', { request_id: sent.request_id, phone: '905321234567', code: '123456' });
if (check.valid) { /* signed in */ }
مثال Python
import os
import requests
BASE = "https://wapflow.net/api/otp/v1"
HEADERS = {"Authorization": "Bearer " + os.environ["WAPFLOW_OTP_KEY"]}
def otp(path, body):
return requests.post(BASE + path, json=body, headers=HEADERS, timeout=15).json()
sent = otp("/send", {"phone": "905321234567", "app_name": "Acme"})
# ... when the user submits the code:
check = otp("/verify", {"request_id": sent["request_id"], "phone": "905321234567", "code": "123456"})
if check.get("valid"):
pass # signed in
معالجة الأخطاء
عالجوا نتائج الإرسال والتحقق كلًّا على حدة. إذا أعاد الإرسال success: false، فتصرّفوا بحسب رمز الخطأ:
| HTTP / الرمز | ماذا تفعلون؟ |
|---|---|
| 401 invalid_key | تحقّقوا من المفتاح؛ فقد يكون ملغى أو مكتوبًا بشكل خاطئ. |
| 402 no_subscription, subscription_expired | ابدأوا الاشتراك أو جدّدوه. |
| 422 invalid_phone | اطلبوا من المستخدم إعادة إدخال الرقم مع رمز الدولة. |
| 429 rate_limited | أعيدوا المحاولة بعد عدد الثواني المذكور في retry_after ضمن الاستجابة. |
| 429 quota_exceeded | انتهت الحصة الشهرية؛ رقّوا الباقة أو انتظروا الفترة التالية. |
| 429 daily_limit_reached | بلغت الحسابات المتصلة حدّها اليومي؛ أعيدوا المحاولة بعد retry_after (في اليوم التالي عند الساعة 00:00 بتوقيت تركيا). لا تُستهلك الحصة. |
| 503 no_account_connected, send_failed | تأكدوا من وجود حساب WhatsApp متصل ومفعّل، وأعيدوا المحاولة بعد قليل. |
في التحقق قد تعيد HTTP 200 ومع ذلك تكون قيمة valid false. يوضح حقل reason السبب: invalid_code أو expired أو too_many_attempts أو already_verified أو not_found. وعند الرمز الخاطئ يبيّن attempts_left عدد المحاولات المتبقية؛ وإبلاغ المستخدم بذلك يحسّن تجربته.
حدود المعدل وتجربة المستخدم
- يمكن إرسال رمز واحد إلى الرقم نفسه كل 60 ثانية، وخمسة في الساعة، وعشرة في اليوم. ضعوا عدًّا تنازليًا مدته 60 ثانية على زر «إعادة الإرسال».
- يوجد 60 إرسالًا في الدقيقة لكل مفتاح API، و120 طلبًا في الدقيقة لكل عنوان IP، و10 محاولات تحقق في الدقيقة لكل رقم.
- يؤثر الحد اليومي وتسخين الأرقام الجديدة في الإرسال؛ للتفاصيل راجعوا مقالتنا عن تقليل خطر الحظر.
قائمة التحقق الأمني
- لا تستخدموا مفتاح API في المتصفح أو تطبيق الجوال أو أي شيفرة عامة؛ أجروا الاستدعاءات من خادمكم.
- تحقّقوا من الرمز دائمًا على الخادم عبر
/verify، ولا تثقوا بمعلومة «تم التحقق» القادمة من المتصفح. - احفظوا المفتاح في متغير بيئة، ولا ترفعوه إلى المستودع.
- طبّقوا حدّ معدل خاصًا بكم، وعند الحاجة CAPTCHA، قبل إرسال أي رمز؛ فقد يستنزف الاستخدام المسيء حصتكم.
- احتفظوا بقناة احتياطية (SMS أو البريد الإلكتروني) للعمليات الحساسة. WapFlow OTP ليس واجهة WhatsApp Business API الرسمية، ولا يضمن التسليم.
إذا كنتم تستخدمون WordPress أو WooCommerce، فيمكنكم الاستغناء عن البرمجة واستخدام الإضافة. للباقات راجعوا صفحة الأسعار، ولملخص المنتج راجعوا صفحة WapFlow OTP.
الأسئلة الشائعة
ما الذي يتغيّر عند الانتقال إلى الإنتاج؟
المفتاح فقط. يبدأ مفتاح الاختبار بـ wfo_test_، وقواعد الإرسال والمعدل فيه هي نفسها في المفتاح الفعلي، ولا يزال الاشتراك الفعّال مطلوبًا.
هل يجب إرسال request_id؟
لا، لكنه مُوصى به. وإذا لم ترسلوه فسيُفحص آخر رمز غير منتهٍ أُرسل إلى ذلك الرقم.
هل يمكنني تغيير نص الرسالة؟
نعم. من اللوحة يمكن ضبط اسم التطبيق، ونموذج الرسالة، وطول الرمز، والمدة، واللغة. يستخدم النموذج المتغيرات {code} و{app} و{minutes}. ويمكنكم تجاوز هذه الإعدادات لكل طلب باستخدام app_name وcode_length وttl وlang.
كيف أعرف أن الرسالة وصلت؟
استعلموا عن الطلب عبر نقطة النهاية /status/:request_id، وقد تظهر القيم sent وdelivered وread. وتعتمد معلومات التسليم على WhatsApp ولا تُضمن.
هل هذه الواجهة متاحة في تطبيق Windows أيضًا؟
لا. WapFlow OTP خدمة سحابية منفصلة.


