ar
معاينة مجانية

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

بقلم: فريق WapFlow · 16 نوفمبر 2026 · 6 دقيقة قراءة
محرر شيفرة يعرض استدعاء WhatsApp OTP API ورسالة رمز التحقق على الهاتف

يتلخّص إرسال رمز التحقق عبر 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 خدمة سحابية منفصلة.

مقالات ذات صلة