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

ارسال کد تأیید از طریق واتساپ با 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 یک سرویس ابری جداگانه است.


