المصادقة

يجب أن يحمل كل طلب إلى واجهة علاقات البرمجية مفتاح API. يُعرّف المفتاح علاقات بالحساب الذي يخصه الطلب، وبعضو الفريق الذي يتصرف الطلب باسمه، وبأجزاء الواجهة البرمجية المسموح له باستخدامها. ويُرفض أي طلب بلا مفتاح صالح برمز الحالة 401.

يفتح مفتاح API بيانات حسابك لأي نظام يحمله، لذا يستحق إنشاؤه شيئاً من العناية: امنح كل مفتاح الإمكانيات التي يحتاجها تكاملك فقط، وأبقِه بعيداً عن أي شيفرة تعمل داخل المتصفح أو في تطبيق جوال، واستبدله قبل انتهاء صلاحيته حتى لا يتوقف تكاملك.

تشرح هذه الصفحة كيفية إنشاء المفاتيح واستخدامها وتجديدها وإلغائها من الإعدادات > التكاملات > واجهة التطبيق البرمجية.

المتطلبات

المتطلب التفاصيل
الخطة المفتاح الذي يفتح الواجهة البرمجية كاملة متاح في الخطط المدفوعة. أما مفتاح إرسال رموز التحقق عبر واتساب فيمكن إنشاؤه في كل الخطط، بما فيها الخطة المجانية. اطّلع على الخطط في صفحة الأسعار.
الصلاحيات عرض مفاتيح API لرؤية مفاتيحك، وإنشاء مفتاح API جديد لإنشائها وتجديدها، وإلغاء مفتاح API لإلغائها، وعرض سجل استخدام API لرؤية السجل أسفل الصفحة.
عدد المفاتيح يمكن لكل عضو في الفريق أن يملك مفتاحاً عاماً واحداً ومفتاحاً واحداً لرموز التحقق في كل حساب.
الصلاحية 180 يوماً من لحظة إنشاء المفتاح.

نوعان من المفاتيح

تصنّف علاقات المفاتيح بحسب الإمكانيات التي تحملها:

النوع الإمكانيات الخطة
مفتاح رموز التحقق broadcast-send-otp، ومعها current-user اختيارياً. ولا شيء غيرهما. كل الخطط
مفتاح عام أي مجموعة أخرى من الإمكانيات. الخطط المدفوعة

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

في الخطط المدفوعة يمكنك أن تملك النوعين معاً: مثلاً مفتاحاً لمزامنة نظام إدارة العملاء لديك، وآخر لصفحة تسجيل الدخول. القائمة الكاملة للإمكانيات، ونقاط النهاية التي تفتحها كل واحدة منها، موجودة في الصلاحيات والقدرات.

الخطوة 1: أنشئ مفتاحاً

  1. اضغط أيقونة الإعدادات، ثم انتقل إلى التكاملات > واجهة التطبيق البرمجية.

    تعرض الصفحة المفاتيح التي تملكها في هذا الحساب. تُظهر كل بطاقة اسم المفتاح، وتاريخ الإنشاء، وينتهي في، والحالة، والإمكانيات.



ApiKeys1-AR

  1. اضغط رمز جديد.
  2. أدخل في حقل الاسم اسماً يوضح الغرض من المفتاح، كاسم النظام الذي سيستخدمه. يظهر الاسم على بطاقة المفتاح وفي سجل استخدام الواجهة البرمجية.
  3. اختر من الإمكانيات كل ما يحتاجه التكامل. اكتب جزءاً من اسم الكيان بالإنجليزية، مثل contact، لتضييق القائمة.
  4. اضغط إنشاء.



ApiKeys2-AR

في الخطة المجانية، توضح النافذة أن خطتك تتيح إنشاء رمز لإرسال رموز التحقق، وتكون إمكانيتا مفتاح رموز التحقق محددتين مسبقاً، وهما الوحيدتان المتاحتان للاختيار.

يظهر زر رمز جديد باهتاً وغير قابل للضغط عندما تملك كل المفاتيح التي تتيحها خطتك.

{info} لا يمكن تغيير إمكانيات المفتاح بعد إنشائه. لإضافة إمكانية أو حذفها، ألغِ المفتاح وأنشئ مفتاحاً جديداً، ثم حدّث تكاملك.

الخطوة 2: انسخ المفتاح

فور إنشاء المفتاح تعرضه علاقات مرة واحدة فقط. اضغط أيقونة النسخ واحفظ المفتاح في مكان آمن، كمخزن الأسرار على خادمك.



ApiKeys3-AR

{danger.fa-close} لن تتمكن من رؤية المفتاح مجدداً بعد إغلاق هذه النافذة، فإن أضعته فجدّده لتحصل على مفتاح جديد. عامل المفتاح معاملة كلمة المرور: لا تشاركه مع تطبيقات أو أشخاص لا تثق بهم، ولا تضعه في صفحة ويب أو تطبيق جوال.

الخطوة 3: أرسل المفتاح مع كل طلب

مرّر المفتاح في ترويسة 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.

لاستبدال المفتاح دون انقطاع، جدّده:

  1. اضغط أيقونة تجديد على بطاقة المفتاح، ثم أكّد.
  2. انسخ المفتاح الجديد من النافذة كما في الخطوة 2.
  3. حدّث تكاملك بالمفتاح الجديد خلال 30 دقيقة.

يحمل المفتاح الجديد الاسم نفسه والإمكانيات نفسها، وتمتد صلاحيته 180 يوماً أخرى. أما المفتاح القديم فيبقى فعالاً 30 دقيقة حتى لا تفشل الطلبات التي في طريقها، ثم يتوقف.

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

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

إذا انتهت صلاحية المفتاح بالفعل، فجدّده لتحصل على مفتاح جديد بالإمكانيات نفسها، ثم ألغِ المفتاح المنتهي.

إلغاء مفتاح

ألغِ المفتاح عندما تستغني عن التكامل الذي يستخدمه، أو عندما تشك في تسرّبه، أو عندما لا يعود عضو الفريق الذي أنشأه بحاجة إليه.

  1. اضغط أيقونة إلغاء على بطاقة المفتاح.
  2. اضغط تأكيد.

يتوقف المفتاح فوراً، ويُرفض كل طلب يُرسل به برمز الحالة 401. ولا يمكن التراجع عن الإلغاء.

سجل استخدام الواجهة البرمجية

أسفل المفاتيح، يعرض سجل استخدام الواجهة البرمجية الطلبات المرسلة بمفاتيح الحساب خلال آخر 7 أيام: اسم المفتاح، ورابط الواجهة البرمجية، ومحتوى الطلب، وطريقة الطلب، وحالة الطلب، وتاريخ الإنشاء. استخدمه للتأكد من أن التكامل يستدعي ما تتوقعه، وللعثور على الطلبات التي فشلت.

يشمل السجل مفاتيح جميع أعضاء الفريق في الحساب، ويراه كل من يملك صلاحية عرض سجل استخدام API. ويعرض عمود محتوى الطلب نص الطلب كما أرسله تكاملك، لذا قد يتضمن بيانات شخصية كالأسماء وأرقام الهواتف. امنح هذه الصلاحية لمن يحتاجها فقط.

تُحذف السجلات التي مضى عليها أكثر من 7 أيام.

نقاط يجب مراعاتها

  • يرى كل عضو في الفريق مفاتيحه فقط. لا تظهر مفاتيحك في صفحة زميلك، ولا يستطيع تجديد المفتاح أو إلغاءه إلا عضو الفريق الذي أنشأه.
  • المفتاح يتبع عضو الفريق. إذا عُطّل عضو الفريق الذي أنشأ المفتاح في الحساب، تُرفض الطلبات المرسلة بالمفتاح برمز الحالة 423 حتى يعود العضو نشطاً. ويحدث الأمر نفسه ما دام الحساب مجدولاً للحذف.
  • الإمكانيات لا تحل محل الصلاحيات. اختيار إمكانية لا يمنح الصلاحية المقابلة لها. فإذا رُفض طلب برمز الحالة 403 رغم أن المفتاح يحمل الإمكانية، فراجع صلاحيات عضو الفريق.
  • مفتاح لكل تكامل أسهل في الإدارة. الاسم الواضح لكل مفتاح يجعل سجل الاستخدام مقروءاً، ويتيح لك إلغاء تكامل واحد دون المساس بغيره، في حدود عدد المفاتيح الذي تتيحه خطتك.
  • حد الطلبات. تُحتسب الطلبات لكل عضو في الفريق أياً كان المفتاح الذي يستخدمه. راجع النظرة العامة.