القراءة على مستوى الجهة

في النشر المخصص، يستطيع نظام الجهة أو الشركة القابضة قراءة جميع مساحات العمل دفعة واحدة عبر تكامل قراءة على مستوى النشر. وهو الاستثناء الوحيد من قاعدة أن الطلب لا يسمّي مساحة عمل أخرى، لذلك فهو للقراءة فقط وتحت ضوابط مشددة.

ينشئ التكامل مشرف المنصة من لوحة تحكم المنصة ← التكاملات (صلاحية اللوحة integrations.act، ويملكها دور المالك)، وليس مسؤول مساحة العمل. انظر تكاملات اللوحة لإنشائه وإدارة مفاتيحه وخطافات الويب الخاصة به.

ما يستطيع فعله

• قراءة فقط: كل نقاط GET في الواجهة البرمجية العامة، عبر جميع مساحات العمل النشطة. لا تُقرأ مساحات العمل الموقوفة أو المحذوفة أبداً. وكل عملية كتابة (POST وPATCH وPUT وDELETE) تعيد 403 forbidden.
• قراءة كاملة: بلا مجموعة صلاحيات وبلا إخفاء لبيانات التواصل. يُعاد بريد المرشح وهاتفه ورقم هويته كاملة.
• خطافات ويب عبر جميع مساحات العمل: تستقبل نقاطه الأحداث من كل مساحة عمل نشطة، ويحمل كل غلاف حدث workspaceId.
• سجل التدقيق: يعيد GET /api/v1/audit-events صفوف تدقيق كل مساحة عمل نشطة إضافة إلى صفوف المنصة (workspaceId: null، مثل إجراءات لوحة التحكم)، بترتيب واحد من الأقدم إلى الأحدث.
• غير متاح: GET /api/v1/bulk-jobs/{id} (مهام الإدراج المجمّع تخص تكامل مساحة العمل الذي أرسلها).

الضوابط

• يجب أن يكون للتكامل قائمة عناوين IP مسموحة (عناوين IP أو نطاقات CIDR؛ ويُرفض النطاق الذي يشمل كل العناوين) قبل إنشاء أي مفتاح (422 ip_allowlist_required). ويُرفض عند الطلب كل مفتاح لتكامل بلا قائمة مسموحة.
• يحتاج كل مفتاح إلى تاريخ انتهاء (422 expires_at_required).
• لا تُسجَّل قراءات الواجهة البرمجية في التدقيق. أما تغييرات المفاتيح والنقاط فتُكتب في سجل تدقيق المنصة (admin.integration.*).

workspaceId على الكائنات و?workspaceId=

تتجاهل مفاتيح مساحة العمل ?workspaceId= ولا يُضاف workspaceId إلى كائناتها.

الترقيم عبر مساحات العمل

تمر القوائم على مساحات العمل بترتيب معرّفاتها، وداخل كل مساحة يُستخدم الترتيب المعتاد (id، أو updatedAt ثم id مع updatedSince). ويحفظ nextCursor مساحة العمل وآخر صف، فتبقى الصفحات ثابتة إن أُضيفت مساحات عمل أو أُوقفت بين صفحة وأخرى. ومع updatedSince يكون الترتيب داخل كل مساحة عمل وليس شاملاً: اقرأ كل الصفحات، ثم انقل علامة المزامنة إلى وقت بدء المزامنة. ويُستثنى سجل التدقيق، فترتيبه واحد شامل من الأقدم إلى الأحدث.

مدة صلاحية المفاتيح وتدويرها

تنتهي صلاحية كل مفتاح لتكامل على مستوى النشر. خطّط للتدوير قبل الموعد: أنشئ مفتاحًا جديدًا من اللوحة (يظهر مرة واحدة)، وانشره في نظام الجهة، وتحقق من تحديث وقت آخر استخدام، ثم ألغِ المفتاح القديم. تعمل المفاتيح من العناوين المدرجة في القائمة المسموحة للتكامل فقط، فأضف العناوين الجديدة لنظام الجهة قبل نقله.

ما يضيفه سجل التدقيق

صفوف المنصة (workspaceId: null) هي نشاط لوحة تحكم المنصة: إنشاء مساحات العمل وتغيير حالتها، ودخول مشرفي المنصة إلى مساحات العمل وخروجهم منها، وتغييرات أدوار اللوحة ومشرفيها وتكاملاتها (ومنها إظهار سر توقيع خطاف ويب)، وتعديلات دليل جديرون (taxonomy.*: القطاعات والقطاعات الفرعية والمجموعات الوظيفية والمهارات وروابطها؛ وقيمة target.type بصيغة snake_case مثل sub_sector أو sub_sector_job_family، وtarget.id للرابط بصيغة <fromId>:<toId>)، ومحاولات تسجيل الدخول الفاشلة إلى اللوحة (admin.login_failed، وتبقى عمدًا لأن السجل قراءة كاملة). صفِّ حسب action إن كان نظام SIEM لدى الجهة يحتاج بعضها فقط. انظر سجل التدقيق لأنظمة SIEM.

أول طلب

curl "https://<deployment>/api/v1/employees?limit=100" -H "Authorization: Bearer $ENTITY_KEY"
curl "https://<deployment>/api/v1/job-families?workspaceId=cmv…" -H "Authorization: Bearer $ENTITY_KEY"

يمرّ الطلب الأول على صفحات موظفي كل مساحة عمل نشطة، ولكل منهم workspaceId؛ ويقرأ الثاني الهيكل الوظيفي لمساحة عمل واحدة.