مفاتيح API وواجهة API العامة

فيمَ يُستخدم المفتاح

يتيح مفتاح API لكود مساحة العمل نفسه، سواء كان سكربتًا أو خادمًا أو منتجًا آخر، أن يقرأ مشاريعها وينشئها ويعدّلها، وأن يقرأ مهامها ويضيف مهام، من دون أن يسجّل أحد الدخول. كل مفتاح يتبع مساحة عمل واحدة، ويحمل الصلاحيات المختارة عند إنشائه، ويُرسل رمز حامل (bearer token) إلى API العامة تحت /api/v1.

• يظهر المفتاح الكامل مرة واحدة، عند إنشائه. تحتفظ API بتجزئة SHA-256 له وببادئة قصيرة مثل nst_live_3f9a فقط، لذلك لا يمكن عرض مفتاح ضائع مرة أخرى: أبطله وأنشئ مفتاحًا آخر.
• كل استدعاء بمفتاح يُحتسب ضمن طلبات API لمساحة العمل في صفحة الفوترة، ويحدّث آخر استخدام للمفتاح.
• تمنح البيانات الأولية مفتاحًا واحدًا لكل من Forma Studio وMonogram حتى لا تكون القائمة فارغة. لم تُعرض أسرارهما قط، لذلك لا تصادقان أي شيء: أنشئ مفتاحك الخاص لتجربة API.

إنشاء مفتاح

1. 01

   افتح تبويب مفاتيح API

   في لوحة التحكم، افتح الإعدادات، ثم مفاتيح API، واضغط إنشاء مفتاح. يظهر التبويب فقط للدور الذي يملك keys.manage.
2. 02

   سمِّه واختر ما يُسمح له به

   أعطه اسم المفتاح، مثل «خادم الإنتاج»، وحدّد ما يُسمح للمفتاح به تحت «ما يُسمح للمفتاح به». قراءة المشاريع وقراءة المهام محددتان في البداية.
3. 03

   انسخ المفتاح السري

   «انسخ المفتاح السري الآن»: يعرض مربع الحوار المفتاح الكامل مرة واحدة، مع نسخ المفتاح. احفظه في مدير الأسرار لديك، ثم اضغط حفظته. إغلاق مربع الحوار ينسيه.

لا تستطيع مساحة العمل المتأخرة الدفع بعد انتهاء مهلة السماح، أو الملغاة، إنشاء مفاتيح: انظر دفعة فاشلة.

إبطال مفتاح

اضغط إبطال في صف المفتاح وأكّد بـ إبطال المفتاح: «سيتوقف فورًا كل ما يستخدم هذا المفتاح. لا يمكن التراجع عن ذلك.» يبقى المفتاح المُبطل في القائمة، عليه علامة مُبطل، أسفل المفاتيح النشطة. يُسجَّل إنشاء المفتاح وإبطاله في سجل نشاط مساحة العمل.

استدعاء API بمفتاح

أرسل المفتاح في الترويسة Authorization: Bearer مع كل طلب. للردود الغلاف نفسه الذي في بقية API، وهو { "success": true, "data": ..., "message": "" }.

اعرض مشاريع مساحة العمل، الأحدث تغييرًا أولًا، بحد أقصى 100:

curl http://localhost:8000/api/v1/projects -H "Authorization: Bearer <your key>"

اعرض مهام مشروع واحد، بترتيب اللوحة، بمعرّف المشروع من تلك القائمة (مثل prj_01):

curl http://localhost:8000/api/v1/projects/prj_01/tasks -H "Authorization: Bearer <your key>"

أضف مهمة. العنوان بالإنجليزية وحده مطلوب؛ وstatus هي backlog (الافتراضية) أو in_progress أو review أو done، وpriority هي low أو normal أو high، وdueDate تُكتب بالصيغة YYYY-MM-DD:

curl -X POST http://localhost:8000/api/v1/projects/prj_01/tasks \
  -H "Authorization: Bearer <your key>" -H "Content-Type: application/json" \
  -d '{"translations":{"en":{"title":"Check the launch email"}},"priority":"high"}'

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

أنشئ مشروعًا أو غيّر واحدًا بالحقول نفسها في درج المشروع بلوحة التحكم: translations (الاسم name بالإنجليزية مطلوب، حتى 120 حرفًا، وdescription اختياري)، واختياريًا status (in_progress أو review أو blocked أو completed) وownerId (عضو) وdueDate وprogress (من 0 إلى 100):

curl -X POST http://localhost:8000/api/v1/projects \
  -H "Authorization: Bearer <your key>" -H "Content-Type: application/json" \
  -d '{"translations":{"en":{"name":"Launch site"}},"status":"in_progress"}'

PATCH /api/v1/projects/<id> يقبل أيًّا من الحقول نفسها. تعمل كل كتابة باسم منشئ المفتاح، مع فحوصات لوحة التحكم: يجب أن يظل المنشئ يملك projects.write في مساحة العمل، ولا تستطيع مساحة عمل متأخرة الدفع انتهت مهلة سماحها إنشاء مشاريع.

عندما يُرفض الاستدعاء

message جملة بلغة الطلب: الجملة أعلاه، أو الجملة العامة للحالة. أي حقل في الجسم لا يقبله المسار يُجاب بـ 400.

من يستطيع إدارة المفاتيح

هي جزء من مصفوفة أدوار كل مساحة عمل، فيستطيع المالك منحها لدور آخر.

• الفريق والأدوار
• مرجع واجهة API