طلب كود الربط (تسجيل الدخول بالهاتف)

يطلب كود ربط للمصادقة القائمة على الهاتف في واتساب (بأسلوب OTP).

POST

https://api.wawp.net/v2/auth/request-code?access_token=YOUR_ACCESS_TOKEN&instance_id=Your_Instance_ID&phone_number=201145202826

تسجيل الدخول مطلوب

سجل الدخول لاستبدال المعرفات (Instance ID) ورمز الوصول (Access Token) بمعلومات حسابك الحقيقي لاختبار ال API مباشرة.

تسجيل الدخول

اختبار /v2/auth/request-code

يدعم

POST

لا توجد معاملات استعلام مطلوبة

هذه النهاية الطرفية لا تتوقع بيانات في الرابط.

وقت الانتظار

يستغرق توليد واتساب من 2 إلى 5 ثوانٍ. يجب أن تظهر واجهة المستخدم مؤشر تحميل.

حد المعدل

لا تطلب الرموز بشكل متكرر. قد يقوم واتساب بحظر الرقم مؤقتًا.

توصيات

استخدم هذا كحل بديل للمستخدمين الذين لديهم كاميرات معطلة.
اعرض الكود المكون من 8 أحرف بخط كبير وواضح مع عد تنازلي.
تأكد من أن الجلسة في حالة 'SCAN_QR_CODE' قبل الطلب.

الربط بدون واجهة: قوة أكواد الاقتران عبر الهاتف

يُعد الرابط /v2/auth/request-code نقلة نوعية في أتمتة واتساب، وهو مصمم خصيصاً للبيئات التي يكون فيها مسح كود QR مستحيلاً فيزيائياً أو غير مريح تقنياً. تسمح لك هذه الطريقة بربط حساب واتساب بنسخة Wawp عن طريق إدخال كود أبجدي رقمي مكون من 8 رموز مباشرة في تطبيق واتساب على الهاتف.

🏗️ هندسة المصافحة الثنائية

عند استدعاء هذا الرابط مع phone_number، تبدأ Wawp في تنسيق خلفي معقد:

الاستهداف: ينشئ المحرك اتصالاً بخوادم واتساب و"يعلن" رغبته في الارتباط برقم الهاتف المقدم.
إنشاء الكود: تتفاوض بنية Wawp التحتية على كود اقتران فريد وقصير الأجل مكون من 8 رموز (مثال: ABCD-1234).
ربط الجلسة: يتم ربط الكود الناتج تشفيرياً بـ instance_id الخاص بك.
الانتظار التفاعلي: يدخل المحرك في وضع "الاستماع التفاعلي"، بانتظار كتابة المستخدم لهذا الكود في جهازه المحمول.

🛡️ أفضل الممارسات الاستراتيجية

1. توحيد أرقام الهواتف عالمياً

يتبع واتساب تنسيقاً دولياً صارماً للأرقام. ستفشل العملية إذا كان التنسيق غير صحيح.

إجراء المطور: قبل تمرير رقم الهاتف، قم بتوحيده برمجياً:
- قم بإزالة جميع المسافات والواصلات والأقواس.
- قم بإزالة أي بادئة + أو 00.
- تأكد من وجود رمز الدولة (مثال: استخدم 201112223333 بدلاً من 01112223333).

2. بناء تجربة مستخدم بأسلوب OTP

بما أن المستخدم يحتاج لإدخال الكود في هاتفه، فإن تصميم واجهة المستخدم الخاصة بك أمر بالغ الأهمية.

سير العمل:
- اعرض الكود المكون من 8 رموز بخط كبير وعريض.
- وفر مؤقت عد تنازلي (الأكواد صالحة لمدة تقريبية 2-5 دقائق).
- أضف دليلاً بسيطاً للمستخدم: واتساب -> الإعدادات -> الأجهزة المرتبطة -> الربط باستخدام رقم الهاتف.

3. التعامل مع حالة 422 "غير جاهز"

إذا كان المحرك قيد التشغيل للتو، فقد لا يكون جاهزاً لإنشاء الكود فوراً.

الاستجابة: ستتلقى خطأ 422 Session Status Not Expected. هذا يشير إلى أن المحرك في مرحلة "التسخين". انتظر 10 ثوانٍ قبل السماح للمستخدم بالنقر على زر "إنشاء الكود" مرة أخرى.

💡 حالات الاستخدام القياسية

أ. تهيئة الخوادم بدون واجهة رسومية (Headless)

للعملاء الذين يديرون مئات الحسابات على خوادم لينكس معزولة بدون شاشات، تعد طريقة كود الاقتران هي الطريقة الوحيدة للتوسع.

ب. الدعم الفني والربط عن بُعد

إذا كان العميل يواجه صعوبة في مسح كود QR (بسبب كاميرا تالفة أو ضعف إضاءة الشاشة)، يمكن لموظف الدعم إنشاء كود اقتران وإملائه للعميل هاتفياً، مما يضمن نجاح الربط في ثوانٍ.

⚠️ الأخطاء الشائعة

إساءة استخدام حد المحاولات: لدى واتساب حد داخلي لعدد مرات طلب أكواد الاقتران. طلب الكود أكثر من 3-5 مرات في وقت قصير قد يؤدي لحظر الميزة مؤقتاً لهذا الرقم.
الحالة غير الصحيحة: يمكنك طلب الكود فقط إذا كانت حالة الجلسة هي SCAN_QR_CODE.

ملخص المسؤوليات:

بدء بروتوكول الاقتران عبر الهاتف.
استرداد كود ربط فريد مكون من 8 رموز.
تهيئة المحرك للاستماع لحقن أوراق الاعتماد عن بُعد.
دعم عمليات الربط "عبر الهاتف فقط" في الحالات التي لا تُستخدم فيها الكاميرات.

البارامترات

قم بتهيئة المعاملات المطلوبة للتفاعل مع نقطة النهاية هذه. جميع وسائط الاستعلام والبيانات مدرجة أدناه مع تفاصيلها.

محتوى الطلب

يرسل كـ JSON

	`string`		معرف النسخة المكون من 12 رمزاً مثال:
	`string`		مفتاح الوصول الخاص بـ API مثال:
	`string`		رقم الهاتف المراد ربطه (مثال: 201145202826) مثال:

أمثلة الكود

استخدم أمثلة الكود الجاهزة لدمج واجهة برمجة التطبيقات (API) في مشروعك بسرعة وكفاءة. اختر لغة البرمجة والمكتبة التي تفضلها.

1const baseUrl = "https://api.wawp.net";
2const endpoint = "/v2/auth/request-code";
3const params = new URLSearchParams({
4  "instance_id": "Your_Instance_ID",
5  "access_token": "YOUR_ACCESS_TOKEN"
6}).toString();
7const body = {
8  "phone_number": "201145202826"
9};
10
11fetch(`${baseUrl}${endpoint}${params ? '?' + params : ''}`, {
12  method: "POST",
13  headers: { "Content-Type": "application/json" },
14  body: JSON.stringify(body)
15})
16  .then(async (response) => {
17    if (response.ok) {
18      const data = await response.json();
19      console.log("Success:", data);
20      return data;
21    }
22    
23    // Error Handling
24    if (response.status === 400) {
25      console.error("Error 400: طلب غير صالح - معاملات مطلوبة مفقودة");
26    }
27    if (response.status === 400) {
28      console.error("Error 400: طلب غير صالح (تنسيق XML)");
29    }
30    if (response.status === 400) {
31      console.error("Error 400: طلب غير صالح (نص عادي)");
32    }
33    if (response.status === 401) {
34      console.error("Error 401: غير مصرح - مفتاح الوصول غير صالح أو مفقود");
35    }
36    if (response.status === 401) {
37      console.error("Error 401: غير مصرح (تنسيق XML)");
38    }
39    if (response.status === 404) {
40      console.error("Error 404: غير موجود - الجلسة غير موجودة");
41    }
42    if (response.status === 404) {
43      console.error("Error 404: غير موجود (تنسيق XML)");
44    }
45    if (response.status === 500) {
46      console.error("Error 500: خطأ في الخادم الداخلي - فشل غير متوقع");
47    }
48    if (response.status === 500) {
49      console.error("Error 500: خطأ في الخادم الداخلي (HTML)");
50    }
51    if (response.status === 502) {
52      console.error("Error 502: بوابة غير صالحة - فشل الاتصال بالخادم الرئيسي");
53    }
54    if (response.status === 502) {
55      console.error("Error 502: بوابة غير صالحة (تنسيق XML)");
56    }
57    if (response.status === 422) {
58      console.error("Error 422: Unprocessable Entity - Session Status Mismatch");
59    }
60
61    const errorText = await response.text();
62    console.error(`Error ${response.status}: ${errorText}`);
63  })
64  .catch((error) => console.error("Network Error:", error));

عينات تفاعليةUTF-8

Ln 64, Col 1javascript

الردود المتوقعة

استكشف كافة الردود والنتائج المحتملة من الخادم. قمنا بتوثيق كل كود حالة (Status Code) مع أمثلة للبيانات لتسهيل معالجة الأخطاء والنجاح.

تم إنشاء كود الربط بنجاح وهوا جاهز للاستخدام.

3 نسخ

النوع:

application/json

string *

Example

{
"code": "ABCD-1234"
}

طلب غير صالح - معاملات مطلوبة مفقودة

3 نسخ

غير مصرح - مفتاح الوصول غير صالح أو مفقود

2 نسخ

Command Palette

Search for a command to run...