# إسناد العملاء المحتملين وتصفيتهم وحقولهم

> أسند عملاء مجيب المحتملين إلى زملائك، واعرضهم حسب المسؤول أو حسب حقل مخصّص، وثبّتهم، وأضف حقول الوكيل المخصّصة للعملاء المحتملين أو غيّرها أو احذفها عبر الواجهة البرمجية العامة.

حين يصل العملاء المحتملون، يوزّعهم فريقك ويرتّبهم. عبر الواجهة البرمجية العامة يستطيع نظام CRM أو الأتمتة لديك فعل الشيء نفسه: إسناد كل عميل محتمل إلى الزميل المناسب، وعرض عملاء زميل أو العملاء المطابقين لحقل مخصّص، وتثبيت ما يحتاج إلى انتباه، وتشكيل نموذج العملاء المحتملين للوكيل، الذي يحدّد أيضاً ما يجمعه الذكاء الاصطناعي حين يحفظ عميلاً محتملاً. كل نقطة نهاية تقع تحت وكيل واحد: `/v1/agents/{agentId}/…`.

## كيف أُسند عميلاً محتملاً إلى زميل؟

أرسل `user_id` الخاص بالزميل في `assigned_to` بـ `POST` إلى نقطة `assign` الخاصة بالعميل المحتمل. يصبح الزميل **المسؤول** عن العميل في لوحة التحكم، وتُسنَد إليه محادثة العميل أيضاً. ويجب أن يستطيع الزميل فتح الوكيل.

```bash
curl -X POST https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/leads/LEAD_ID/assign \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "assigned_to": "TEAMMATE_USER_ID", "reason": "Handles the Riyadh branch." }'
```

اعثر على `user_id` عبر [عرض أعضاء الفريق لوكيل](../api-reference/list-agent-members): لا يُسنَد العميل إلا إلى الزملاء الذين قيمة `can_open_agent` لديهم `true`. وأي شخص آخر يُعيد `422 assignee_not_allowed` ولا يتغيّر شيء. و`reason` اختياري، ويُحفظ مع الإسناد في سجلات مجيب. والرد هو العميل المحتمل بقيمة `assigned_to` الجديدة. راجع [مرجع إسناد عميل محتمل أو إلغاء إسناده](../api-reference/assign-lead).

## كيف أُلغي إسناد عميل محتمل؟

أرسل `assigned_to` بقيمة `null` بـ `POST` إلى نقطة `assign` الخاصة بالعميل المحتمل. بعدها يظهر العميل في لوحة التحكم **بدون مسؤول**. والحقل مطلوب، فيُرفض الجسم الفارغ بدل أن يُلغى إسناد عميل بالخطأ.

```bash
curl -X POST https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/leads/LEAD_ID/assign \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "assigned_to": null }'
```

## كيف أعرض عملاء زميل، أو العملاء غير المُسنَدين؟

أضف `assigned_to` إلى قائمة العملاء المحتملين: `user_id` لزميل، أو `unassigned` للعملاء غير المُسنَدين لأحد. ويجتمع مع بقية المرشحات، مثل `status`، فلا يظهر العميل إلا إذا طابقها كلها.

```bash
curl "https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/leads?assigned_to=unassigned&status=new" \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE"
```

لا تُقبل القيمة `me`، لأن المفتاح ليس شخصاً: هي وأي قيمة أخرى تُعيد `422 invalid_request_body` مع `param` بقيمة `assigned_to`. راجع [مرجع عرض العملاء المحتملين](../api-reference/list-leads).

## كيف أصفّي العملاء المحتملين حسب حقل مخصّص؟

مرّر `custom_fields`: كائن JSON مُرمَّز للرابط (URL-encoded) يربط مفتاح الحقل بشرط، أي `op` مع قيمه في `values`. ومع curl يتولى `-G` و`--data-urlencode` الترميز عنك.

```bash
curl -G https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/leads \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  --data-urlencode 'custom_fields={"city":{"op":"eq","values":["Cairo"]},"visit_date":{"op":"between","values":["2026-10-01","2026-11-01"]}}'
```

| `op` | `values` | يطابق العميل حين يكون الحقل |
|---|---|---|
| `eq` | قيمة واحدة | مساوياً للقيمة |
| `in` | قيمة أو أكثر | مساوياً لإحدى القيم |
| `ilike` | قيمة واحدة | محتوياً القيمة دون اعتبار لحالة الأحرف؛ ويعمل `%` و`_` كأحرف بدل |
| `between` | قيمتان | بين القيمة الأولى، وهي مشمولة، والثانية، وهي غير مشمولة |
| `is_null` | لا قيم | بلا قيمة |

تُقارَن القيم بالقيمة المخزّنة كنص. اكتب التواريخ بصيغة `YYYY-MM-DD` ليرتّبها `between` ترتيباً صحيحاً، ولا تتوقع أن تُقارَن الأرقام حسب حجمها. وتجتمع الشروط بـ AND، والعميل الذي لا قيمة له تحت مفتاحٍ لا يطابق هناك إلا `is_null`. وعدد المفاتيح والقيم في الطلب محدود؛ راجع [مرجع عرض العملاء المحتملين](../api-reference/list-leads).

## كيف أثبّت عميلاً محتملاً أو أُلغي تثبيته؟

أرسل `PATCH` إلى العميل المحتمل بـ `pinned`: القيمة `true` تثبّته لكل من يعمل على الوكيل، كما يفعل **تثبيت** في لوحة التحكم، و`false` تُلغي تثبيته. ويأتي العملاء المثبَّتون أولاً، في الصفحة الأولى من القائمة.

```bash
curl -X PATCH https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/leads/LEAD_ID \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "pinned": true }'
```

إرسال الحالة التي عليها العميل أصلاً لا يغيّر شيئاً، فيحتفظ العميل المثبَّت بمكانه. ولا تحوي الصفحات التالية من القائمة عملاء مثبَّتين، فأبقِ عدد المثبَّتين أقل من قيمة `limit` التي تعرض بها. راجع [مرجع تحديث عميل محتمل](../api-reference/update-lead).

## كيف أضيف حقلاً للعملاء المحتملين؟

أرسل بـ `POST` مفتاحاً في `key` وتسمية في `label` ونوعاً في `type` إلى حقول العملاء المحتملين للوكيل. يُضاف الحقل بعد حقول الوكيل المخصّصة الأخرى، في نموذج العميل المحتمل وعموداً في جدول العملاء في لوحة التحكم، وتبدأ أداة [حفظ عميل](/docs/tools/capture-lead) في جمعه في الخلفية، عادةً خلال دقيقة.

```bash
curl -X POST https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/lead-fields \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "key": "preferred_branch", "label": "Preferred branch", "type": "enum", "options": [ { "value": "riyadh", "label": "Riyadh" }, { "value": "jeddah", "label": "Jeddah" } ] }'
```

التسمية تخبر الذكاء الاصطناعي بما يسأل عنه، فاكتبها كما تشرح الحقل لزميل جديد. و`"required": true` يجعل الذكاء الاصطناعي يعدّ الحقل لازماً قبل أن يحفظ عميلاً محتملاً. يأخذ حقل `enum` خياراته في `options`، ولا تأخذ الأنواع الأخرى خيارات. والمفتاح هو مكان القيمة في `custom_fields` لكل عميل، ولا يتغيّر لاحقاً.

المفتاح الذي يحجزه مجيب، مثل `name` أو `status` أو `source`، يُعيد `422 invalid_request`. وأي مفتاح آخر لدى الوكيل أصلاً، ومنه الحقول المدمجة مثل `notes`، يُعيد `409 field_key_taken`، والوكيل الذي لا يتسع لحقل مخصّص آخر يُعيد `422 lead_field_limit_reached`. صيغة المفتاح والأنواع والحدود في [مرجع إضافة حقل](../api-reference/create-lead-field).

## كيف أغيّر حقلاً للعملاء المحتملين؟

أرسل `PATCH` إلى حقل مخصّص بمفتاحه لتغيير تسميته `label`، أو هل هو مطلوب `required`، أو خياراته `options`. أرسل ما يتغيّر فقط. يبقى المفتاح والنوع كما هما؛ ولنوع آخر أضف حقلاً جديداً. ويتبع الذكاء الاصطناعي التغيير في الخلفية، عادةً خلال دقيقة.

```bash
curl -X PATCH https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/lead-fields/preferred_branch \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{ "options": [ { "value": "riyadh", "label": "Riyadh" }, { "value": "jeddah", "label": "Jeddah" }, { "value": "dammam", "label": "Dammam" } ] }'
```

تحل `options` محل كل الخيارات، بالترتيب الذي ترسله. والخيار الذي تبقى قيمته `value` يحتفظ بما ضبطته عليه لوحة التحكم، مثل لونه، ويحتفظ العملاء بالقيم التي تزيلها. ويُطابَق المفتاح في المسار حرفياً، بما في ذلك حالة الأحرف، والمفتاح الذي لا حقل له لدى الوكيل يُعيد `404 not_found`. ولا تُغيَّر الحقول المدمجة، ومنها حالات العملاء المحتملين، عبر الواجهة البرمجية (`422 system_field`). راجع [مرجع تغيير حقل](../api-reference/update-lead-field).

## كيف أحذف حقلاً للعملاء المحتملين؟

أرسل `DELETE` إلى حقل مخصّص بمفتاحه. يخرج الحقل من نموذج العملاء المحتملين للوكيل نهائياً، ويتوقف الذكاء الاصطناعي عن جمعه في الخلفية، عادةً خلال دقيقة. والرد `204` بلا جسم.

```bash
curl -X DELETE https://api.mojeeb.app/v1/agents/YOUR_AGENT_ID/lead-fields/preferred_branch \
  -H "Authorization: Bearer mk_live_YOUR_KEY_HERE"
```

يحتفظ العملاء بالقيم التي كانت لهم تحت المفتاح: تظل الواجهة البرمجية تعيدها في `custom_fields`، ويتوقف جدول لوحة التحكم عن عرضها، وتظهر مجدداً إن أضفت حقلاً بالمفتاح نفسه. ولا تُحذف الحقول المدمجة (`422 system_field`). راجع [مرجع حذف حقل](../api-reference/delete-lead-field).

## أسئلة شائعة

### من يُسجَّل صاحباً للإسناد عبر الواجهة البرمجية؟

الشخص الذي أنشأ المفتاح. يسجّل مجيب الإسناد باسمه إسناداً يدوياً، كما يسجّله كاتباً لملاحظات المفتاح.

### ماذا يعني `422 assignee_not_allowed`؟

لا يستطيع الزميل فتح الوكيل: فهو مقيّد بوكلاء آخرين، أو غادر منظمتك، أو أن المعرّف ليس لأحد زملائك. اختر شخصاً قيمة `can_open_agent` لديه `true`، أو امنحه الوكيل من لوحة التحكم أولاً؛ راجع [إدارة الفريق](/docs/features/team-management). وإن تعذّر على مجيب فحص صلاحية الزميل، يكون الرد `503 access_unavailable` بدلاً من ذلك: أعد المحاولة بتراجع متصاعد.

### لماذا يُعيد `assigned_to=me` الخطأ 422؟

المفتاح ليس شخصاً، فليس له عملاء خاصون به. استخدم `user_id` للزميل الذي تقصده، من [عرض أعضاء الفريق لوكيل](../api-reference/list-agent-members).

### هل أستطيع إسناد عميل محتمل إلى الزميل المُسنَد إليه أصلاً؟

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

### لماذا لا يُعيد مرشح الحقل المخصّص شيئاً؟

تحقّق من أربعة أمور. يجب أن يطابق المفتاح مفتاح الحقل حرفياً، بما في ذلك حالة الأحرف. ويطابق `eq` و`in` النص المخزّن حرفياً، فاستخدم `ilike` لتجاهل حالة الأحرف. ويستثني `between` قيمته الثانية، فلتشمل آخر يوم في شهر اجعل النهاية أول يوم في الشهر التالي. وتُقارَن الأرقام كنص.

### هل أستطيع تصفية الأرقام حسب حجمها؟

لا. تُقارَن القيم كنص، فلا يتبع `between` الترتيب العددي. استخدم `eq` أو `in` بالقيم الدقيقة، أو صفِّ الأرقام في نظامك.

### هل أستطيع تغيير نوع الحقل أو مفتاحه؟

لا. أضف حقلاً جديداً بالمفتاح والنوع اللذين تحتاجهما. والحقل الذي تحذفه ثم تضيفه بالمفتاح نفسه ونوع آخر يجد القيم القديمة كما كانت، دون تحويل.

### هل أستطيع تغيير حالات العملاء المحتملين عبر الواجهة البرمجية؟

ليس بعد. الحالات هي خيارات الحقل المدمج `status`، والحقول المدمجة لا تُغيَّر عبر الواجهة البرمجية (`422 system_field`). عدّلها من لوحة التحكم عبر **تعديل الحالات**. أما نقل عميل محتمل من حالة إلى أخرى فيعمل عبر الواجهة؛ راجع [جهات الاتصال والملاحظات والعملاء المحتملون](./contacts-and-leads).

### لماذا أعاد إنشاء الحقل 409؟

لدى الوكيل حقل بهذا المفتاح أصلاً، ومنه الحقول المدمجة، ولم يُنشأ شيء. والإنشاء الذي تعيد محاولته بعد رد ضائع ينتهي هنا أيضاً: اعرض حقول العملاء المحتملين وتابع.

### لماذا لا يجمع الذكاء الاصطناعي حقلاً أضفته؟

لا تلتقط أداة حفظ عميل تغييرات الحقول إلا وهي مفعّلة. فإن كانت متوقفة، شغّلها من بطاقتها في صفحة الأدوات، ثم افتح **تعديل الأعمدة** في صفحة العملاء واحفظ مرة واحدة، كما تشرح صفحة [حفظ عميل](/docs/tools/capture-lead).

### هل أستطيع تثبيت أي عدد من العملاء المحتملين؟

نعم، لا حد لذلك، لكن القائمة لا تعيد العملاء المثبَّتين إلا في صفحتها الأولى، في الواجهة البرمجية ولوحة التحكم على السواء. ثبّت ما يحتاج إلى انتباه الآن فقط، وألغِ تثبيت العميل بعد إنجازه.

### هل أستطيع حذف عميل محتمل؟

نعم: `DELETE /v1/agents/{agentId}/leads/{leadId}` يحذفه نهائياً دون تراجع، وحذف العميل نفسه مرة ثانية يُعيد `404 not_found`. وتبقى جهة الاتصال وملاحظاتها والمحادثة. ولإخراج عميل من العمل المفتوح لفريقك دون أن تفقده، انقله إلى حالة نهائية بدلاً من حذفه. راجع [جهات الاتصال والملاحظات والعملاء المحتملون](./contacts-and-leads).