17. واجهة API للتكامل ومفاتيح API

تتيح لك واجهة التكامل البرمجية (API) أن يقرأ برنامجك أو جدولك أو نصّك البرمجي بيانات مشاريعك آليًا: قائمة المشاريع، وجداول الكابلات والمواد، وجدول الدوائر وقائمة الأطراف للوحات التوزيع، وحصر الكميات، وتكوين حزمة المخططات. الواجهة للقراءة فقط: فهي لا تغيّر المخطط ولا المشروع.

من يمكنه الحصول على مفتاح API

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

يرى المفتاح المشاريع نفسها التي تراها أنت: مشاريعك الخاصة، وعند الطلب تلك التي شُورِكت معك. أما بالنسبة إلى مشروع مشترك، فلا تُعاد الجداول والحصر إلا إذا كانت المشاركة تسمح بالتصدير.

إنشاء مفتاح

في بطاقة مفاتيح API بصفحة الملف الشخصي، انقر زر مفتاح جديد.
أعطِ المفتاح اسمًا (مثلًا اسم البرنامج الذي سيستخدمه).
اختر النطاق: قراءة المشاريع تتيح قائمة المشاريع وبيانات المشروع، وقراءة المستندات تتيح الجداول والحصر وحزمة المخططات. اختر فقط ما يحتاجه البرنامج فعلًا.
اختر الانتهاء: 30 أو 90 أو 365 يومًا. يتوقف المفتاح المنتهي عن العمل؛ أنشئ مفتاحًا جديدًا بدلًا منه.
أدخل كلمة المرور الحالية (الحساب الذي لا يملك كلمة مرور يحتاج إلى تسجيل دخول حديث). عند إنشاء أول مفتاح، وافق على شروط استخدام API.

بعد الإنشاء يظهر المفتاح مرة واحدة فقط: انسخه واحفظه في مكان آمن. وفي ما بعد تعرض القائمة بادئته فقط (avk_…) مع تاريخَي الإنشاء والانتهاء وآخر استخدام وعدد الاستدعاءات. كما نرسل إشعارًا بالبريد الإلكتروني عن المفتاح الجديد (دون المفتاح نفسه).

إلغاء مفتاح

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

نصائح أمنية

تعامل مع المفتاح كما تتعامل مع كلمة مرورك: كل من يعرفه يستطيع قراءة مشاريعك ضمن نطاقه.
احتفظ به في مخزن أسرار (مدير كلمات المرور، أو متغير بيئة على الخادم، أو متغير سري في CI) وليس في الشيفرة المصدرية: لا تضعه في مستودع git، ولا في جدول مشترك ولا في بريد إلكتروني.
لا تستخدمه في شيفرة تعمل داخل المتصفح (صفحة ويب، إضافة متصفح): فهناك يستطيع أي شخص قراءته. مكان المفتاح هو الخادم أو نص برمجي أو برنامج سطح مكتب.
أعطِ كل برنامج مفتاحه الخاص بأضيق نطاق ممكن ومدة انتهاء قصيرة، حتى لا يوقف إلغاء مفتاح واحد أي شيء آخر.

الاستخدام من برنامج

يُرسل المفتاح في ترويسة الطلب بوصفه رمز Bearer: Authorization: Bearer avk_…. تقع نقاط النهاية تحت /api/v1/ (مثل GET /api/v1/projects) وتردّ بصيغة JSON. والوصف الكامل بصيغة OpenAPI متاح على /api/v1/openapi.json؛ ويمكن لمعظم أدوات المطورين استيراده.

عدد الاستدعاءات محدود لكل مفتاح ولكل حساب (افتراضيًا 60 في الدقيقة و10٬000 في اليوم)؛ وعند تجاوز ذلك يردّ الخادم بالرمز 429، فانتظر قليلًا. تسجيل الدخول إلى الموقع (ملف تعريف الارتباط) لا يفتح الواجهة البرمجية، والمفتاح لا يسجّل دخولك إلى واجهة الويب.