ما هي
تتيح الواجهة البرمجية لـ«كورب هاندز» لنظام الموارد البشرية أو مستودع البيانات أو أدواتكم الداخلية التعامل مع بياناتكم في «كورب هاندز». ويستخدم كل طلب مفتاحاً يخص مساحة شركتك ولا يحمل إلا الصلاحيات التي اخترتها.
من الاستخدامات الشائعة في الخليج: إرسال بيانات الموظفين من Workday أو SAP، وجلب ساعات التطوع المعتمدة إلى لوحة استدامة أو ذكاء أعمال على مستوى المجموعة.
ماذا يمكنك أن تفعل بها
GET /api/v1/employees(عرض الموظفين): البريد والاسم والدور والقسم والمسمى الوظيفي والرقم الوظيفي والحالة وتاريخ الانضمام، مع التصفية بـactive=true|false.POST /api/v1/employees(إضافة الموظفين وتحديثهم وتعطيلهم): حتى 5,000 شخص في الطلب الواحد مطابقةً بالبريد، وأرسل"active": falseللتعطيل.GET /api/v1/activities?from=YYYY-MM-DD&to=YYYY-MM-DD(قراءة الأنشطة): الأنشطة مع أعداد المسجلين.GET /api/v1/hours?year=2026(قراءة ساعات التطوع المعتمدة): سجلات الساعات المعتمدة فقط.GET /api/v1/reports/summary?year=2026(قراءة الملخص السنوي): الأرقام الرئيسية للسنة، من الساعات المعتمدة فقط.
طريقة الاستخدام
إنشاء مفتاح API
- افتح مفاتيح الواجهة البرمجيةانتقل إلى مساحة المسؤولية المجتمعية ← التكاملات ← مفاتيح الواجهة البرمجية (API).
- سمّه واختر الصلاحياتأعطِ المفتاح اسماً، مثل «تكامل Workday»، وحدد من الصلاحيات ما يحتاجه فقط.
- انسخ المفتاح مرة واحدةاختر إنشاء مفتاح. يظهر المفتاح (
corphands_live_…) مرة واحدة فقط، فاحفظه في نظام إدارة الأسرار لديكم. لا يحتفظ «كورب هاندز» إلا ببصمته.
إجراء أول طلب
- أرسل المفتاح كرمز Bearerمثال:
curl -s "https://your-corphands-address/api/v1/employees?limit=50" -H "Authorization: Bearer $CORPHANDS_KEY" - تصفّح النتائجاستخدم
limit(من 1 إلى 500، والافتراضي 100) وoffset. - تعامل مع الأخطاءتعود الأخطاء بالصيغة
{"error":{"code":…,"message":…}}مع الرمز 401 (مفتاح غير صالح) أو 403 (صلاحية أو باقة ناقصة أو اشتراك غير نشط) أو 429 (تجاوز الحد) أو 400/413 (محتوى غير صالح أو كبير جداً).
نصائح وممارسات جيدة
- خصص لكل تكامل مفتاحاً مستقلاً بأقل الصلاحيات الممكنة، ويمكنك إلغاء أي مفتاح في أي وقت عبر إلغاء.
- الحدود: 120 طلباً في الدقيقة لكل مفتاح، و25 مفتاحاً نشطاً لكل مساحة.
- لا تستخدم
"deactivate_missing": trueفي طلب POST إلا إذا أرسلت القائمة الكاملة للموظفين. والأدوار المرسلة عبر الواجهة البرمجية تقتصر على employee أو manager. - يُسجَّل كل طلب يغيّر البيانات في سجل التدقيق، ويُظهر عمود آخر استخدام متى استُخدم كل مفتاح آخر مرة.
أسئلة شائعة
هل تعرض الواجهة البرمجية الساعات غير المعتمدة؟
لا. نقطتا الساعات والملخص تعرضان الساعات المعتمدة فقط، وهي الأرقام نفسها المستخدمة في تقرير الاستدامة.
هل تتوفر Webhooks؟
ليس حالياً. استعلم من نقاط الواجهة بشكل دوري بدلاً من ذلك.
ماذا يحدث للمفاتيح إذا تغيّرت باقتنا؟
تتوقف المفاتيح عن العمل إذا لم تعد الباقة تشمل الواجهة البرمجية أو أصبح الاشتراك غير نشط، وتعود للعمل عند استعادة الباقة ما لم تُلغَ.
أين أجد المرجع الكامل؟
يمكن لمسؤول التواصل لديكم في «كورب هاندز» مشاركة دليل التكامل، وفيه جميع الحقول وأمثلة الطلبات.