قائمة الأقسام والفروع — مرجع واجهة البرمجة API | بصمتك

قائمة الأقسام والفروع — مرجع واجهة البرمجة API

GET /departments — أقسام الحساب. يعيد GET /locations الفروع بالطريقة نفسها، ويقبل كلاهما /{id} لصف واحد.

المعاملات

  • updated_since

    الصفوف التي تغيّرت منذ هذا الوقت بصيغة ISO-8601 فقط. استخدم meta.server_time من التشغيل السابق ناقص دقيقتين. بدون فرق توقيت يُقرأ بتوقيت الرياض.

  • pagination

    أرسل cursor للتصفح بالمؤشر (موصى به لكل مزامنة).

  • cursor

    قيمة meta.next_cursor من الصفحة السابقة. القيمة null تعني آخر صفحة.

  • per_page

    عدد الصفوف في الصفحة. الافتراضي 50 والحد الأقصى 200.

  • include_deleted

    أعد الصفوف المحذوفة أيضاً (يكون deleted_at معبّأً) لتحذفها من نظامك.

ملاحظات

  • صف الفرع يحمل أيضاً boundary_type ومع include_deleted=1 يحمل deleted_at .

صفحات أخرى في المرجع

  • حضور موظف واحد

    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} موظفاً واحداً بالشكل نفسه.

  • إنشاء موظف أو تحديثه

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

List departments and branches — API reference

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

Parameters

  • updated_since

    Only rows changed at or after this ISO-8601 time. Use the previous run's meta.server_time minus two minutes. Without an offset it is read as Asia/Riyadh.

  • pagination

    Send cursor for keyset pagination (recommended for every sync).

  • cursor

    meta.next_cursor of the previous page. null means the last page.

  • per_page

    Rows per page. Default 50, maximum 200.

  • include_deleted

    Also return deleted rows (deleted_at is set) so you can remove them on your side.

Good to know

  • A branch row also carries boundary_type and, with include_deleted=1 , deleted_at .

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.

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