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

الاشتراك في الإشعارات اللحظية — مرجع واجهة البرمجة API

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

المعاملات

  • url (مطلوب)

    رابط https. تُرفض العناوين الخاصة والمحلية.

  • events (مطلوب)

    employee.created و employee.updated و employee.deleted و attendance.created و attendance.updated و attendance.deleted و leave.updated و leave.deleted و payroll.approved و payroll.returned و payroll.paid و payroll.cancelled و approval.decided.

  • description

    وصف لمرجعكم.

  • active

    القيمة false توقف الإرسال مؤقتاً.

ملاحظات

  • تحقق من التوقيع، وارفض الطابع الزمني الأقدم من خمس دقائق، واستخدم X-Basmtak-Event-Id لتجاهل الإشعار المكرر. أجب بـ 2xx خلال 10 ثوانٍ؛ يُعاد الإرسال ست مرات خلال ساعتين، و HTTP 410 يوقف الاشتراك.
  • متاح أيضاً: GET /webhooks و PATCH و DELETE /webhooks/{id} و POST /webhooks/{id}/ping لإشعار تجريبي موقّع و POST /webhooks/{id}/rotate-secret و GET /webhooks/{id}/deliveries .
  • تُفعَّل الإشعارات اللحظية لكل بيئة. عند إيقافها تعيد الطلبات خطأً ولا يمكن منح الصلاحية.

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

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

    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 — صف لكل موظف لكل وردية في اليوم، مع وقتي الدخول والخروج وساعات العمل والتأخير والخروج المبكر والوقت الإضافي.

  • كتابة الدخول والخروج

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

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

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

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

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

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

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

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

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

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

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

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

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

Subscribe to webhooks — API reference

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

Parameters

  • url (required)

    An https URL. Private and loopback addresses are refused.

  • events (required)

    employee.created, employee.updated, employee.deleted, attendance.created, attendance.updated, attendance.deleted, leave.updated, leave.deleted, payroll.approved, payroll.returned, payroll.paid, payroll.cancelled, approval.decided.

  • description

    A label for your own reference.

  • active

    false pauses deliveries.

Good to know

  • Verify the signature, refuse a timestamp older than five minutes, and use X-Basmtak-Event-Id to ignore a repeated delivery. Answer 2xx within 10 seconds; failures are retried six times over two hours, and HTTP 410 switches the subscription off.
  • Also available: GET /webhooks , PATCH and DELETE /webhooks/{id} , POST /webhooks/{id}/ping for a signed test delivery, POST /webhooks/{id}/rotate-secret and GET /webhooks/{id}/deliveries .
  • Webhooks are switched on per installation. When they are off, the calls answer with an error and the scope cannot be granted.

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.

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