إضافة موظف جديد — مرجع واجهة البرمجة API | بصمتك

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

Create new employee — API reference

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.

Parameters

  • profile.mobile (required)

    Mobile number without the country code (9 digits starting with 5 for Saudi numbers). Must not belong to another employee.

  • profile.name (required)

    The employee's name (Arabic).

  • profile.cc

    Country code of the mobile. Default 966.

  • profile.name_en

    Name in English.

  • profile.title

    Job title (Arabic).

  • profile.title_en

    Job title (English).

  • profile.custom_id

    Your own employee number. Must be unique in the account.

  • profile.joining_date

    Work start date (YYYY-MM-DD).

  • profile.email

    E-mail address. A value that cannot receive mail is refused.

  • salaries

    Salary items, each {amount, type}. See Salary item types. The total is calculated for you.

  • general_settings.location_id

    Branch id.

  • general_settings.department_id

    Department id.

  • general_settings.location_name

    Pick the branch by name instead of id.

  • general_settings.department_name

    Pick the department by name. A department that does not exist is created.

  • general_settings.status

    1 active (default), 0 inactive.

  • general_settings.establishment_id

    The company, for accounts with several companies. Defaults to the main one.

  • extra

    Personal details: country_id, marital_status, birth_date.

Good to know

  • This call sends the welcome SMS and WhatsApp invitation to the mobile number. To add employees silently from an ERP, and to update them later by your own id, use the Partner API's POST /employees .
  • Salary items are saved only when the token's user may write salaries. When the account requires approval for new employees, the answer carries pending_approval: true and the employee is created after a second admin approves.

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.

  • 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.

  • Create or update an employee

    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.

  • 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.