fa
پیش‌نمایش رایگان

یکپارچه‌سازی API کد تأیید واتساپ: نمونه‌های PHP، Node.js و Python

نویسنده: تیم WapFlow · 16 نوامبر 2026 · 7 دقیقه مطالعه
ویرایشگر کد با فراخوانی API کد تأیید واتساپ و پیام کد تأیید روی گوشی

ارسال کد تأیید از طریق واتساپ با API کد OTP وپ‌فلو به دو فراخوانی خلاصه می‌شود: یکی کد را می‌فرستد و دیگری آنچه کاربر وارد کرده را تأیید می‌کند. در این راهنما نحوه کار API، نمونه‌های cURL، PHP، Node.js و Python، مدیریت خطا و نکات امنیتی که باید مراقب آن باشید را گردآوری کرده‌ایم. نمونه‌ها با قالب مستندات رسمی API مطابقت دارند و فقط برای خوانایی کمی اضافه شده‌اند. اگر قبل از کدنویسی نمی‌دانید این محصول چیست، ابتدا OTP واتساپ چیست را بخوانید.

اصول اولیه

  • آدرس پایه: https://wapflow.net/api/otp/v1
  • احراز هویت: هدر Authorization: Bearer <key> در هر درخواست. کلیدهای زنده با wfo_live_ و کلیدهای آزمایشی با wfo_test_ شروع می‌شوند.
  • قالب پاسخ: در موفقیت { "success": true, ... } و در خطا { "success": false, "error": { "code": "...", "message": "..." } }.
  • شماره تلفن: همراه با کد کشور، برای نمونه 905321234567. API شماره را به رقم تبدیل می‌کند (+، فاصله و خط تیره حذف می‌شوند) و ۱۰ تا ۱۵ رقم انتظار دارد. شماره‌های یازده‌رقمی که با ۰ شروع می‌شوند ترکیه‌ای در نظر گرفته می‌شوند و ۹۰ پیش از آن‌ها اضافه می‌شود.

کلید API را در صفحه OTP وپ‌فلو در پنل وپ‌فلو بسازید. کلید فقط هنگام ساخت نمایش داده می‌شود؛ آن را در یک متغیر محیطی روی سرور نگه دارید.

چهار نقطه پایانی

نقطه پایانیکاربرد
POST /sendکد را تولید و از طریق واتساپ ارسال می‌کند. phone الزامی است؛ code_length (۴ تا ۸)، ttl (۶۰ تا ۹۰۰ ثانیه)، lang و app_name اختیاری‌اند.
POST /verifyکدی را که کاربر وارد کرده بررسی می‌کند. phone و code الزامی‌اند؛ اگر request_id بفرستید، همان درخواست بررسی می‌شود.
GET /status/:request_idوضعیت درخواست را برمی‌گرداند: queued، sent، delivered، read، failed، verified، expired.
GET /meنشان می‌دهد کلید معتبر است یا نه، پلن، تعداد حساب‌های متصل و مصرف سهمیه این ماه را.

پس از ۵ تلاش اشتباه، درخواست قفل می‌شود و کد تأییدشده دوباره قابل استفاده نیست. اگر 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_ انجام دهید: پیام واتساپ ارسال نمی‌شود، سهمیه مصرف نمی‌شود و کد در فیلد 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 نسخه ۱۸ یا بالاتر) استفاده می‌کند و باید به‌صورت ماژول ES اجرا شود.

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 دوباره تلاش کنید (روز بعد ساعت ۰۰:۰۰ به وقت ترکیه). سهمیه مصرف نمی‌شود.
503 no_account_connected، send_failedمطمئن شوید یک حساب واتساپ متصل و فعال وجود دارد؛ کمی بعد دوباره تلاش کنید.

در تأیید، پاسخ HTTP 200 هم ممکن است valid برابر false داشته باشد. فیلد reason دلیل را نشان می‌دهد: invalid_code، expired، too_many_attempts، already_verified یا not_found. برای کد اشتباه، attempts_left نشان می‌دهد چند تلاش باقی مانده است؛ انتقال آن به کاربر تجربه بهتری می‌سازد.

محدودیت نرخ و تجربه کاربر

  • هر شماره می‌تواند در هر ۶۰ ثانیه ۱ کد، در هر ساعت ۵ کد و در هر روز ۱۰ کد دریافت کند. روی دکمه «ارسال مجدد» یک شمارش معکوس ۶۰ ثانیه‌ای بگذارید.
  • برای هر کلید API در دقیقه ۶۰ ارسال، برای هر نشانی IP در دقیقه ۱۲۰ درخواست و برای تأیید، برای هر شماره در دقیقه ۱۰ تلاش مجاز است.
  • محدودیت روزانه و گرم‌شدن شماره‌های جدید بر ارسال تأثیر می‌گذارد؛ جزئیات را در مطلب کاهش خطر مسدودی ما ببینید.

فهرست امنیتی

  • هرگز کلید API را در مرورگر، اپ موبایل یا هر کد عمومی به کار نبرید؛ فراخوانی‌ها را از سرور خودتان انجام دهید.
  • همیشه کد را در سرور با /verify بررسی کنید؛ به پرچم «تأییدشده» که از مرورگر می‌آید اعتماد نکنید.
  • کلید را در متغیر محیطی نگه دارید و آن را داخل مخزن کد نگذارید.
  • پیش از ارسال کد، محدودیت نرخ خودتان و در صورت نیاز CAPTCHA اعمال کنید؛ سوءاستفاده می‌تواند سهمیه شما را ببلعد.
  • برای اقدامات حساس یک کانال پشتیبان (پیامک یا ایمیل) نگه دارید. WapFlow OTP API رسمی WhatsApp Business نیست و تحویل پیام را تضمین نمی‌کند.

اگر از WordPress یا WooCommerce استفاده می‌کنید، می‌توانید از کدنویسی صرف‌نظر کنید و از افزونه استفاده کنید. برای پلن‌ها صفحه قیمت‌ها و برای معرفی محصول صفحه OTP وپ‌فلو را ببینید.

پرسش‌های متداول

وقتی به حالت واقعی می‌روم چه تغییری می‌کند؟

فقط کلید. کلید آزمایشی با wfo_test_ شروع می‌شود و قواعد ارسال و نرخ آن همان کلید زنده است؛ اشتراک فعال هم همچنان لازم است.

آیا حتماً باید request_id را بفرستم؟

خیر، اما توصیه می‌شود. اگر نفرستید، آخرین کد منقضی‌نشده ارسال‌شده به آن شماره بررسی می‌شود.

آیا می‌توانم متن پیام را تغییر دهم؟

بله. در پنل می‌توانید نام برنامه، قالب پیام، طول کد، مدت اعتبار و زبان را تنظیم کنید. قالب از متغیرهای {code}، {app} و {minutes} استفاده می‌کند. برای هر درخواست هم می‌توانید این مقادیر را با app_name، code_length، ttl و lang تغییر دهید.

از کجا بفهمم پیام تحویل شده است؟

درخواست را با /status/:request_id استعلام کنید؛ ممکن است sent، delivered و read را ببینید. اطلاعات تحویل به واتساپ بستگی دارد و تضمین نمی‌شود.

آیا این API در برنامه Windows هم وجود دارد؟

خیر. WapFlow OTP یک سرویس ابری جداگانه است.

مقاله‌های مرتبط