رموز التحقق عبر الواتساب

يرسل تأكيد رموز تسجيل الدخول عبر الواتساب من رقم تجاري موثّق. يبقى مستخدمين تطبيقك عندك: تأكيد يوصل الرمز، ويتحقق منه أيضًا إن أردت. وشركتك الأولى تأتي مع 5 رموز مجانًا.

قبل أن تبدأ#

1. أنشئ حسابًا، وأدخل اسم الشركة، ثم أضف تطبيقًا من لوحة التحكم.
2. افتح الإعدادات ← إعدادات OTP ← الربط البرمجي — Authorization وأنشئ مفتاحًا. هذا هو المفتاح السري المستخدم بالشكل Authorization: Key <key>، ويظهر كاملًا مرة واحدة فقط. مع مفتاح التطبيق يكون target اختياريًا إلا إذا أردت تحديد فرع.
3. من رصيد الرسائل انقل رصيد OTP من محفظة الشركة إلى هذا التطبيق. يبدأ التطبيق الجديد برصيد صفر ولا يمكنه الإرسال قبل تعبئته.
4. احفظ المفتاح على خادمك، ولا تضعه أبدًا داخل تطبيق أو صفحة ويب.

وضع التوصيل (الافتراضي)#

خادمك يولّد الرمز ويتحقق منه، وتأكيد يوصله فقط.

curl https://takeed-iq.com/api/v1/otp/send \
  -H "Authorization: Key $TAKEED_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "+9647701234567", "code": "482913", "user_ip": "203.0.113.7"}'

يردّ تأكيد فورًا بـ 202 Accepted ثم يرسل الرمز في الخلفية:

{
  "id": "01JAB3K9Q7X2M4N8P6R5T0VWYZ",
  "mode": "deliver",
  "status": "queued",
  "phone": "+964•••••••567",
  "target": "shop",
  "verified": false,
  "expires_at": null,
  "error": null,
  "created_at": "2026-10-15T09:41:00+00:00",
  "sent_at": null,
  "delivered_at": null,
  "read_at": null,
  "verified_at": null
}

الرمز نفسه لا يُخزَّن أبدًا. احتفظ بالـ id لتتابع الرمز.

تعيد الواجهة البرمجية الأوقات بصيغة ISO 8601 وبتوقيت UTC ‏(+00:00) حتى لا يختلف تفسيرها بين الخوادم، بينما تعرضها لوحة التحكم بتوقيت بغداد (Asia/Baghdad).

الوضع المُدار#

يولّد تأكيد الرمز (6 أرقام، صالح 5 دقائق، و5 محاولات افتراضيًا)، ويرسله، ويتحقق منه. فعّله من لوحة التحكم: افتح التطبيق، ثم تبويب OTP، ثم الوضع المُدار.

1. أرسل الطلب بدون code:

   bash

   curl https://takeed-iq.com/api/v1/otp/send \
     -H "Authorization: Key $TAKEED_KEY" \
     -H "Content-Type: application/json" \
     -d '{"phone": "+9647701234567", "user_ip": "203.0.113.7"}'

2. يحمل ردّ 202 القيمة "mode": "managed" ومعها id وexpires_at. احفظ الـ id مع محاولة تسجيل الدخول.

3. عندما يكتب المستخدم الرمز، أرسله مع الـ id:

   bash

   curl https://takeed-iq.com/api/v1/otp/verify \
     -H "Authorization: Key $TAKEED_KEY" \
     -H "Content-Type: application/json" \
     -d '{"id": "01JAB3K9Q7X2M4N8P6R5T0VWYZ", "code": "482913"}'

الرمز الصحيح يردّ بـ 200 ومعه "status": "verified". وإلا فالردّ يذكر السبب: code_invalid (رمز خاطئ)، أو too_many_attempts، أو code_expired، أو already_verified. كل الأسباب في رموز الأخطاء.

الحقول#

متابعة الرمز#

اسأل عنه بـ GET /api/v1/otp/{id}، أو دع تأكيد يستدعي الـ Webhook الخاص بك كلما تقدّم الرمز خطوة:

الـ Webhook#

ضع الرابط (HTTPS) في لوحة التحكم: تبويب عام في التطبيق، ثم رابط Webhook. وأنشئ سرّ التوقيع من تبويب الأمان. كل حدث يصل بطلب POST بهذا المحتوى، حيث يحمل data.otp كل حقول ردّ الواجهة البرمجية أعلاه (بعضها فقط معروض هنا):

{
  "event": "otp.delivered",
  "created_at": "2026-10-15T09:41:03+00:00",
  "data": {
    "otp": {"id": "01JAB3K9Q7X2M4N8P6R5T0VWYZ", "mode": "deliver", "status": "delivered", "target": "shop"}
  }
}

ويحمل كل طلب ترويسة توقيع بهذا الشكل:

X-Takeed-Signature: t=<unix time>,v1=<HMAC-SHA256 of "<t>.<body>" with the webhook secret>

تحقّق منها، وارفض الطوابع الزمنية القديمة:

// $header: the X-Takeed-Signature value. $body: the raw request body.
[$t, $v1] = sscanf($header, 't=%d,v1=%s');
$expected = hash_hmac('sha256', $t.'.'.$body, $secret);
$ok = hash_equals($expected, (string) $v1) && abs(time() - $t) < 300;

الحماية#

يفرض تأكيد على كل تطبيق (ويمكنك تعديلها من تبويب OTP في التطبيق):

• لكل رقم: 60 ثانية بين رمز وآخر، و5 رموز في الساعة؛
• لكل عنوان IP: ‏30 طلبًا في الساعة، وبعد 10 طلبات مرفوضة خلال ساعة يُحظر العنوان بقية تلك الساعة؛
• لكل تطبيق: 100 رمز في الدقيقة؛
• قائمة بمفاتيح الدول المسموح بها.

الطلب المرفوض يردّ بسببه (phone_rate_limited، ip_blocked، blocked_country…)، وتعرضه لوحة التحكم بالسبب نفسه.

صياغتك الخاصة#

الرسالة الافتراضية هي نص التحقق الرسمي في الواتساب المعروض أعلاه. ويمكن أن تقول ما تريد بدلًا منه: اسم علامتك، أو اسم الفرع، أو الدقائق المتبقية. اطلب من فريق تأكيد صياغة لشركتك، أو لتطبيق واحد، أو لفرع واحد؛ ويمكنها استخدام {code} و{name} (اسم الفرع، أو التطبيق) و{minutes}. يوافق الواتساب على كل صياغة قبل استخدامها، والأكثر تحديدًا هي التي تُستخدم: الفرع، ثم التطبيق، ثم الشركة.

الرصيد#

كل رمز يقبله الواتساب يستهلك رصيدًا واحدًا من رصيد OTP الخاص بالتطبيق، سواء تحقق المستخدم منه أم لا. وإذا فشل مزوّد الخدمة في قبول الرسالة يُعاد الرصيد إلى التطبيق نفسه. عندما يصبح رصيد التطبيق صفرًا تُرفض الطلبات بالخطأ application_credit_exhausted ‏(402)، وعندها انقل إليه رصيدًا جديدًا من رصيد الرسائل. وإذا لم يتوفر رصيد قابل للتوزيع في محفظة الشركة، فعلى مسؤولها الحصول على رصيد أولًا. الإشعارات لا تستهلك هذا الرصيد.

معرفة عدد رسائل OTP المتاحة#

يستطيع خادم مشروعك قراءة الرصيد الحالي لتطبيقه باستخدام مفتاح Authorization نفسه المستخدم في الإرسال:

curl https://takeed-iq.com/api/v1/otp/balance \
  -H "Authorization: Key $TAKEED_KEY"

{
  "object": "otp_balance",
  "app_id": "971ea6e3-2f83-4a5c-a501-1f7a285d06d5",
  "target": "my-app",
  "available_messages": 1000
}

الحقل available_messages هو عدد رسائل OTP المتبقية في محفظة هذا التطبيق لحظة الطلب. هذه لقطة مباشرة وقد تتغير عند قبول إرسال متزامن أو إعادة رصيد إرسال فاشل. كل رسالة OTP يقبلها واتساب تستهلك رسالة واحدة، أما إشعارات التطبيقات فمجانية ولا تغيّر هذا العدد. لا تضع هذا الاستدعاء أو مفتاح Authorization داخل كود المتصفح أو تطبيق الهاتف؛ استدعه من خادم مشروعك فقط.

مفتاح التطبيق لا يحتاج أي معاملات. أما مفتاح الشركة العام القديم فيحدد التطبيق بواسطة ?target=my-app، ويمكن تحديد فرع مثل ?target=my-app:north لكن الفروع تشترك في محفظة التطبيق. تُرسل الاستجابة مع Cache-Control: private, no-store وتخضع للحد المعتاد لطلبات مفتاح API.