English ابدأ التجربة المجانية احجز عرضًا توضيحيًا

المطورون

ابنِ على ماورو بواجهة REST مفتوحة

مفاتيح واجهة بنطاقات محددة، وإشعارات آلية موقّعة، و38 نقطة نهاية موثقة للموظفين والهيكل التنظيمي والحضور والإجازات والرواتب، باستجابات JSON وأخطاء متوقعة وملف OpenAPI 3.1 يمكنك استيراده في أي أداة.

مرجع واجهة البرمجة openapi.json
  • العنوان الأساسيhttps://mawro.neuroskill.tech/api/v1
  • المصادقةمفتاح (Bearer mk_live_…) على ‎/ext، ورمز JWT للمستخدم في غيرها
  • الإصداراتضمن المسار: /api/v1
  • حدود الاستخدام120 طلبًا في الدقيقة لكل مفتاح افتراضيًا، و600 لكل مستخدم مسجّل

البدء السريع

أول طلب لك في ثلاث خطوات

  1. 1أنشئ مفتاح واجهة برمجةيفتح المسؤول الإعدادات › التكاملات › مفاتيح الواجهة، ويسمّي المفتاح، ويختار النطاقات اللازمة فقط (مثل "إرسال بصمات الحضور")، ويمكنه تحديد تاريخ انتهاء. يظهر المفتاح مرة واحدة، ولا يحتفظ ماورو إلا ببصمته المشفّرة.
  2. 2استدعِ الواجهة الخارجيةأرسل المفتاح في الترويسة Authorization: Bearer mk_live_… إلى نقاط النهاية ‎/ext. لا يرى المفتاح أكثر مما يراه منشئه، وكل استدعاء مسجّل في سجل التدقيق.
  3. 3اشترك في الإشعارات الآليةأضف عنوان https من الإعدادات › التكاملات › الإشعارات الآلية واختر أحداثًا مثل employee.hired أو payroll.run_approved. كل إرسال موقّع لتتحقق من أنه صادر عن ماورو.

تكاملات شائعة

ما تبنيه الفرق أولًا

أجهزة الحضور

أرسل البصمات من أي جهاز أو نظام وقت بمفتاح واجهة، مع مفتاح منع التكرار فلا تُحتسب إعادة الإرسال مرتين.

POST /ext/attendance/punches/batch

الرواتب والمحاسبة

اقرأ دورات الرواتب المعتمدة ونتائج كل دورة لكل موظف وعنصر، والمبالغ فقط إن كان منشئ المفتاح مخوّلًا برؤية الرواتب.

GET /ext/payroll/runs/{id}/export

مزامنة بيانات الموارد البشرية

تصفّح الموظفين الذين تغيّرت بياناتهم منذ آخر مزامنة، ودع إشعارات employee.* تخبرك بموعد المزامنة التالية.

GET /ext/employees

الاستجابات

غلاف واحد وأخطاء متوقعة

  • تعيد الاستجابات الناجحة النتيجة ضمن data، مع معرّف تتبع وتوقيت الخادم ضمن meta.
  • تعيد الأخطاء مفتاحًا ثابتًا ورمز حالة HTTP وتفاصيل على مستوى الحقل يمكن عرضها للمستخدمين.
  • التوقيتات بصيغة ISO-8601 وبالتوقيت العالمي. القوائم مقسّمة إلى صفحات أو محدودة العدد، راجع كل نقطة نهاية.
  • اذكر معرّف التتبع (الموجود أيضًا في ترويسة X-Correlation-Id) عند التواصل مع الدعم.
200Success
{
  "data": {
    "rows": [
      {
        "id": "7d1c…",
        "displayName": "Ana Santos",
        "employeeNumber": "EMP-000214"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 25
  },
  "meta": {
    "correlationId": "b6f0c2a4-…",
    "timestamp": "2026-10-18T09:15:02.114Z"
  }
}
422Error
{
  "error": {
    "key": "CFG-001",
    "type": "ERROR",
    "message": "Validation failed.",
    "statusCode": 422,
    "correlationId": "b6f0c2a4-…",
    "timestamp": "2026-10-18T09:15:02.114Z",
    "path": "/api/v1/attendance/punches/batch",
    "details": [
      {
        "field": "events[0].eventAt",
        "key": "CFG-001",
        "message": "Must be an ISO-8601 timestamp.",
        "severity": "ERROR"
      }
    ]
  }
}

الإشعارات الآلية

أحداث تصل إلى أنظمتك، موقّعة

كل إرسال طلب POST بصيغة JSON يحمل { id, type, createdAt, data } مع الترويسات X-Mawro-Event وX-Mawro-Delivery وX-Mawro-Timestamp وX-Mawro-Signature. أي رد 2xx خلال 10 ثوانٍ يُعد تسليمًا، وإلا يعيد ماورو المحاولة حتى 8 مرات بفواصل متزايدة، ويحتفظ بسجل إرسال يمكن إعادة الإرسال منه، ويوقف العنوان بعد 20 إخفاقًا متتاليًا. يجب أن تكون العناوين عامة وبروتوكول https، وتُرفض العناوين الخاصة والداخلية.

  • employee.hiredأصبح سجل التوظيف نشطًا (تعيين مباشر أو تفعيل بعد الاستقبال).
  • employee.updatedكُتبت معلومة في سجل موظف، أو تغيّرت حالة التوظيف.
  • employee.terminatedاكتمل الخروج وانتهى التوظيف.
  • leave.approvedاعتُمد طلب إجازة.
  • attendance.publishedأُقفلت فترة حضور، فأصبحت أرقامها نهائية للرواتب.
  • payroll.run_approvedاعتُمدت دورة رواتب.
  • onboarding.completedاكتمل ملف استقبال موظف جديد.
  • offboarding.completedاكتمل ملف خروج موظف.
Node.jsالتحقق من الإرسال
import { createHmac, timingSafeEqual } from 'node:crypto';

// Express: app.post('/hooks/mawro', express.raw({ type: '*/*' }), handler)
function fromMawro(req, secret) {
  const ts = req.get('X-Mawro-Timestamp');
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = 'v1=' + createHmac('sha256', secret)
    .update(ts + '.' + req.body).digest('hex');
  return req.get('X-Mawro-Signature').split(',').some((s) =>
    s.trim().length === expected.length &&
    timingSafeEqual(Buffer.from(s.trim()), Buffer.from(expected)));
}

التوقيع هو HMAC-SHA256 للنص "timestamp.body" بسرّ العنوان (يظهر مرة واحدة ويمكن تدويره). أثناء التدوير قد تحمل الترويسة توقيعين.

المرجع

تصفح نقاط النهاية

Authentication

4 نقطة نهاية

  • POST/auth/login
  • POST/auth/refresh
  • POST/auth/logout
  • GET/auth/me

Employees

5 نقطة نهاية

  • GET/employees/directory
  • POST/employees
  • GET/employees/{id}
  • GET/employees/{id}/facts/{factKey}

Organization

2 نقطة نهاية

  • GET/config/{entity}
  • GET/config/{entity}/{id}

Attendance

5 نقطة نهاية

  • POST/attendance/punches/batch
  • GET/attendance/punches
  • GET/attendance/punches/exceptions
  • GET/attendance/devices/silent

Leave

6 نقطة نهاية

  • GET/leave/types/available
  • GET/leave/balances
  • GET/leave/requests
  • POST/leave/requests

Payroll

8 نقطة نهاية

  • GET/payroll/runs
  • GET/payroll/runs/{id}
  • GET/payroll/journals
  • GET/payroll/journals/{id}

External API

8 نقطة نهاية

  • GET/ext/me
  • GET/ext/employees
  • GET/ext/employees/{id}
  • GET/ext/attendance/punches

امنح كل تكامل مفتاحًا خاصًا به بالنطاقات اللازمة فقط. أما نقاط النهاية خارج ‎/ext فتعمل برمز جلسة مستخدم من POST /auth/login للأدوات التي تعمل باسم شخص مسجّل. التكاملات

شاهد ماورو يعمل وفق إجراءات شركتك

احجز جولة مدتها 30 دقيقة مع فريقنا، أو ابدأ تجربة مجانية وادعُ فريق الموارد البشرية اليوم.

احجز عرضًا توضيحيًا ابدأ التجربة المجانية