إنشاء موظف أو تحديثه — مرجع واجهة البرمجة API | بصمتك

إنشاء موظف أو تحديثه — مرجع واجهة البرمجة 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 — يسجّل رابطاً يستدعيه بصمتك عند تغيّر موظف أو سجل حضور أو إجازة أو مسير رواتب. يُعاد سر التوقيع مرة واحدة.

Create or update an employee — API reference

POST /employees — Creates an employee, or updates the one whose external_id matches, so a repeated call never duplicates. PATCH /employees/{id} updates by Basmtak id with the same fields.

Parameters

  • name (required)

    Name. Required on create.

  • mobile (required)

    National number or +9665XXXXXXXX. Required on create; must not belong to another employee.

  • external_id

    Your system's stable id for the employee. Stored as the employee number.

  • name_en

    Name in English.

  • email

    E-mail address.

  • country_code

    Default 966.

  • job_title / job_title_en

    Job title in Arabic and English.

  • joining_date

    YYYY-MM-DD.

  • status

    1 active, 0 inactive.

  • department_id / department_name

    The department by id or by exact name. A new name creates the department.

  • location_id / location_name

    The branch by id or by exact name. Branches are never created.

  • establishment_id / establishment_name

    The company, for accounts with several companies.

  • send_invite

    true sends the welcome SMS and WhatsApp invitation. Default false: nothing is sent.

Good to know

  • HTTP 201 when the employee was created, 200 when an existing one was updated. Fields you leave out are not changed on update.
  • A status change may wait for a second admin when the account requires approval. The answer is then HTTP 202 with approval_request_id ; read the outcome from GET /approvals/{id} .

More API pages

  • Single employee attendance

    GET /reports/attendance/v1/oneEmployee — The full attendance report of one employee between two dates: every check-in and check-out, lateness, early leave, overtime, absences and leave days.

  • All employees attendance

    GET /reports/attendance/v1/list — The attendance report for all active employees, or for one branch or department, page by page. Each employee carries the period totals and the day-by-day rows.

  • Get employee profile

    GET /employees/v1/profile/{employee_id} — One employee's profile: name, mobile, job title, joining date, branch and department, plus personal details such as nationality, birth date and contract end.

  • Create new employee

    POST /employees/create — Adds an employee with their salary items, branch and department. The employee receives the invitation to install the Basmtak app by SMS.

  • Salary item types

    The type ids to send in the salaries array when you create an employee.

  • Test the connection

    GET /ping — Checks an API key and returns the account it belongs to, its scopes and its branch and department restrictions. Use it for a Test connection button.

  • List employees

    GET /employees — Employees of the account, page by page, with incremental sync. GET /employees/{id} returns one employee in the same shape.

  • List departments and branches

    GET /departments — Departments of the account. GET /locations returns the branches the same way, and both accept /{id} for one row.

  • List attendance records

    GET /attendance — One row per employee per shift per day, with check-in and check-out timestamps, worked hours, lateness, early leave and overtime.

  • Write check-in and check-out

    POST /attendance — Creates a day's attendance record or corrects the existing one. Lateness, early leave and overtime are recalculated against the employee's shift. PATCH /attendance/{id} corrects a record by id.

  • List absence days

    GET /absences — One row per shift day with no check-in: unexcused absences, days off and days on approved leave.

  • List leave

    GET /leave — Leave requests with their type, dates, days and status. GET /leave/grants returns leave that HR recorded directly, in the same shape.

  • Leave balances

    GET /leave/balances — The annual leave balance of each employee, calculated the way the employee profile shows it, plus net days per leave type.

  • List employee requests

    GET /requests — The requests inbox: every request an employee filed, with its type, status and the values entered on the form.

  • List payroll runs

    GET /payrolls — Payroll runs with their period, status and the times they were submitted, approved and paid.

  • List payslips

    GET /payslips — One payslip per employee per payroll run: basic, housing, additions, deductions and the net total.

  • Subscribe to webhooks

    POST /webhooks — Registers a URL that Basmtak calls when an employee, attendance record, leave or payroll changes. The signing secret is returned once.