مرجع WapFlow OTP API

أرسل رموز التحقق وتحقق منها من رقم WhatsApp الخاص بك. جميع الاستجابات بصيغة JSON.

عنوان URL الأساسي: https://wapflow.net/api/otp/v1

المصادقة

أرسل الترويسة Authorization: Bearer <key> مع كل طلب. تُنشأ المفاتيح في صفحة WapFlow OTP داخل لوحة WapFlow؛ تبدأ المفاتيح الحية بـ wfo_live_ والمفاتيح التجريبية بـ wfo_test_. يُعرض المفتاح مرة واحدة فقط عند إنشائه — احفظه بأمان واستخدمه على خادمك فقط.

تكون الاستجابة الناجحة بالشكل { "success": true, ... }، وتكون استجابة الخطأ بالشكل { "success": false, "error": { "code": "...", "message": "..." } }.

إرسال رمز

phone (مطلوب) هو رقم المستلم. اختيارياً: code_length (من 4 إلى 8)، وttl (من 60 إلى 900 ثانية)، وlang (مثل tr وen) وapp_name. أي قيمة لا تحددها تُؤخذ من إعدادات لوحتك.

{
  "phone": "905321234567",
  "code_length": 6,
  "ttl": 300,
  "lang": "tr",
  "app_name": "Acme"
}

{
  "success": true,
  "request_id": "req_...",
  "phone": "905321234567",
  "expires_at": "2026-11-12T10:05:00.000Z",
  "status": "sent"            // "sent" | "queued"
}

التحقق من رمز

الحقلان phone وcode مطلوبان. إذا أرسلت request_id يُتحقق من ذلك الطلب تحديداً؛ وإن لم ترسله فيُتحقق من آخر رمز غير منتهٍ أُرسل إلى هذا الرقم بهذا المفتاح. بعد 5 محاولات خاطئة يُقفل الطلب، ولا يمكن إعادة استخدام الرمز بعد التحقق منه.

{ "request_id": "req_...", "phone": "905321234567", "code": "123456" }

{ "success": true, "valid": true }

{ "success": true, "valid": false,
  "reason": "invalid_code",     // invalid_code | expired | too_many_attempts | already_verified | not_found
  "attempts_left": 3 }

الاستعلام عن الحالة

يعيد حالة الطلب: queued، sent، delivered، read، failed، verified أو expired.

{ "success": true, "request_id": "req_...", "status": "delivered",
  "sent_at": "...", "delivered_at": "...", "verified_at": null }

اختبار الاتصال

يعرض أن المفتاح صالح، وباقتك، وعدد الحسابات المرتبطة، واستخدام الحصة لهذا الشهر (يستخدمه زر "اختبار الاتصال" في إضافة WordPress).

{ "success": true, "plan": "otp-2",
  "accounts": { "limit": 2, "connected": 1 },
  "quota": { "monthly": 15000, "used": 42, "period": "2026-11" },
  "ends_at": "2026-12-12T10:00:00.000Z", "mode": "live" }

أمثلة

تُرسل هذه الأمثلة رمزاً ثم تتحقق من الرمز الذي يُدخله المستخدم. استبدل wfo_live_XXXX بمفتاحك الخاص.

# 1) send
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
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"}'

<?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']);
// ... kullanıcı kodu girince:
$check = wapflow_otp('/verify', ['request_id' => $sent['request_id'], 'phone' => '905321234567', 'code' => $_POST['code']]);
if (!empty($check['valid'])) { /* giriş başarılı */ }

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 */ }

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

رموز الأخطاء

حدود المعدل

• لكل رقم: رمز واحد كل 60 ثانية، و5 في الساعة، و10 في اليوم.
• لكل مفتاح API: 60 إرسالاً في الدقيقة.
• لكل عنوان IP: 120 طلباً في الدقيقة (يشمل التحقق).
• التحقق: 10 محاولات في الدقيقة لكل رقم، وبحد أقصى 5 محاولات خاطئة لكل رمز.
• تعتمد الحصة الشهرية على باقتك؛ وعند استنفادها يُعاد quota_exceeded. لا تستهلك المفاتيح التجريبية أي حصة.

تسخين الحساب والحد اليومي

• تُسخَّن أرقام واتساب الجديدة المتصلة تدريجياً لتقليل خطر الحظر: 30 رمزاً يومياً في الأيام الثلاثة الأولى، و100 رمز يومياً في الأيام 4–7، ثم 500 رمز يومياً لكل حساب (القيم الافتراضية).
• يُتخطّى الحساب الذي يصل إلى حده اليومي، وتُرسَل الرموز من حساباتك المتصلة الأخرى. إذا امتلأت جميعها، يُرجَع 429 daily_limit_reached؛ ويُعاد العداد إلى الصفر عند منتصف الليل بتوقيت إسطنبول.
• لحجم أكبر، اختر باقة تتضمن عدة حسابات. مفاتيح الاختبار لا تتأثر بهذه الحدود.

المفاتيح التجريبية

المفاتيح التي تبدأ بـ wfo_test_ لا ترسل أي رسالة WhatsApp ولا تستهلك أي حصة؛ يُعاد الرمز في الحقل test_code من الاستجابة. قواعد الإرسال والحدود هي نفسها للمفتاح الحي، ويظل الاشتراك النشط مطلوباً. للانتقال إلى الوضع الحي، غيّر المفتاح فقط.

{ "success": true, "request_id": "req_...", "status": "sent", "test_code": "482913" }

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

• يُختصر الرقم إلى أرقام فقط (تُحذف علامة + والمسافات والشرطات)، ويجب أن يكون طوله بين 10 و15 رقماً.
• أدرج رمز الدولة (مثل 905321234567). تُعامل الأرقام المكونة من 11 رقماً التي تبدأ بالصفر على أنها تركية ويُضاف إليها 90 في البداية.
• الرقم غير الصالح يُعيد 422 invalid_phone.

ملاحظات أمنية

• تُولَّد الرموز بمولّد أرقام عشوائية آمن تشفيرياً، ولا تُخزَّن أبداً كنص صريح.
• لا تستخدم مفتاح API في المتصفح أو تطبيق الجوال أو الشيفرة العامة؛ أجرِ الاستدعاءات من خادمك.
• تحقق دائماً من الرمز على الخادم عبر /verify.
• WapFlow OTP ليست واجهة WhatsApp API الرسمية ولا تضمن التسليم؛ احتفظ بقناة احتياطية للعمليات الحرجة.

إضافة WordPress

1. حمّل wapflow-otp.zip.
2. في لوحة إدارة WordPress انتقل إلى الإضافات → أضف جديدة → رفع إضافة، وارفع ملف zip وفعّله.
3. في إعدادات الإضافة، الصق مفتاح API الذي أنشأته في لوحة WapFlow.
4. استخدم زر "اختبار الاتصال" للتحقق من المفتاح وباقتك.
5. جرّب أولاً بمفتاح تجريبي، ثم انتقل إلى المفتاح الحي.