# واجهة برمجة تطبيقات LinkedIn ومساعدو الذكاء الاصطناعي (MCP)

كل ما تقوم به على صفحات LinkedIn يمكن تنفيذه أيضاً من خلال برنامج نصي أو مساعد ذكاء اصطناعي: العملاء المحتملون، قائمة انتظار طلبات الاتصال، قواعد ملف تعريف العميل المثالي (ICP) الخاصة بك (بما في ذلك البلدان التي تقبلها ومدى حجم شبكة العميل المحتمل)، صندوق الوارد الخاص بك، وكلاء الذكاء الاصطناعي لديك، وإعداداتك.

لا يوجد شيء جديد لإعداده. فهي تستخدم **نفس مفتاح واجهة برمجة التطبيقات (API key) الخاص ببقية <span data-t="appName">DM Champ</span>**، لذا إذا كنت تتصل بالفعل بواجهة برمجة التطبيقات الخاصة بنا أو لديك مساعد ذكاء اصطناعي متصل، فأنت جاهز للبدء.

## أين تجد مفتاحك

الإعدادات (Settings) ← عمليات التكامل (Integrations) ← مفتاح واجهة برمجة التطبيقات (API Key). إذا لم يكن لديك مفتاح بعد، انقر على **إنشاء مفتاح واجهة برمجة التطبيقات (Generate API key)**. الخطوات الكاملة موجودة في [الوصول إلى واجهة برمجة التطبيقات (API Access)](api-access.md).

لا يوجد مفتاح LinkedIn منفصل لإنشائه أو تدويره أو إلغائه. يعمل المفتاح بصفتك أنت، وبنفس الأذونات التي تمتلكها في التطبيق، لذا تعامل معه ككلمة مرور. سيؤدي إلغاؤه في الإعدادات إلى قطع اتصال كل برنامج نصي ومساعد متصل على الفور.

## الاتصال بواجهة برمجة التطبيقات مباشرة

- **عنوان URL الأساسي:** `https://app.sdrpilot.ai/api/v1`
- **الترويسة (Header):** `X-API-Key: YOUR_API_KEY`
- **وصف قابل للقراءة آلياً:** `https://app.sdrpilot.ai/api/v1/docs/openapi.yaml`
  (متاح أيضاً كـ `.json`)

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

تعمل `Authorization: Bearer YOUR_API_KEY` أيضاً. ما لا يمكنك فعله هو إرسال مفتاح خاطئ وتوقع أن يتم تمريره لشيء آخر: بمجرد تقديم مفتاح، تستند الإجابة إلى ذلك المفتاح.

ما الذي يظهر عند حدوث خطأ:

| الاستجابة | ماذا يعني ذلك |
|---|---|
| `401` | المفتاح مفقود أو غير منسق بشكل صحيح أو غير مقبول. |
| `403` | المفتاح صالح، ولكن ذلك الحساب لا يحتوي على مساحة عمل LinkedIn، أو لم يُسمح له بالدخول بعد. |
| `429` | عدد كبير جداً من المحاولات المرفوضة في دقيقة واحدة لهذا المفتاح. أبطئ وتيرتك. |
| `502` `dmchamp_unreachable` | لم نتمكن من التحقق من مفتاحك في تلك اللحظة. لا يتم التعامل معه أبداً كإذن مرور. حاول مرة أخرى. |

## توصيل مساعد ذكاء اصطناعي

تتواجد أدوات LinkedIn على نفس نقطة نهاية MCP الخاصة بـ <span data-t="appName">DM Champ</span>، مع نفس مفتاح واجهة برمجة التطبيقات، لذا فإن المساعد الذي قمت بتوصيله بالفعل سيتعرف عليها تلقائياً. إذا لم تقم بتوصيل مساعد بعد، فاتبع [توصيل مساعدي الذكاء الاصطناعي (MCP)](connect-ai-clients.md) واستخدم نقطة النهاية المدرجة هناك.

::: master-only
نقطة النهاية هي `https://mcp.youraiconnector.com/mcp`، ويتم المصادقة عليها باستخدام ترويسة `X-API-Key`، تماماً كما هو موضح في توصيل مساعدي الذكاء الاصطناعي (MCP).
:::

يتم تمييز جميع أدوات LinkedIn بالبادئة **`linkedin_`**، مما يسهل العثور عليها في قائمة أدوات المساعد الخاص بك وطلبها بالاسم ("استخدم أدوات LinkedIn لتظهر لي ما هو موجود في قائمة الانتظار"). لا توجد أذونات لكل أداة على حدة: يمكن للأداة القيام بأي شيء يمكنك القيام به في التطبيق.

## مثال 1 — قبول العملاء المحتملين من دول معينة فقط

يحتوي ملف تعريف ICP الخاص بك على القواعد التي يجب أن يستوفيها العملاء المحتملون. هذا يحدد قائمة مسموح بها تشمل هولندا وبلجيكا. رموز الدول تتكون من حرفين، بأحرف كبيرة.

```bash
curl -X PUT https://app.sdrpilot.ai/api/v1/icp/YOUR_ICP_ID/filters \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"countries":{"mode":"allow","codes":["NL","BE"]}}'
```

أمران يجب معرفتهما. النص الأساسي هو المجموعة **الكاملة** من القواعد، وليس تصحيحاً: أي قاعدة تغفل عن ذكرها سيتم إيقاف تشغيلها. وتتضمن الإجابة كتلة `impact_on_queue` تخبرك بعدد طلبات الاتصال الموجودة بالفعل في قائمة الانتظار والتي لن تستوفي القواعد الجديدة، على سبيل المثال `{"examined": 389, "would_withdraw": 155}`.
حفظ القواعد لا يؤدي إلى سحب أي شيء من تلقاء نفسه.

في المساعد، يمكنك ببساطة قول: "اضبط ملف تعريف ICP الخاص بي ليقبل هولندا وبلجيكا فقط، وأخبرني بما سيؤدي ذلك إلى قائمة الانتظار الخاصة بي."

## مثال 2 — معرفة ما هو موجود في قائمة الانتظار

طلبات الاتصال التي تمت الموافقة عليها ولكن لم يتم إرسالها بعد:

```bash
curl -s "https://app.sdrpilot.ai/api/v1/connections/queue?status=queued&limit=100" \
  -H "X-API-Key: YOUR_API_KEY"
```

يحمل كل صف اسم الشخص، والعنوان الرئيسي، والشركة، والموقع، والدولة، وعدد اتصالاته ومتابعيه، والنتيجة. يمكنك تضييق نطاق القائمة باستخدام `country` و `min_score` و `max_score` و `source`، والتنقل بين صفحاتها باستخدام `limit` و `cursor`. تظهر هنا فقط الطلبات الموجودة في قائمة الانتظار وتلك التي تنتظر الموافقة. الطلبات التي تم إرسالها بالفعل تعتبر تاريخاً ولا يمكن تغييرها.

## مثال 3 — سحب طلبات الجميع خارج دولك

بعد تغيير قواعدك، أعد فحص قائمة الانتظار مقابلها. بدون `apply=true`، يعد هذا معاينة ولا يغير شيئاً:

```bash
curl -X POST "https://app.sdrpilot.ai/api/v1/connections/queue/rescreen" \
  -H "X-API-Key: YOUR_API_KEY"
```

ستحصل على عدد الأشخاص الذين تم فحصهم، وعدد الطلبات التي سيتم سحبها، وتفصيل لكل قاعدة، مثل `country` و `network_too_small` (كانت شبكة العميل المحتمل أصغر من الحد الأدنى الخاص بك). هل أنت راضٍ عن ذلك؟ قم بتشغيله مرة أخرى باستخدام `?apply=true` وسيتم سحب تلك الطلبات.

```bash
curl -X POST "https://app.sdrpilot.ai/api/v1/connections/queue/rescreen?apply=true" \
  -H "X-API-Key: YOUR_API_KEY"
```

إذا كنت تفضل سحب مجموعة محددة، فقم بنشر المعرفات (ids) بدلاً من ذلك، أو استخدم عامل تصفية مثل `{"filter":{"status":"queued","country":"NG"}}` لتفريغ كل ما يطابق. أرسل المعرفات أو عامل تصفية، وليس كلاهما.

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

- **`401` في كل استدعاء** — المفتاح مفقود أو خاطئ. انسخه مرة أخرى من الإعدادات (Settings) → عمليات التكامل (Integrations) → مفتاح API.
- **`403` على الرغم من أن المفتاح يعمل في مكان آخر** — هذا الحساب غير مرتبط بمساحة عمل LinkedIn، أو أن LinkedIn لم يتم تفعيله له بعد.
- **`502 dmchamp_unreachable`** — خلل مؤقت في التحقق من مفتاحك. لم يتم السماح بمرور أي شيء؛ حاول مرة أخرى.
- **قاعدة لا تطابق شيئاً** — يجب أن تكون رموز الدول بصيغة الحرفين الكبيرين (`NL`، وليس `Netherlands` أو `nl`)، ويجب أن تكون رموز اللغة بأحرف صغيرة.
- **المساعد لا يظهر أي أدوات LinkedIn** — أعد توصيله ليقوم بإعادة تحميل قائمة الأدوات، وتأكد من أنك تستخدم نفس مفتاح API.

---

## الخطوات التالية

- [ربط مساعدي الذكاء الاصطناعي (MCP)](connect-ai-clients.md) — قم بإعداد Claude أو ChatGPT أو Cursor باستخدام مفتاحك.
- [الوصول إلى API](api-access.md) — قم بإنشاء أو تدوير المفتاح الذي يستخدمه هذا.