كتابة الدخول والخروج — مرجع واجهة البرمجة API | بصمتك

كتابة الدخول والخروج — مرجع واجهة البرمجة API

POST /attendance — ينشئ سجل حضور اليوم أو يصحّح الموجود. يُعاد حساب التأخير والخروج المبكر والإضافي حسب وردية الموظف. يصحّح PATCH /attendance/{id} سجلاً بمعرّفه.

المعاملات

  • employee_id / external_id (مطلوب)

    الموظف بمعرّف بصمتك أو بالرقم الوظيفي لديكم.

  • date (مطلوب)

    يوم الحضور (YYYY-MM-DD). ليس في المستقبل.

  • check_in

    HH:MM بنظام 24 ساعة، أو null للمسح.

  • check_out

    HH:MM بنظام 24 ساعة، أو null للمسح.

  • shift

    ترتيب الوردية في اليوم. الافتراضي 1.

  • reason (مطلوب)

    سبب كتابة الوقت. يُحفظ في سجل التعديلات.

ملاحظات

  • يعمل المفتاح باسم المدير الذي أصدره. عندما تشترط مجموعة صلاحياته موافقة على تعديل الحضور يكون الرد HTTP 202 {"status": "pending_approval", "approval_request_id": 91} ولا يتغير شيء حتى يقرر مدير ثانٍ. اقرأ النتيجة من GET /approvals/{id} أو من إشعار approval.decided .

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

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

    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 /departments — أقسام الحساب. يعيد GET /locations الفروع بالطريقة نفسها، ويقبل كلاهما /{id} لصف واحد.

  • قائمة سجلات الحضور

    GET /attendance — صف لكل موظف لكل وردية في اليوم، مع وقتي الدخول والخروج وساعات العمل والتأخير والخروج المبكر والوقت الإضافي.

  • قائمة أيام الغياب

    GET /absences — صف لكل يوم وردية بدون تسجيل دخول: الغياب بدون عذر وأيام الراحة وأيام الإجازة المعتمدة.

  • قائمة الإجازات

    GET /leave — طلبات الإجازة مع نوعها وتواريخها وأيامها وحالتها. يعيد GET /leave/grants الإجازات التي سجّلتها الموارد البشرية مباشرة بالشكل نفسه.

  • أرصدة الإجازات

    GET /leave/balances — رصيد الإجازة السنوية لكل موظف محسوباً كما يظهر في ملف الموظف، مع صافي الأيام لكل نوع إجازة.

  • قائمة طلبات الموظفين

    GET /requests — صندوق الطلبات: كل طلب قدّمه موظف مع نوعه وحالته والقيم المُدخلة في النموذج.

  • قائمة مسيرات الرواتب

    GET /payrolls — مسيرات الرواتب مع فترتها وحالتها وأوقات الرفع والاعتماد والدفع.

  • قائمة قسائم الرواتب

    GET /payslips — قسيمة لكل موظف في كل مسير: الأساسي والسكن والإضافات والاستقطاعات والصافي.

  • الاشتراك في الإشعارات اللحظية

    POST /webhooks — يسجّل رابطاً يستدعيه بصمتك عند تغيّر موظف أو سجل حضور أو إجازة أو مسير رواتب. يُعاد سر التوقيع مرة واحدة.

Write check-in and check-out — API reference

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.

Parameters

  • employee_id / external_id (required)

    The employee by Basmtak id or by your employee number.

  • date (required)

    The attendance day (YYYY-MM-DD). Not in the future.

  • check_in

    HH:MM in 24-hour time, or null to clear.

  • check_out

    HH:MM in 24-hour time, or null to clear.

  • shift

    The shift's order in that day. Default 1.

  • reason (required)

    Why the time is written. Kept in the record's history.

Good to know

  • The key acts as the admin who issued it. When that admin's permission group requires approval for attendance edits, the answer is HTTP 202 {"status": "pending_approval", "approval_request_id": 91} and nothing changes until a second admin decides. Read the outcome from GET /approvals/{id} or the approval.decided webhook.

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

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