مزامنة الأشخاص من واجهة API خاصة بك

يربط مصدر Custom API نظام Polzy بنظام خاص بك — أداة موارد بشرية داخلية، أو نظام CRM، أو قاعدة بيانات خلف واجهة API. يعمل بطريقتين، ويمكنك استخدامهما معًا:

• السحب (pull). يقرأ Polzy نقطة نهاية HTTPS تُعيد أشخاصك بصيغة JSON، وفق جدول زمني تختاره.
• الدفع (push). يرسل نظامك شخصًا واحدًا إلى Polzy لحظة تغيّره، موقّعًا بسرّ مشترك بينكما، فيطبّقه Polzy فورًا.

في الحالتين، يحوّل ربط الحقول نفسه سجلاتك إلى أشخاص في Polzy.

قبل أن تبدأ

تحتاج إلى:

• أن تكون مسؤولًا في مساحة عمل Polzy، على خطة Team أو أعلى، مع تفعيل مزامنة الأشخاص من الإعدادات ← عام ← ما تقوم به مساحة العمل هذه.
• نقطة نهاية على الإنترنت العام، تُقدَّم عبر HTTPS، تُعيد قائمة JSON بالأشخاص — ومطوّر يستطيع تعديلها. لا يستدعي Polzy العناوين الخاصة أو الداخلية.
• معرّف id فريد لكل شخص. يستخدمه Polzy للتعرّف على الأشخاص من مزامنة إلى أخرى.
• أن تكون الحقول التي تريد تجميع النتائج حسبها مضافة في Polzy.

تتزامن مساحة العمل من مصدر واحد في كل مرة. إذا كان هناك مصدر آخر مربوط، فافصله أولًا. وإذا كانت مؤسستك تزوّد الأشخاص عبر SCIM، فلا يمكن ربط أي مصدر إطلاقًا — راجع SCIM.

ما تُعيده نقطة النهاية

يُعيد طلب GET إلى نقطة النهاية الأشخاصَ، كقائمة في أعلى الاستجابة أو في مسار داخلها:

{
  "data": {
    "users": [
      {
        "id": "4821",
        "email": "anouk@acme.com",
        "first_name": "Anouk",
        "last_name": "Jansen",
        "phone": "+31612345678",
        "is_active": true,
        "department": "Sales",
        "manager_email": "rahul@acme.com"
      }
    ]
  },
  "meta": { "next_cursor": "eyJwYWdlIjoyfQ" }
}

هنا تكون قيمة مسار البيانات (JSON) هي data.users؛ أما إذا كانت القائمة في أعلى الاستجابة، فاتركه فارغًا. ويمكن للمسارات أن تدخل في القوائم أيضًا، مثل results[0].people.

لكل طلب 30 ثانية للاستجابة. إذا كانت نقطة النهاية تقسّم النتائج إلى صفحات، فأخبر Polzy بالطريقة:

• عبر رابط أو مؤشّر. ضع الحقل الذي يحمله في حقل الصفحة التالية، مثل meta.next_cursor. يُستدعى العنوان الكامل كما هو، أما المؤشّر فيُضاف إلى عنوان نقطة النهاية بالشكل ?cursor=…، أو بالاسم الموجود في معامل الصفحة. يتوقف Polzy حين يكون الحقل فارغًا.
• عبر رقم الصفحة. اترك حقل الصفحة التالية فارغًا وضع اسم المعامل في معامل الصفحة، مثل page. يطلب Polzy الصفحة 2 ثم 3 وهكذا، ويتوقف عند أول صفحة فارغة.

يقرأ Polzy 500 صفحة على الأكثر في كل مزامنة.

ربط واجهتك في Polzy

1. افتح جهات الاتصال ← المزامنة والحقول.
2. ضمن المصادر المتاحة، ابحث عن Custom API واختر ربط. تُفتح لوحة من ثلاث خطوات: الاتصال وإعدادات المزامنة وربط الحقول.
3. أدخل رابط URL لنقطة نهاية API، ومسار البيانات (JSON) وحقول تقسيم الصفحات إن احتجت إليها.
4. اختر نوع المصادقة واملأ ما يطلبه: Bearer Token؛ أو اسم ترويسة API Key وقيمة API Key؛ أو اسم المستخدم وكلمة المرور لـ المصادقة الأساسية؛ أو لا شيء مع بدون. أضف أي ترويسة أخرى تحتاجها نقطة النهاية ضمن ترويسات مخصصة.
5. للدفع، أدخل سلسلة عشوائية طويلة في سرّ توقيع الويب هوك، وأعطِ السلسلة نفسها لمطوّرك. وإلا فاتركه فارغًا.
6. اختر اختبار الاتصال. تعني رسالة Successfully connected to API. Found N users. أن Polzy استطاع قراءة نقطة النهاية.
7. اختر التالي، وراجع إعدادات المزامنة، ثم اختر التالي مرة أخرى، واربط الحقول (أدناه)، ثم اختر ربط.

مزامنة الأشخاص

ربط Custom API

تُشفَّر المفاتيح وتُستخدم نيابةً عنك فقط.

2 من 2 مطلوبة

الاتصالإعدادات المزامنةربط الحقول

حقل الصفحة التاليةاختياري

معامل الصفحةاختياري

سرّ توقيع الويب هوكاختياري

رابط URL لنقطة نهاية APIمطلوب

نوع المصادقةمطلوب

Bearer Tokenاختياري

مشفّر أثناء التخزينإلغاءاختبار الاتصالالتالي

تُخزَّن الرموز وكلمات المرور وسرّ التوقيع وقيمة كل ترويسة مخصصة مشفّرةً، ولا تُستخدم إلا لاستدعاء نقطة النهاية.

إعدادات المزامنة

يتبع وصول أشخاصك كأعضاء أو كجهات اتصال جمهورَ مساحة عملك: أعضاء في مساحة عمل للموظفين، يستطيعون تسجيل الدخول ويشغلون مقعدًا؛ وجهات اتصال في مساحة عمل للعملاء أو مستخدمي المنتج أو ضيوف الفعاليات، يكتفون بالإجابة.

ربط الحقول

يقرأ الربط الافتراضي email وfirst_name وlast_name وphone وis_active. أما الباقي فتربطه بنفسك: فعّل تخطيط الحقول المخصص واكتب لكل حقل المسار في سجلاتك الذي يملؤه — department وmanager_email وplan وprofile.country. تقترح القائمة أسماء شائعة، وتُكتب المسارات بالأسلوب نفسه المستخدم في مسار البيانات. لكل صف أيضًا قيمة في إذا كان فارغًا، استخدم، تُكتب حين لا يحتوي السجل شيئًا لذلك الحقل؛ أما القيمة التي ترسلها واجهتك فلا تُستبدل أبدًا.

مزامنة الأشخاص

ربط Custom API

تُشفَّر المفاتيح وتُستخدم نيابةً عنك فقط.

الاتصالإعدادات المزامنةربط الحقول

تخطيط الحقول المخصص

التخطيط المخصص نشط اختر أي حقل من نظام الموارد البشرية لديك يغذّي كل حقل من حقول المشارك.

الحقول الأساسية

حقل المشاركمن المصدرإذا كان فارغًا، استخدم

البريد الإلكترونيمطلوب

مثال: anouk@acme.com, rahul@acme.com

الاسم الأولمطلوب

مثال: أنوك، راهول

اسم العائلةمطلوب

مثال: يانسن، ميهتا

حقول مساحة العمل

حقل المشاركمن المصدرإذا كان فارغًا، استخدم

القسم

مثال: المبيعات، العمليات

مشفّر أثناء التخزينرجوعربط

أمور تجدر معرفتها:

• أمثلة حقيقية. بعد الربط، اختر الإعدادات في المزامنة والحقول وافتح ربط الحقول من جديد: تشمل الاقتراحات حينها كل مسار في خمسة سجلات حقيقية، لكل منها مثال.
• حالة النشاط. القيمة false أو 0 أو no أو inactive أو terminated أو leave أو disabled أو suspended أو archived تعطّل الشخص؛ وأي قيمة أخرى، أو عدم وجود قيمة، يُبقيه نشطًا.
• المديرون. اربط المدير بحقل يحمل البريد الإلكتروني للمدير أو رقمه الوظيفي أو معرّفه id في واجهتك. يُنشأ الربط حين يكون المدير موجودًا في Polzy أيضًا. يحتاج المديرون إلى تفعيل التسلسل الإداري في مساحة العمل.
• لا تُملأ إلا حقول مساحة عملك. أضف حقلًا عبر إضافة حقل في المزامنة والحقول قبل ربطه. ولمقارنة النتائج حسبه، اجعله حقلًا من نوع قائمة وفعّل المجموعات.

المعاينة وتشغيل المزامنة الأولى

1. في المزامنة والحقول، اختر معاينة مزامنة ضمن سجل المزامنة. يحسب Polzy ما ستضيفه المزامنة وتحدّثه وتعطّله دون أن يغيّر شيئًا، ويفتح السجل حيث تظهر النتيجة بوصف معاينة.
2. راجع المعاينة، وصحّح الربط من الإعدادات عند الحاجة، ثم اختر مزامنة الآن.

المزامنة والحقول

Custom APIمتصلآخر مزامنة منذ 5 دقائق · تعمل كل ساعة · 152 شخصًا · 9 مجموعاتالإعداداتمزامنة الآن

سجل المزامنةمعاينة مزامنة

اليوم، 09:12نجحتأُضيف 2 · حُدّث 5

اليوم، 08:10جزئيةحُدّث 1 · تُخطي 3

أمس، 16:40معاينةأُضيف 152

يُطابَق الأشخاص بمعرّفهم id، ثم بالبريد الإلكتروني، فمن أضفته يدويًا من قبل يُحدَّث بدلًا من أن يُضاف مرتين.

دفع التغييرات لحظة حدوثها

يرسل الدفع شخصًا واحدًا في كل مرة إلى Polzy، موقّعًا، كلما تغيّر. وتستمر المزامنات المجدولة إلى جانبه وتلتقط ما فاته — لذا ما زال Polzy يحتاج إلى نقطة النهاية أعلاه، حتى لو كانت تُعيد قائمة فارغة.

1. افتح في Polzy التكاملات، ثم Custom API، وانسخ العنوان الظاهر تحت الاستقبال. هذا العنوان مخصص لاتصالك وينتهي بـ /api.
2. تأكد من أن السرّ نفسه محفوظ في سرّ توقيع الويب هوك ضمن الإعدادات وفي نظامك.
3. من نظامك، أرسل طلب POST إلى ذلك العنوان، مع الشخص بصيغة JSON وثلاث ترويسات:

الجسم هو الشخص، بأسماء الحقول نفسها التي تُعيدها نقطة النهاية، فيُطبَّق الربط نفسه. ويمكن أيضًا تغليفه بالشكل { "user": { … } } أو { "employee": { … } }. يجب أن يحمل المعرّف id والحقول التي تغيّرت — فالجسم الذي يحمل id وحده يُقبَل لكنه لا يغيّر شيئًا. لتعطيل شخص، أرسله مع "is_active": false، أو مع ما يقرأه ربطك لـ حالة النشاط.

في Node.js:

import crypto from 'node:crypto';

const body = JSON.stringify({
  id: '4821',
  email: 'anouk@acme.com',
  first_name: 'Anouk',
  last_name: 'Jansen',
  department: 'Operations',
  is_active: true,
});
const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = crypto
  .createHmac('sha256', process.env.POLZY_SIGNING_SECRET)
  .update(`${timestamp}.${body}`)
  .digest('hex');

await fetch(process.env.POLZY_RECEIVING_URL, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Polzy-Timestamp': timestamp,
    'X-Polzy-Signature': signature,
    'X-Polzy-Event-Id': 'person-4821-2026-10-31T09:12:00Z',
  },
  body,
});

في Python:

import hashlib, hmac, json, os, time, requests

body = json.dumps({"id": "4821", "email": "anouk@acme.com", "department": "Operations", "is_active": True})
timestamp = str(int(time.time()))
signature = hmac.new(
    os.environ["POLZY_SIGNING_SECRET"].encode(),
    f"{timestamp}.{body}".encode(),
    hashlib.sha256,
).hexdigest()

requests.post(
    os.environ["POLZY_RECEIVING_URL"],
    data=body,
    headers={
        "Content-Type": "application/json",
        "X-Polzy-Timestamp": timestamp,
        "X-Polzy-Signature": signature,
        "X-Polzy-Event-Id": "person-4821-2026-10-31T09:12:00Z",
    },
)

وقّع البايتات التي ترسلها بالضبط: حوّل الجسم إلى نص مرة واحدة وأرسل السلسلة نفسها. وهذا ما يجيب به Polzy:

إذا كانت مساحة عملك متوقفة مؤقتًا لتجاوزها خطتها، تُؤكَّد الاستدعاءات ولا يُطبَّق شيء.

استدعاءات موقّعة دون طابع زمني

كان الإصدار الأول من الدفع يوقّع الجسم وحده، دون X-Polzy-Timestamp. ما زالت هذه الاستدعاءات مقبولة حاليًا، وما دام نظامك يرسلها، تعرض الإعدادات ← واجهة البرمجة ← الويب هوك تحذيرًا بالتاريخ الذي ستُرفض بدءًا منه. ومن ذلك التاريخ، يجيب Polzy عنها بـ 401 وCalls without X-Polzy-Timestamp are refused since متبوعة بذلك التاريخ. انتقل إلى التوقيع الموضّح أعلاه قبل ذلك — راجع الويب هوك.

استكشاف الأخطاء وإصلاحها

معلومات مفيدة

• الحدود. المزامنة التي تتجاوز مقاعدك أو جهات اتصالك تستورد من يتسع لهم، وتتوقف عندهم، وتُبلغ المسؤولين — راجع الاستخدام والحدود.
• شخص واحد في كل دفعة. أرسل استدعاءً منفصلًا لكل شخص تغيّر.
• قطع الاتصال أو الإزالة. من الإعدادات، يوقف قطع الاتصال المزامنة ويحتفظ بالإعدادات والسجل لتعيد الربط لاحقًا، بينما تحذف إزالة الاتصال. في الحالتين يبقى الأشخاص الذين تمت مزامنتهم في Polzy ولا يعودون يُحدَّثون، وتُرفض التغييرات المدفوعة.
• بقية واجهة API. لقراءة النتائج أو إنشاء الإجراءات من نظامك، استخدم مفتاح API ومرجع API.