المصادقة

يقبل FreeMaint آليتي مصادقة: JWTs (الصادرة عن طريق /auth/login، المستخدمة بواسطة تطبيقات الويب والجوال لدينا) ومفاتيح API (التي تم إنشاؤها في /company-settings/api، المستخدمة من خلال عمليات التكامل الخاصة بك).

JWT (جلسات المستخدم)

1. POST /auth/login — الجسم: {email, password}. يُرجع {access_token, refresh_token}.
2. إرسال رأس التفويض — في كل طلب: Authorization: Bearer <access_token>.
3. تحديث عند انتهاء الصلاحية — أرسل POST إلى /auth/refresh مع refresh_token للحصول على access_token جديد. تبقى رموز الوصول صالحة لمدة ساعتين.

مفتاح API (تكامل الخادم)

1. افتح /company-settings/api أو /profile/api-keys — يُنشئ المسؤولون المفاتيح من إعدادات الشركة > API، بدءًا من باقة Business. ويُنشئ الشخص الذي يملك دوره صلاحية «إنشاء مفاتيح API شخصية» مفاتيحه الخاصة من الملف الشخصي > الأمان > مفاتيح API. يمكن لدور يملك صلاحية «إدارة التكاملات» (مثل قالب مسؤول التكاملات) إنشاء مفاتيح الشركة وإلغاؤها وحذفها دون أن يكون مسؤولًا؛ ولا يسلّم مفتاحًا لشخص آخر إلا المسؤول.
2. انقر فوق "مفتاح جديد" — يمكنك اختياريًا تحديد تاريخ انتهاء ومستوى وصول (للقراءة فقط افتراضيًا). يُعرض المفتاح الخام مرة واحدة فقط — انسخه فورًا.
3. استخدمه — أرسل Authorization: Bearer fmk_<rawKey> مع كل طلب. الصيغة: تبدأ بـ fmk_ متبوعةً بـ 32 حرفًا سداسيًا عشريًا.

ملاحظات أمنية

• يتم تخزين مفاتيح API كتجزئة SHA-256 — بمجرد إغلاق مربع حوار الكشف، تصبح القيمة الأولية غير قابلة للاسترداد
• يؤدي إلغاء المفتاح إلى تعطيله على الفور؛ يتم الاحتفاظ بالصف للتدقيق
• ينتمي كل مفتاح إلى شركة واحدة ولا يصل إلا إلى بياناتها — فسجل شركة أخرى لا يُعثر عليه ببساطة
• يمكن أن تحمل المفاتيح حقل expiresAt اختياريًا لعمليات التكامل قصيرة الأمد
• مستويات الوصول، وهي سقف يُضاف فوق صلاحيات المالك: READ (الافتراضي — استعلامات فقط)، READ_STOCK (استعلامات + adjustStock — مثالي لكشك صرف فقط)، FULL (كل عملية يسمح بها دور المالك)
• يعمل كل مفتاح بصفة مالكه: يحمل كل استدعاء صلاحياته ونطاق رؤيته للبيانات، وما يكتبه المفتاح يُوقَّع باسمه. إذا عُطِّل المالك يُرفَض المفتاح (401، الرمز API_KEY_OWNER_INACTIVE) إلى أن يسلّمه مسؤول إلى شخص آخر من إعدادات الشركة > API — ولا تتغير قيمة المفتاح.

اختبار التكامل

لا توجد بيئة اختبار منفصلة: مفتاح واجهة البرمجة يخاطب دائمًا البيانات الحقيقية للشركة التي ينتمي إليها. وهناك طريقتان للاختبار بأمان. (١) استخدم شركة ثانية كشركة اختبار — فالعزل بين الشركات هو ذاته الآلية التي تفصل بين جميع العملاء، ولذلك لا يمكن لشيء تفعله هناك أن يصل إلى بيانات الإنتاج لديك. ومفاتيح الواجهة البرمجية تتطلب باقة Business، لذا يجب أن تكون تلك الشركة على Business أيضًا: لا يمكن لشركة مجانية إنشاء مفتاح. (٢) للعمل بالقراءة فقط، أنشئ مفتاحًا بمستوى الوصول READ: يستطيع تنفيذ كل الاستعلامات ولا يستطيع أي طفرة، فلا يمكنه تغيير أي شيء إطلاقًا. وعندما تصبح جاهزًا للكتابة، يسمح مفتاح READ_STOCK بـ adjustStock ولا شيء غيره.