يجب أن يحمل كل طلب إلى واجهة علاقات البرمجية مفتاح API. يُعرّف المفتاح علاقات بالحساب الذي يخصه الطلب،
وبعضو الفريق الذي يتصرف الطلب باسمه، وبأجزاء الواجهة البرمجية المسموح له باستخدامها. ويُرفض أي طلب بلا مفتاح صالح
برمز الحالة 401.
يفتح مفتاح API بيانات حسابك لأي نظام يحمله، لذا يستحق إنشاؤه شيئاً من العناية: امنح كل مفتاح الإمكانيات التي يحتاجها تكاملك فقط، وأبقِه بعيداً عن أي شيفرة تعمل داخل المتصفح أو في تطبيق جوال، واستبدله قبل انتهاء صلاحيته حتى لا يتوقف تكاملك.
تشرح هذه الصفحة كيفية إنشاء المفاتيح واستخدامها وتجديدها وإلغائها من الإعدادات > التكاملات > واجهة التطبيق البرمجية.
| المتطلب | التفاصيل |
|---|---|
| الخطة | المفتاح الذي يفتح الواجهة البرمجية كاملة متاح في الخطط المدفوعة. أما مفتاح إرسال رموز التحقق عبر واتساب فيمكن إنشاؤه في كل الخطط، بما فيها الخطة المجانية. اطّلع على الخطط في صفحة الأسعار. |
| الصلاحيات | عرض مفاتيح API لرؤية مفاتيحك، وإنشاء مفتاح API جديد لإنشائها وتجديدها، وإلغاء مفتاح API لإلغائها، وعرض سجل استخدام API لرؤية السجل أسفل الصفحة. |
| عدد المفاتيح | يمكن لكل عضو في الفريق أن يملك مفتاحاً عاماً واحداً ومفتاحاً واحداً لرموز التحقق في كل حساب. |
| الصلاحية | 180 يوماً من لحظة إنشاء المفتاح. |
تصنّف علاقات المفاتيح بحسب الإمكانيات التي تحملها:
| النوع | الإمكانيات | الخطة |
|---|---|---|
| مفتاح رموز التحقق | broadcast-send-otp، ومعها current-user اختيارياً. ولا شيء غيرهما. |
كل الخطط |
| مفتاح عام | أي مجموعة أخرى من الإمكانيات. | الخطط المدفوعة |
لا يستطيع مفتاح رموز التحقق إلا إرسال رموز التحقق عبر واتساب والتحقق منها، وقراءة المستخدم الحالي. تُدفع هذه الرسائل من رصيد رموز التحقق لا من حصة الرسائل في خطتك، ولهذا تتيحه كل الخطط.
في الخطط المدفوعة يمكنك أن تملك النوعين معاً: مثلاً مفتاحاً لمزامنة نظام إدارة العملاء لديك، وآخر لصفحة تسجيل الدخول. القائمة الكاملة للإمكانيات، ونقاط النهاية التي تفتحها كل واحدة منها، موجودة في الصلاحيات والقدرات.
اضغط أيقونة الإعدادات، ثم انتقل إلى التكاملات > واجهة التطبيق البرمجية.
تعرض الصفحة المفاتيح التي تملكها في هذا الحساب. تُظهر كل بطاقة اسم المفتاح، وتاريخ الإنشاء، وينتهي في، والحالة، والإمكانيات.


في الخطة المجانية، توضح النافذة أن خطتك تتيح إنشاء رمز لإرسال رموز التحقق، وتكون إمكانيتا مفتاح رموز التحقق محددتين مسبقاً، وهما الوحيدتان المتاحتان للاختيار.
يظهر زر رمز جديد باهتاً وغير قابل للضغط عندما تملك كل المفاتيح التي تتيحها خطتك.
{info} لا يمكن تغيير إمكانيات المفتاح بعد إنشائه. لإضافة إمكانية أو حذفها، ألغِ المفتاح وأنشئ مفتاحاً جديداً، ثم حدّث تكاملك.
فور إنشاء المفتاح تعرضه علاقات مرة واحدة فقط. اضغط أيقونة النسخ واحفظ المفتاح في مكان آمن، كمخزن الأسرار على خادمك.

{danger.fa-close} لن تتمكن من رؤية المفتاح مجدداً بعد إغلاق هذه النافذة، فإن أضعته فجدّده لتحصل على مفتاح جديد. عامل المفتاح معاملة كلمة المرور: لا تشاركه مع تطبيقات أو أشخاص لا تثق بهم، ولا تضعه في صفحة ويب أو تطبيق جوال.
مرّر المفتاح في ترويسة Authorization على شكل رمز Bearer:
Authorization: Bearer {your-api-token}
ويبدو الطلب الكامل هكذا:
curl https://app.alaaqat.com/api/me \
-H "Authorization: Bearer {your-api-token}" \
-H "Accept: application/json"
ينتمي المفتاح إلى الحساب الذي كنت تعمل فيه عند إنشائه، وكل طلب يُرسل به يقرأ بيانات ذلك الحساب ويعدّلها فقط. فإن كنت تدير عدة حسابات، فأنشئ مفتاحاً في كل منها.
ويتصرف المفتاح أيضاً باسمك، أي باسم عضو الفريق الذي أنشأه. لا ينجح الطلب إلا إذا كان المفتاح يحمل الإمكانية التي تحتاجها نقطة النهاية وكانت صلاحياتك في الحساب تسمح بالإجراء. وتُرجع نقاط نهاية القوائم السجلات التي تراها في التطبيق فقط. راجع الصلاحيات والقدرات.
صلاحية المفتاح 180 يوماً. يتحول تاريخ ينتهي في على بطاقته إلى اللون الأحمر عندما يتبقى أقل من 30 يوماً، وترسل
لك علاقات بريداً إلكترونياً قبل الموعد بنحو أسبوعين، ثم بأسبوع، ثم بيوم واحد. وعند انتهاء الصلاحية تصبح
الحالة غير نشط، ويُرفض كل طلب يُرسل بالمفتاح برمز الحالة 401.
لاستبدال المفتاح دون انقطاع، جدّده:
يحمل المفتاح الجديد الاسم نفسه والإمكانيات نفسها، وتمتد صلاحيته 180 يوماً أخرى. أما المفتاح القديم فيبقى فعالاً 30 دقيقة حتى لا تفشل الطلبات التي في طريقها، ثم يتوقف.
ستظهر بعدها بطاقتان بالاسم نفسه، والمفتاح الجديد هو صاحب تاريخ ينتهي في الأبعد. وبعد أن ينتقل تكاملك إلى المفتاح الجديد، ألغِ البطاقة القديمة.
{warning} ما دمت لم تلغِ البطاقة القديمة، فلن تستطيع تجديد ذلك المفتاح مرة أخرى، ولا إنشاء مفتاح آخر من النوع نفسه: فالمفتاح القديم يبقى محسوباً ضمن مفاتيحك حتى بعد توقفه. وعند محاولة التجديد تظهر الرسالة "لا يمكنك إنشاء المزيد من الرموز، قم بإزالة الرموز القديمة أولاً."
إذا انتهت صلاحية المفتاح بالفعل، فجدّده لتحصل على مفتاح جديد بالإمكانيات نفسها، ثم ألغِ المفتاح المنتهي.
ألغِ المفتاح عندما تستغني عن التكامل الذي يستخدمه، أو عندما تشك في تسرّبه، أو عندما لا يعود عضو الفريق الذي أنشأه بحاجة إليه.
يتوقف المفتاح فوراً، ويُرفض كل طلب يُرسل به برمز الحالة 401. ولا يمكن التراجع عن الإلغاء.
أسفل المفاتيح، يعرض سجل استخدام الواجهة البرمجية الطلبات المرسلة بمفاتيح الحساب خلال آخر 7 أيام: اسم المفتاح، ورابط الواجهة البرمجية، ومحتوى الطلب، وطريقة الطلب، وحالة الطلب، وتاريخ الإنشاء. استخدمه للتأكد من أن التكامل يستدعي ما تتوقعه، وللعثور على الطلبات التي فشلت.
يشمل السجل مفاتيح جميع أعضاء الفريق في الحساب، ويراه كل من يملك صلاحية عرض سجل استخدام API. ويعرض عمود محتوى الطلب نص الطلب كما أرسله تكاملك، لذا قد يتضمن بيانات شخصية كالأسماء وأرقام الهواتف. امنح هذه الصلاحية لمن يحتاجها فقط.
تُحذف السجلات التي مضى عليها أكثر من 7 أيام.
423 حتى يعود العضو نشطاً. ويحدث الأمر نفسه ما دام الحساب مجدولاً للحذف.403
رغم أن المفتاح يحمل الإمكانية، فراجع صلاحيات عضو الفريق.