إنشاء موظف أو تحديثه — مرجع واجهة البرمجة API
POST /employees — ينشئ موظفاً، أو يحدّث الموظف المطابق لـ external_id، فلا يتكرر الموظف عند إعادة الطلب. يحدّث PATCH /employees/{id} بمعرّف بصمتك وبالحقول نفسها.
المعاملات
-
name (مطلوب)
الاسم. مطلوب عند الإنشاء.
-
mobile (مطلوب)
الرقم المحلي أو +9665XXXXXXXX. مطلوب عند الإنشاء؛ يجب ألا يكون لموظف آخر.
-
external_id
معرّف الموظف الثابت في نظامكم. يُحفظ كرقم وظيفي.
-
name_en
الاسم بالإنجليزية.
-
email
البريد الإلكتروني.
-
country_code
الافتراضي 966.
-
job_title / job_title_en
المسمى الوظيفي بالعربية والإنجليزية.
-
joining_date
YYYY-MM-DD.
-
status
1 نشط، 0 غير نشط.
-
department_id / department_name
القسم بالمعرّف أو بالاسم المطابق. الاسم الجديد يُنشئ القسم.
-
location_id / location_name
الفرع بالمعرّف أو بالاسم المطابق. لا تُنشأ الفروع.
-
establishment_id / establishment_name
المنشأة، للحسابات متعددة المنشآت.
-
send_invite
القيمة true ترسل رسالة الترحيب ودعوة واتساب. الافتراضي false: لا يُرسل شيء.
ملاحظات
- HTTP 201 عند إنشاء الموظف، و200 عند تحديث موظف موجود. الحقول غير المُرسلة لا تتغير عند التحديث.
- قد ينتظر تغيير الحالة موافقة مدير ثانٍ إذا اشترط الحساب ذلك. يكون الرد HTTP 202 مع approval_request_id ؛ اقرأ النتيجة من GET /approvals/{id} .
صفحات أخرى في المرجع
-
حضور موظف واحد
GET /reports/attendance/v1/oneEmployee — تقرير الحضور الكامل لموظف واحد بين تاريخين: كل تسجيل دخول وخروج، التأخير، الخروج المبكر، الوقت الإضافي، الغياب وأيام الإجازة.
-
حضور جميع الموظفين
GET /reports/attendance/v1/list — تقرير الحضور لجميع الموظفين النشطين، أو لفرع أو قسم واحد، صفحة بصفحة. يحمل كل موظف إجماليات الفترة والصفوف اليومية.
-
ملف الموظف
GET /employees/v1/profile/{employee_id} — ملف موظف واحد: الاسم والجوال والمسمى الوظيفي وتاريخ الالتحاق والفرع والقسم، مع البيانات الشخصية كالجنسية وتاريخ الميلاد ونهاية العقد.
-
إضافة موظف جديد
POST /employees/create — يضيف موظفاً مع بنود راتبه وفرعه وقسمه. تصل الموظف دعوة تحميل تطبيق بصمتك برسالة نصية.
-
أنواع بنود الراتب
معرّفات الأنواع التي تُرسل في مصفوفة salaries عند إضافة موظف.
-
اختبار الاتصال
GET /ping — يتحقق من مفتاح API ويعيد الحساب التابع له وصلاحياته وقيود الفروع والأقسام. استخدمه لزر «اختبار الاتصال».
-
قائمة الموظفين
GET /employees — موظفو الحساب صفحة بصفحة مع المزامنة التزايدية. يعيد GET /employees/{id} موظفاً واحداً بالشكل نفسه.
-
قائمة الأقسام والفروع
GET /departments — أقسام الحساب. يعيد GET /locations الفروع بالطريقة نفسها، ويقبل كلاهما /{id} لصف واحد.
-
قائمة سجلات الحضور
GET /attendance — صف لكل موظف لكل وردية في اليوم، مع وقتي الدخول والخروج وساعات العمل والتأخير والخروج المبكر والوقت الإضافي.
-
كتابة الدخول والخروج
POST /attendance — ينشئ سجل حضور اليوم أو يصحّح الموجود. يُعاد حساب التأخير والخروج المبكر والإضافي حسب وردية الموظف. يصحّح PATCH /attendance/{id} سجلاً بمعرّفه.
-
قائمة أيام الغياب
GET /absences — صف لكل يوم وردية بدون تسجيل دخول: الغياب بدون عذر وأيام الراحة وأيام الإجازة المعتمدة.
-
قائمة الإجازات
GET /leave — طلبات الإجازة مع نوعها وتواريخها وأيامها وحالتها. يعيد GET /leave/grants الإجازات التي سجّلتها الموارد البشرية مباشرة بالشكل نفسه.
-
أرصدة الإجازات
GET /leave/balances — رصيد الإجازة السنوية لكل موظف محسوباً كما يظهر في ملف الموظف، مع صافي الأيام لكل نوع إجازة.
-
قائمة طلبات الموظفين
GET /requests — صندوق الطلبات: كل طلب قدّمه موظف مع نوعه وحالته والقيم المُدخلة في النموذج.
-
قائمة مسيرات الرواتب
GET /payrolls — مسيرات الرواتب مع فترتها وحالتها وأوقات الرفع والاعتماد والدفع.
-
قائمة قسائم الرواتب
GET /payslips — قسيمة لكل موظف في كل مسير: الأساسي والسكن والإضافات والاستقطاعات والصافي.
-
الاشتراك في الإشعارات اللحظية
POST /webhooks — يسجّل رابطاً يستدعيه بصمتك عند تغيّر موظف أو سجل حضور أو إجازة أو مسير رواتب. يُعاد سر التوقيع مرة واحدة.