مرجع WhatsApp OTP API

المصادقة

تستخدم الواجهة مصادقة Bearer Token. أنشئ مفتاح API من لوحة التحكم › الإعدادات › مفاتيح API وامنحه صلاحيتَي otp:send وotp:verify.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json

Base URL

https://app.zervixo.com/api/v1

جميع الطلبات يجب أن تتضمن Accept: application/json. الاستجابات دائمًا بصيغة JSON.

POST /api/v1/otp/send

يُرسل رمز OTP إلى رقم هاتف عبر واتساب. يتطلب صلاحية otp:send على مفتاح API.

{
  "success": true,
  "message": "OTP sent",
  "expires_at": "2026-10-20T14:35:00Z",
  "ref": "otp_01jd3k8m4v2xq6z"
}

POST /api/v1/otp/verify

يتحقق من رمز OTP مُرسَل سابقًا. يتطلب صلاحية otp:verify على مفتاح API.

{
  "success": true,
  "verified": true,
  "phone": "+966501234567"
}

{
  "success": false,
  "verified": false,
  "error": "invalid_or_expired"
}

حدود المعدل

تُطبَّق الحدود على مستوى مفتاح API. عند تجاوزها تُعاد استجابة 429 Too Many Requests مع رأس Retry-After يُحدد وقت الانتظار بالثواني.

رموز الأخطاء

أمثلة على الكود

cURL — إرسال OTP

curl -X POST https://app.zervixo.com/api/v1/otp/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "phone": "+966501234567",
    "purpose": "login",
    "expires_in": 300,
    "locale": "ar"
  }'

cURL — التحقق من OTP

curl -X POST https://app.zervixo.com/api/v1/otp/verify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "phone": "+966501234567",
    "code": "483921",
    "ref": "otp_01jd3k8m4v2xq6z"
  }'

PHP (Guzzle) — إرسال OTP

use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://app.zervixo.com/api/v1/',
    'headers' => [
        'Authorization' => 'Bearer ' . $apiKey,
        'Accept'        => 'application/json',
    ],
]);

$response = $client->post('otp/send', [
    'json' => [
        'phone'      => '+966501234567',
        'purpose'    => 'login',
        'expires_in' => 300,
        'locale'     => 'ar',
    ],
]);

$data = json_decode($response->getBody(), true);
echo $data['ref']; // store this for verify step

PHP (Guzzle) — التحقق من OTP

$response = $client->post('otp/verify', [
    'json' => [
        'phone' => '+966501234567',
        'code'  => $userEnteredCode,
        'ref'   => $ref,
    ],
]);

$data = json_decode($response->getBody(), true);

if ($data['verified']) {
    // proceed with login / registration
} else {
    // show "incorrect code" message to user
}