إضافة موظف جديد — مرجع واجهة البرمجة API
POST /employees/create — يضيف موظفاً مع بنود راتبه وفرعه وقسمه. تصل الموظف دعوة تحميل تطبيق بصمتك برسالة نصية.
المعاملات
-
profile.mobile (مطلوب)
رقم الجوال بدون رمز الدولة (9 أرقام تبدأ بـ 5 للأرقام السعودية). يجب ألا يكون مسجلاً لموظف آخر.
-
profile.name (مطلوب)
اسم الموظف (بالعربية).
-
profile.cc
رمز الدولة للجوال. الافتراضي 966.
-
profile.name_en
الاسم بالإنجليزية.
-
profile.title
المسمى الوظيفي (بالعربية).
-
profile.title_en
المسمى الوظيفي (بالإنجليزية).
-
profile.custom_id
الرقم الوظيفي الخاص بكم. يجب أن يكون فريداً في الحساب.
-
profile.joining_date
تاريخ بدء العمل (YYYY-MM-DD).
-
profile.email
البريد الإلكتروني. تُرفض القيمة التي لا تستقبل بريداً.
-
salaries
بنود الراتب، كل بند {amount, type}. راجع «أنواع بنود الراتب». الإجمالي يُحسب تلقائياً.
-
general_settings.location_id
معرّف الفرع.
-
general_settings.department_id
معرّف القسم.
-
general_settings.location_name
اختر الفرع بالاسم بدلاً من المعرّف.
-
general_settings.department_name
اختر القسم بالاسم. يُنشأ القسم إن لم يكن موجوداً.
-
general_settings.status
1 نشط (الافتراضي)، 0 غير نشط.
-
general_settings.establishment_id
المنشأة، للحسابات متعددة المنشآت. الافتراضي المنشأة الرئيسية.
-
extra
بيانات شخصية: country_id و marital_status و birth_date.
ملاحظات
- يرسل هذا الطلب رسالة الترحيب النصية ودعوة واتساب إلى رقم الجوال. لإضافة الموظفين بصمت من نظام ERP وتحديثهم لاحقاً بمعرّفكم، استخدم POST /employees في واجهة الشركاء.
- تُحفظ بنود الراتب فقط إذا كان مستخدم الرمز يملك صلاحية كتابة الرواتب. عندما يشترط الحساب موافقة على الموظفين الجدد يحمل الرد pending_approval: true ويُنشأ الموظف بعد موافقة مدير ثانٍ.
صفحات أخرى في المرجع
-
حضور موظف واحد
GET /reports/attendance/v1/oneEmployee — تقرير الحضور الكامل لموظف واحد بين تاريخين: كل تسجيل دخول وخروج، التأخير، الخروج المبكر، الوقت الإضافي، الغياب وأيام الإجازة.
-
حضور جميع الموظفين
GET /reports/attendance/v1/list — تقرير الحضور لجميع الموظفين النشطين، أو لفرع أو قسم واحد، صفحة بصفحة. يحمل كل موظف إجماليات الفترة والصفوف اليومية.
-
ملف الموظف
GET /employees/v1/profile/{employee_id} — ملف موظف واحد: الاسم والجوال والمسمى الوظيفي وتاريخ الالتحاق والفرع والقسم، مع البيانات الشخصية كالجنسية وتاريخ الميلاد ونهاية العقد.
-
أنواع بنود الراتب
معرّفات الأنواع التي تُرسل في مصفوفة salaries عند إضافة موظف.
-
اختبار الاتصال
GET /ping — يتحقق من مفتاح API ويعيد الحساب التابع له وصلاحياته وقيود الفروع والأقسام. استخدمه لزر «اختبار الاتصال».
-
قائمة الموظفين
GET /employees — موظفو الحساب صفحة بصفحة مع المزامنة التزايدية. يعيد GET /employees/{id} موظفاً واحداً بالشكل نفسه.
-
إنشاء موظف أو تحديثه
POST /employees — ينشئ موظفاً، أو يحدّث الموظف المطابق لـ external_id، فلا يتكرر الموظف عند إعادة الطلب. يحدّث PATCH /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 — يسجّل رابطاً يستدعيه بصمتك عند تغيّر موظف أو سجل حضور أو إجازة أو مسير رواتب. يُعاد سر التوقيع مرة واحدة.