مرجع واجهة API

العنوان الأساسي وصيغة الاستجابة

كل مسار يُقدَّم تحت البادئة /api. محليًا يكون العنوان الأساسي http://localhost:8000/api. وعلى الخادم يكون عنوان واجهة API متبوعًا بـ /api، وهو القيمة نفسها التي يقرؤها الموقع ولوحة التحكم من NEXT_PUBLIC_API_BASE_URL (متغيرات البيئة). الملفات تُقدَّم خارج البادئة: ملفات هوية الحزمة على /media/… والملفات المرفوعة على /media/uploads/….

أجسام الطلبات بصيغة JSON، باستثناء رفع الملفات. وكل إجابة تأتي في المغلّف نفسه:

{
  "success": true,
  "data": { },
  "message": ""
}

يحمل data النتيجة. أما message فهو رمز قصير تملؤه بعض عمليات الكتابة، مثل project_created أو invitation_sent، ويكون فارغًا في غير ذلك. تُسمّى مساحات العمل والمشاريع والمهام بمعرّفاتها العامة (org_forma وprj_01)؛ والأعضاء والدعوات والمفاتيح والملفات برقمها. وتحمل نصوص المشاريع والمهام اللغتين معًا بالشكل { "en": { … }, "ar": { … } }.

فحص السلامة لا يحتاج إلى رمز:

curl http://localhost:8000/api/health

{"success":true,"data":{"status":"ok","database":"up"},"message":""}

إلى أن تجيب قاعدة البيانات وتصبح جداولها جاهزة، تجيب الواجهة بـ 503 مع "status":"unavailable" و"database":"down". يقرأ فحص الصحة في صورة Docker هذه الحالة، ولا يشغّل Docker Compose الموقع ولوحة التحكم إلا بعد أن ينجح.

لا يجوز للمتصفحات استدعاء واجهة API إلا من العناوين الواردة في CORS_ORIGIN. وإذا تُرك غير مضبوط فهي تسمح بـ http://localhost:3030 وhttp://localhost:3031، وفي الإنتاج ترفض الواجهة البدء من دونه (مشكلات CORS).

الأخطاء

يحتفظ الفشل بالمغلّف نفسه، مع success: false وdata: null ورمز حالة HTTP:

{
  "success": false,
  "data": null,
  "message": "seat_limit_reached",
  "errors": { "email": ["…"] }
}

• يظهر errors عند فشل التحقق (400)، مع المشكلات لكل حقل.
• أي حقل غير معروف في الجسم يُرفض بالرمز 400: كل جسم يقبل الحقول المذكورة أدناه فقط.
• عندما يكون لدى واجهة API جملة للخطأ، يكون message تلك الجملة بلغة الطلب (Accept-Language: ar للعربية): تسجيل دخول مرفوض، وكل 429، والتسجيل المغلق، وحساب محمي من تغيير كلمة المرور أو البريد، وسر webhook مفقود، واشتراك تعذّر على Stripe إلغاؤه، ودور منصة أو صلاحية لا يملكها المستدعي، ووضع الصيانة.
• وفي غير ذلك، يكون message في 401 و403 و404 جملة عامة للحالة، وفي 400 و402 و409 و410 و503 يكون السبب رمزًا قصيرًا (seat_limit_reached وslug_taken وover_plan_limit وpayment_declined وpreview_expired وinvitation_expired وpayment_unavailable)، يحوّله العميل إلى جملته الخاصة. والتخفيض المرفوض بسبب الاستخدام يحمل blockers أيضًا.
• يعني 402 ترقية خطة لم يقبل مزود الدفع تحصيلها: payment_declined أو payment_needs_action (يطلب المصرف تأكيد الدفعة) أو payment_method_missing. وتبقى الخطة كما كانت.
• أثناء تفعيل طاقم المنصة لوضع الصيانة، يجيب كل مسار خارج القائمة القصيرة في وضع الصيانة بـ 503 لأي شخص ليس من طاقم المنصة، مع الجملة في message وcode: "maintenance_mode".
• يعني 401 عدم وجود رمز، أو رمزًا منتهيًا، أو بيانات دخول خاطئة. ويعني 403 تسجيل دخول بلا الصلاحية، أو كتابة في مساحة عمل موقوفة. ويجيب 404 أيضًا عن مساحة عمل ليس المستدعي عضوًا فيها، فلا يعرف الغريب أي مساحات عمل موجودة.
• الطلب الذي يتجاوز حدًّا يُجاب بـ 429 (الحدود لكل عنوان).

تسجيل الدخول

1. 01

   تسجيل الدخول

   الطرفيةنسخ

   curl -X POST http://localhost:8000/api/auth/login \
     -H "Content-Type: application/json" \
     -d '{"email":"owner@northstack.example","password":"YOUR_PASSWORD"}'

   ضع بيانات الدخول الأولية من التثبيت مكان YOUR_PASSWORD، أو استخدم حسابًا خاصًا بك. data.access_token هو الرمز، ومعه token_type بقيمة Bearer وexpires_in وadmin، وهو الحساب مع أدوار المنصة وصلاحياته ومساحات عمله.
2. 02

   استدعِ مسارًا محميًا

   الطرفيةنسخ

   curl http://localhost:8000/api/workspaces \
     -H "Authorization: Bearer YOUR_TOKEN"

   يسرد هذا مساحات عمل الحساب مع دوره في كل منها. ثم يأخذ كل مسار لمساحة عمل معرّفها العام في مساره:

   الطرفيةنسخ

   curl "http://localhost:8000/api/workspaces/org_forma/projects?limit=20" \
     -H "Authorization: Bearer YOUR_TOKEN"

• remember: true يوقّع رمزًا لمدة 30 يومًا، وremember: false رمزًا لمدة 12 ساعة؛ وإذا حُذف فالرمز يدوم بحسب JWT_EXPIRATION، وهو 7d افتراضيًا.
• بريد غير معروف وكلمة مرور خاطئة يُجابان بـ 401 بالرسالة نفسها، بعد العمل نفسه من تجزئة كلمة المرور، فلا تدل الإجابة ولا زمنها على البريد الذي له حساب.
• عشر محاولات دخول فاشلة من عنوان واحد خلال 15 دقيقة تُجاب بـ 429 حتى يمضي 15 دقيقة على أقدم محاولة فاشلة (RATE_LIMIT_LOGIN). ولا تُحتسب عمليات الدخول الناجحة.
• الرموز بلا حالة: يجيب POST /api/auth/logout فورًا، وتسجيل الخروج هو أن ينسى العميل رمزه.

مساحات العمل والصلاحيات

• مسارات مساحة العمل تبدأ بـ /api/workspaces/:workspaceId، وهو المعرّف العام لمساحة العمل. في كل طلب تتحقق واجهة API من أن المستدعي له عضوية نشطة هناك (وإلا 404) ويملك الصلاحية التي يذكرها المسار (وإلا 403). الدور هو دور العضوية: يمكن لشخص واحد أن يكون مالك مساحة عمل ومسؤولًا في أخرى.
• تضم مساحة العمل أربعة أدوار (owner وadmin وmember وbilling) ومصفوفتها الخاصة من 14 صلاحية: workspace.read وworkspace.update وworkspace.delete وprojects.read وprojects.write وmembers.invite وmembers.remove وroles.manage وbilling.read وbilling.manage وkeys.manage وaudit.read وai.read وai.apply. يملكها المالك كلها، وتبقى workspace.delete وroles.manage للمالك مهما قالت المصفوفة. وأي تغيير في المصفوفة يسري على الطلب التالي.
• مساحة العمل الموقوفة تحتفظ بكل طلبات GET وترفض كل طريقة أخرى بالرمز 403.
• مساحة العمل المتأخرة في الدفع تحتفظ بكل شيء حتى تمر BILLING_GRACE_DAYS (7 افتراضيًا)؛ بعدها لا تستطيع إنشاء مشاريع أو دعوات أو مفاتيح API (403)، بينما تستمر كل القراءات وكل عمليات الكتابة الأخرى.
• مسارات المنصة (/api/platform و/api/users و/api/admins و/api/roles و/api/settings) تتحقق بدلًا من ذلك من صلاحيات المنصة للحساب، وتُمنح عبر أدوار المنصة. ينشئ البذر مسؤول المنصة، بكل الصلاحيات الـ 21، والدعم، الذي يقرأ كل صفحات المنصة ويصدّر التقارير. والمسار الذي يذكر عدة صلاحيات يقبل أيًّا منها.

• الفريق والأدوار والصلاحيات
• إدارة المنصة

القوائم والتقسيم إلى صفحات

{ "data": [ ], "total": 12, "page": 1, "limit": 7, "totalPages": 2 }

• المشاريع، والمشاريع المؤرشفة، والنشاط، ومحادثات المساعد ورسائلها، وصفحة مؤسسات المنصة ومستخدميها، تستخدم page وlimit، بحد أقصى 100 في الصفحة. القيم الافتراضية 7 مشاريع و12 حدثًا و20 محادثة و10 مؤسسات أو مستخدمين.
• صفحات الطاقم وإعدادات المنصة وأدوارها تستخدم page وpage_count بدلًا من ذلك (10 افتراضيًا، وبحد أقصى 100). وأدوار المنصة لا تُقسَّم إلى صفحات إلا عند إعطاء الاثنين معًا؛ وإلا تُعاد كل الأدوار.
• تأتي القوائم من الأحدث أولًا (المشاريع والمستخدمون والمؤسسات بحسب آخر تغيير)، مع المعرّف عند التعادل، ما لم يُعطَ sort؛ وتأتي أدوار المنصة بحسب الاسم. وتعيد قائمة المشاريع أيضًا counts لكل تبويب.
• ما يخص مساحة عمل واحدة ويُعرض كاملًا يُجاب دون تقسيم إلى صفحات: مهام اللوحة، والأعضاء، والدعوات، ومفاتيح API، وملفات المشروع، وآخر 36 فاتورة، وآخر 8 إشعارات.

مساحات العمل والأعضاء ومصفوفة الأدوار

الدعوات

تمر رسائل الدعوة عبر إعدادات SMTP الخاصة بواجهة API، أو تذهب إلى سجلها ما دام SMTP_HOST فارغًا، مع الرابط.

المشاريع والملفات

إنشاء مشروع في مساحة عمل متأخرة في الدفع انتهت مهلتها يُجاب بـ 403.

المهام واللوحة

تُعرض المهمة وتُنشأ تحت مشروعها، وتُغيَّر بمعرّفها الخاص تحت مساحة العمل.

المسؤول عن المهمة إذا لم يكن عضوًا يُجاب بـ 400 مع assignee_not_member. كل تغيير يكتب حدثًا في سجل النشاط، مثل task.moved مع العمودين اللذين انتقلت منهما وإليهما.

النظرة العامة والنشاط والإشعارات والبحث

تعرض آخر أحداث النظرة العامة والجرس السجل كاملًا لمن لديه projects.read أو audit.read، وأحداث billing. فقط لمن لديه billing.read ولا يملك أيًّا من الصلاحيتين السابقتين، ولا شيء لأي شخص آخر.

الفوترة وwebhook الخاص بها والدفع التجريبي

• يستخدم الدفع Stripe Checkout عندما يكون STRIPE_SECRET_KEY مضبوطًا، والدفع التجريبي المدمج في غير ذلك، أو متى كان BILLING_PROVIDER=simulator. الدفع التجريبي لا يحصّل من أحد.
• عنوان العودة وحده لا يغيّر الخطة أبدًا: يغيّرها فقط الـ webhook الموقّع، أو الجلسة المقروءة عند sync.
• يُنشأ سعر Stripe لكل خطة عند أول استخدام، بمفتاح البحث northstack_<plan>_usd_<cents>_month، فلا يلزم إعداد أي شيء في Stripe أولًا.
• إتمام دفع Stripe لمساحة عمل لديها اشتراك Stripe بالفعل يلغي القديم، مع احتساب وقته غير المستخدم رصيدًا. يخزّن invoice.paid فاتورة Stripe مرة واحدة (الفواتير فريدة لكل معرّف فاتورة عند المزود)، مع مبلغها وفترتها، وينقل فترة مساحة العمل إلى الفترة التي تبدأ بها الفاتورة، وعند التجديد يطبّق التخفيض المجدول له.
• في الدفع التجريبي تجدد واجهة API كل فترة عند نهايتها (فاتورة مدفوعة، و30 يومًا تالية، وتخفيض مجدول يُطبَّق) وتنهي ما ضُبط للإلغاء. والفترة التجريبية التي تبلغ نهايتها تصبح متأخرة في الدفع، مع مهلة السماح. وتبدأ عدادات الاستخدام من الصفر في كل فترة. يجري هذا عند كل قراءة للفوترة ومرة كل ساعة.
• وجّه webhook الخاص بـ Stripe إلى https://<your API>/api/billing/webhooks/stripe مع الأحداث أعلاه إضافة إلى checkout.session.expired.

• الفوترة
• إعدادات الدفع

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

curl http://localhost:8000/api/v1/projects \
  -H "Authorization: Bearer nst_live_…"

• يبدأ سر مفتاح الإنتاج بـ nst_live_، ومفتاح العرض بـ nst_demo_. ولا يعمل مفتاح العرض إلا ما دامت واجهة API في الوضع التجريبي.
• من دون مفتاح، أو بمفتاح غير معروف أو ملغى، يُجاب بـ 401؛ والمفتاح الذي لا يملك نطاق المسار يُجاب بـ 403؛ ومساحة العمل الموقوفة ترفض الكتابة.
• كل مسار عدا قائمة المشاريع يعمل بصفة منشئ المفتاح: ما ينشئه يُسجَّل على أنه من صنعه، مع تحقق لوحة التحكم وأحداث النشاط وحدود الخطة. ويُجاب بـ 404 متى غادر المنشئ مساحة العمل، وتُجاب عمليات الكتابة الثلاث بـ 403 متى لم يعد دور المنشئ يملك projects.write.
• كل استدعاء يُحتسب ضمن طلبات API الخاصة بالخطة، التي تقرؤها صفحة الفوترة وحدود الخطة.

• مفاتيح API

نظرة عامة على المنصة والمؤسسات

المستخدمون والطاقم وأدوار المنصة والإعدادات

الحماية على كلمات المرور والبريد: لا يجوز لمستدعٍ غير الحساب نفسه تعيين كلمة مرور الحساب أو تغيير بريده إلا إذا كان مسؤول المنصة أو يملك كل صلاحية منصة يملكها الحساب؛ وإلا تُجيب واجهة API بـ 403. والبريد محمي أيضًا لأن رابط إعادة تعيين كلمة المرور يُرسل إليه.

الحماية على الأدوار: لا يستطيع أحد منح دور منصة أو سحبه أو رفعه فوق صلاحياته، فلا تؤدي admins.assign_roles أو roles.assign_permissions وحدها إلى دور مسؤول المنصة.

صلاحيات المنصة الـ 21 هي platform.view وreports.export وorganizations.view وorganizations.manage وusers.view وusers.create وusers.update وusers.delete وusers.restore وadmins.view وadmins.create وadmins.edit وadmins.delete وadmins.assign_roles وroles.view وroles.create وroles.edit وroles.delete وroles.assign_permissions وsettings.view وsettings.edit.

الإعدادات العامة ووضع الصيانة

ما دام إعداد المنصة maintenance_mode بقيمة true، يُجاب كل طلب من أي شخص ليس من طاقم المنصة (حساب يملك platform.view) بـ 503، مع code: "maintenance_mode" والرسالة «المنصة مغلقة مؤقتًا للصيانة. يُرجى المحاولة مرة أخرى بعد قليل.» والرمز المفقود أو الخاطئ يحصل على 503 نفسها. وتبقى هذه مفتوحة للجميع:

• GET /api/health وGET /api/public-settings؛
• POST /api/auth/login وPOST /api/auth/logout، حيث يرفض تسجيل الدخول أي شخص ليس من الطاقم بـ 503 حتى بعد صحة بيانات الدخول؛
• POST /api/billing/webhooks/stripe وتنزيل الفاتورة الموقّع؛
• نقطة MCP، التي تحتفظ بمفتاحها الخاص، وGET /api/demo/status؛
• POST /api/contact الخاص بالموقع وكل مسار /api/licenses، فيستمر نموذج التواصل والدفع لشراء التراخيص في العمل.

كل ما عدا ذلك مغلق أمام من ليس من الطاقم، بما فيه التسجيل واستعادة الحساب والدعوات والتهيئة وواجهة API العامة تحت /api/v1 والملفات المرفوعة والمساعد. والقائمة في back-end/src/common/constants/maintenance.constants.ts.

نموذج التواصل

• clientToken المكرر يعيد معرّف الرسالة الأولى بدلًا من تخزين ثانية، فإعادة المحاولة آمنة.
• الحقل website المملوء يُعامل على أنه روبوت: تبدو الإجابة نفسها، ولا يُخزَّن شيء.
• يستطيع كل عنوان إرسال خمس رسائل في الساعة؛ والتالية تُجاب بـ 429.
• تُخزَّن الرسائل في جدول contact_messages وتُحوَّل إلى CONTACT_INBOX إذا كان مضبوطًا.

الدفع بالترخيص

• السعر هو سعر الخادم نفسه، من back-end/src/modules/licenses/constants/license-offers.ts؛ ولا يرسل المتصفح سعرًا أبدًا.
• تذهب البطاقة إلى Stripe Checkout عندما يكون STRIPE_SECRET_KEY مضبوطًا، وPayPal إلى PayPal عندما يكون PAYPAL_CLIENT_ID وPAYPAL_CLIENT_SECRET مضبوطين، وكلتاهما إلى الدفع التجريبي في غير ذلك. وفي الوضع التجريبي لا يُعرض أبدًا مزود بمفاتيح حقيقية.
• يُدفع الطلب مرة واحدة، بأيٍّ يأتي أولًا من checkout.session.completed في Stripe على POST /api/billing/webhooks/stripe، أو confirm عند العودة، أو زر الدفع في الدفع التجريبي. وهذا وحده يصدر مفتاح الترخيص ويرسل الإيصال بالبريد. أما checkout.session.expired فيعلّم الطلب بأنه فاشل.
• معرّف الطلب سلسلة عشوائية طويلة تحملها روابط عودة المشتري فقط. clientToken المكرر يُجاب بالطلب الأول. يستطيع كل عنوان بدء عشرة طلبات في الساعة.

• الدفع بالترخيص

الملفات المرفوعة والوسائط

تذهب الصور وملفات المشاريع إلى حاوية Cloudflare R2 عندما تُضبط متغيراتها الخمسة R2_*، وإلى MEDIA_UPLOAD_DIR في غير ذلك، وتُقدَّم على PUBLIC_MEDIA_URL متبوعًا بـ /uploads/….

كل ما تقدمه واجهة API تحت /media يحمل X-Content-Type-Options: nosniff، والملف الذي ليس صورة نقطية أو PDF أو نصًا عاديًا أو صوتًا أو فيديو (مثل ملف HTML أو SVG) يُرسل مع Content-Disposition: attachment، فيُنزَّل بدلًا من أن يُفتح صفحةً على عنوان واجهة API. أما الملفات في حاوية R2 فتقدمها الحاوية، بالنوع الذي رُفعت به.

الحدود لكل عنوان

الطلب الذي يتجاوز حدًّا يُجاب بـ 429، مع جملة تذكر ما حُدّ وكم يجب الانتظار، مثل «طلبات تسجيل كثيرة من هذا العنوان. انتظر ساعة ثم حاول مرة أخرى.» تعيش العدادات في ذاكرة واجهة API، فيمحوها إعادة التشغيل. خلف وكيل عكسي، اضبط TRUST_PROXY على عدد الوكلاء أمام واجهة API، وإلا يُحتسب كل زائر على أنه عنوان الوكيل الواحد.

المساعد الذكي ومحادثاته واقتراحاته

خادم MCP

تحديثات الصلاحيات الحية عبر socket.io

مسارات وضع العرض التجريبي