مفاهيم الـ API

القواعد التي يتبعها كل طلب إلى واجهة مهنارو. اقرأ البدء مع واجهة API أولاً إن لم ترسل طلباً بعد.

المصادقة والصلاحيات

• المفتاح أو الرمز شخص. رمز الدخول هو من دخل؛ ومفتاح API يعمل باسم الشخص المختار في يعمل باسم عند إنشائه. كل طلب يُفحص كأن هذا الشخص فعله على الشاشات: أولاً ترخيص الشركة (هل الوحدة مشمولة، وهل الترخيص فعّال)، ثم صلاحية دوره (مثل employees.view)، ثم نطاقه (الفروع أو الأقسام أو الموظفون الذين أُعطي الدور عليهم).
• المفتاح يضيّق صلاحيات صاحبه فقط ولا يوسّعها أبداً: الصلاحيات (قراءة = GET، كتابة = POST، تحديث = PUT وPATCH، حذف = DELETE)، وعناوين IP المسموحة، وتاريخ تنتهي في. المفاتيح لا تنشئ مفاتيح أخرى ولا تدير الـ webhooks؛ هذا يحتاج رمز دخول شخص.
• صلاحية كل طلب مذكورة في مرجع الـ API. الطلب بلا صلاحية مذكورة مفتوح لأي مستخدم نشط في الشركة، ويعرض عندها ما يخصه فقط (إجازاتي، كشوف راتبي) أو ما يحق له رؤيته.
• كلمة المرور المؤقتة أو المنتهية تمنع كل شيء ما عدا GET /api/v1/app/me وPUT /api/v1/app/me/password وDELETE /api/v1/app/token؛ أي طلب آخر يرد بـ 403 و"code": "password_change_required".
• طلبات المنصة (/api/v1/platform/… و/mcp/platform) لفريق مهنارو فقط وتحتاج مفتاح مدير منصة. مفاتيح الشركات ورموزها لا تعمل عليها، ومفاتيح المنصة لا تعمل على طلبات الشركات.

الفروع والعزل

قد يكون للشركة عدة فروع، وكل فرع مساحة عمل منفصلة. كل طلب /api/v1/app/companies/{company}/… يقرأ ويكتب في فرع واحد:

1. الفرع المحدد لهذا الطلب، بالمعامل branch أو الترويسة X-Branch (رقم فرع، أو all لكل الفروع التي يحق لك العمل فيها)؛
2. وإلا آخر فرع انتقل إليه الشخص (PUT /api/v1/app/companies/{company}/branch مع {"branch": 77} أو {"branch": "all"}، وGET على نفس المسار لقراءته)؛
3. وإلا فرع الشخص نفسه.

الفرع الذي لا يستطيع الشخص العمل فيه يرد بـ 403 و"code": "branch_forbidden". سجلات الفروع الأخرى لا تُرجع: رقم من فرع آخر يرد بـ 404، أو 422 مع رسالة تذكر فرعه عندما ترسله في حقل نموذج. والبيانات لا تنتقل أبداً من شركة إلى أخرى.

في الطلب الأول من البدء أعطت قائمة الموظفين total: 8 في فرع المقر - بغداد، وtotal: 10 مع X-Branch: all.

الصفحات والتصفية والترتيب

• الصفحات: القوائم مقسمة إلى صفحات. اطلب صفحة بـ ?page=2. كثير من القوائم تقبل per_page (عادة حتى 100)، والباقي بحجم صفحة ثابت.
• معلومات الصفحة في meta: current_page (أو page في بعض القوائم)، وlast_page، وtotal. استمر في الطلب حتى تساوي current_page قيمة last_page.
• التصفية بمعاملات الاستعلام، مذكورة لكل طلب في المرجع. الأسماء الشائعة: search أو q (نص حر)، وstatus، وemployee أو employee_id، وbranch_id، وtype، والتاريخان from وto.
• الترتيب ثابت لكل قائمة ومذكور في وصف الطلب (مثلاً الموظفون حسب الرقم الوظيفي، والإجازات حسب تاريخ البداية، ومسيرات الرواتب الأحدث أولاً). لا يوجد معامل sort عام.

"meta": {"current_page": 1, "last_page": 4, "total": 8}

التواريخ والأوقات والتوقيت

• التواريخ بالشكل YYYY-MM-DD ("hire_date": "2026-03-01")، والأشهر YYYY-MM (GET …/payroll/2026-10).
• الأوقات بساعة الشركة، أي المنطقة الزمنية المحددة للشركة (Asia/Baghdad ما لم تختر شركتك غيرها؛ وهي في timezone لكل فرع). البصمة في 08:00 ببغداد تظهر 08:00 في الرد، مهما كان توقيت خادمك.
• التاريخ مع الوقت في الردود بصيغة ISO 8601 مع فرق التوقيت، مثل 2026-11-02T22:40:00+03:00.
• عندما ترسل تاريخاً مع وقت، أضف فرق التوقيت (2026-11-02T08:00:00+03:00) ومهنارو يحوّله إلى ساعة الشركة. بدونه يُقرأ على أنه بساعة الشركة.

اللغات

• الرسائل والأخطاء بالإنجليزية. أرسل Accept-Language: ar للعربية.
• الأسماء المدخلة بلغتين ترجع باللغتين: "name": {"en": "Ali Hassan", "ar": "علي حسن"}. وعند الإنشاء أو التعديل أرسلها بنفس الشكل {"en": "…", "ar": "…"}.

نفس الطلب الخاطئ بالعربية:

{"message": "اختر قيمة من القائمة.", "errors": {"status": ["اختر قيمة من القائمة."]}}

الأخطاء

الأخطاء دائماً JSON فيها message. كثير منها يضيف code يستطيع برنامجك التصرف بناءً عليه، وأخطاء التحقق تضيف errors، قائمة رسائل لكل حقل:

{
  "message": "The selected status is invalid. (and 1 more error)",
  "errors": {
    "status": ["The selected status is invalid."],
    "from": ["The from field must be a valid date."]
  }
}

رموز قد تراها:

كل حالات رفض البصمة ترد بـ 422 والرسالة في errors.clock مع code مثل device_pending أو device_blocked أو mock_location أو wifi_required أو held_for_review أو live_location_required.

حدود الطلبات

بعض الطلبات لها حد أشد خاص بها، ويظهر في المرجع. الحدود تُحسب لكل شخص مسجّل. كل رد يحمل X-RateLimit-Limit وX-RateLimit-Remaining، وبعد تجاوز الحد يأتي 429 مع Retry-After (بالثواني).

إعادة المحاولة وتكرار الطلب

• لا تدعم الواجهة ترويسة Idempotency-Key. تكرار GET وPUT وPATCH وDELETE آمن: تنفيذها مرتين يترك نفس النتيجة. أما POST الذي انتهت مهلته فقد يكون نجح: تحقق أولاً (مثلاً اعرض الإجازات) قبل إعادة إرساله، وإلا قد يُنشأ مرتين.
• مع 429 انتظر Retry-After؛ ومع 500 أو 502 أو 503 أعد المحاولة بانتظار متزايد (1، 2، 4 … ثوانٍ).
• تسليمات الـ webhooks تحمل نفس X-Mihnaro-Delivery في كل إعادة محاولة وإعادة إرسال: احفظه وتجاوز ما عالجته سابقاً (الـ Webhooks).

الإصدارات

• الإصدار في العنوان: /api/v1. داخل v1 نضيف فقط: طلبات جديدة، وحقول جديدة في الردود، ومعاملات اختيارية جديدة. اكتب برنامجك بحيث يتجاهل الحقول التي لا يعرفها.
• أي تغيير يكسر البرامج الموجودة (حذف حقل أو تغيير اسمه أو معناه) يذهب إلى إصدار جديد، /api/v2، ويبقى v1 يعمل.
• مرجع الـ API وملف OpenAPI مولَّدان من الكود الحي، فهما مطابقان للخادم دائماً.