> ## Documentation Index
> Fetch the complete documentation index at: https://docs.linkiasoft.com/llms.txt
> Use this file to discover all available pages before exploring further.

# العمل مع العملاء المحتملين

> قراءة مسارك، ونقل عميل محتمل بين المراحل، وتسجيل المتابعات.

نقاط نهاية إدارة العملاء تعمل على مضيف مختلف عن المراسلة — `https://api.linkiasoft.com/api` —
لكنها تأخذ **مفتاح API نفسه**. وترويستا [المصادقة](/ar/authentication) تنطبقان دون تغيير.

<Warning>
  اقرأ [مراحل المسار](#stages-are-keys-not-names) قبل كتابة أي شيء ينقل عميلًا محتملًا. فالخطأ هنا
  هو الطريقة الأشيع لانكسار هذه التكاملات.
</Warning>

<h2 id="stages-are-keys-not-names">
  المراحل مفاتيح لا أسماء
</h2>

مرحلة العميل المحتمل مخزَّنة في حقل `status` كـ**مفتاح مرحلة** — أي معرّف ثابت. أما ما تراه على
اللوحة فهو `name` المرحلة، ويستطيع أي شخص تغييره في أي وقت.

```bash theme={null}
curl https://api.linkiasoft.com/api/v1/lead-stages \
  -H "x-api-key: $LINKIA_API_KEY" \
  -H "X-Tenant-Id: $LINKIA_TENANT_ID"
```

```json theme={null}
[
  { "key": "new",       "name": "New",       "position": 0, "is_default": true },
  { "key": "qualified", "name": "Qualified", "position": 1 },
  { "key": "won",       "name": "Closed Won", "position": 2, "is_won": true },
  { "key": "lost",      "name": "Closed Lost", "position": 3, "is_lost": true }
]
```

وقاعدتان تتبعان ذلك:

* **أرسل `key` لا `name` أبدًا.** فـ`status: "qualified"` ينقل العميل المحتمل، أما
  `status: "Qualified"` فلا.
* **احكم على النتائج بـ`is_won` / `is_lost`، لا بمقارنة المفتاح بـ`"won"`.** فالمستأجرون يعيدون
  تسمية مراحلهم ومفاتيحها. ومسار فيه `closed_deal` بدل `won` أمر طبيعي، والشيفرة التي تطابق النص
  الحرفي تُبلّغ بصفر تحويلات بصمت.

اجلب قائمة المراحل مرة عند الإقلاع وخزّنها مؤقتًا، بدل تثبيت المفاتيح في الشيفرة.

## عرض العملاء المحتملين في مرحلة

```bash theme={null}
curl "https://api.linkiasoft.com/api/v1/leads?status=qualified&limit=20" \
  -H "x-api-key: $LINKIA_API_KEY" \
  -H "X-Tenant-Id: $LINKIA_TENANT_ID"
```

```json theme={null}
{
  "data": [
    {
      "id": "5e6f7a8b-9c0d-4e1f-2a3b-4c5d6e7f8a9b",
      "name": "Ahmed Hassan",
      "company_name": "Acme Trading",
      "phone": "201001234567",
      "status": "qualified",
      "value": 25000,
      "currency": "EGP",
      "assigned_to_user_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 20,
  "totalPages": 3,
  "hasMore": true
}
```

<Note>
  عند قراءة لوحة كاملة، صفّح بـ`offset` لا بـ`page`. فانتقال عميل محتمل خارج المرحلة أثناء القراءة
  يزيح النافذة المرقّمة بالصفحات ويجعلك تتخطى صفًا. و`offset` يتقدم على `page` عند إرسال الاثنين.
</Note>

ولعدّ الأعمدة دون جلب كل عميل محتمل، استخدم
[`GET /v1/leads/stage-counts`](/api-reference/leads/count-leads-per-stage).

## نقل عميل محتمل إلى مرحلة أخرى

التنقل عبر المسار مجرد تحديث لـ`status`:

```bash theme={null}
curl -X PATCH https://api.linkiasoft.com/api/v1/leads/$LEAD_ID \
  -H "x-api-key: $LINKIA_API_KEY" \
  -H "X-Tenant-Id: $LINKIA_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{ "status": "won" }'
```

أرسل الحقول التي تغيّرها فقط. ونقطة النهاية نفسها تحدّث تفاصيل الصفقة:

```json theme={null}
{ "value": 25000, "currency": "EGP", "priority": "high", "expected_close_date": "2026-09-30" }
```

ولتسليم عميل محتمل إلى مندوب آخر، استخدم
[`PATCH /v1/leads/{id}/reassign`](/api-reference/leads/reassign-a-lead-to-another-user)
بدل ضبط `assigned_to_user_id` مباشرة.

<h2 id="mark-a-follow-up">
  تسجيل متابعة
</h2>

**لا توجد علامة متابعة على العميل المحتمل.** فالمتابعة نشاط قيمة `outcome` فيه هي
`follow_up_needed`:

```bash theme={null}
curl -X POST https://api.linkiasoft.com/api/activities/lead/$LEAD_ID \
  -H "x-api-key: $LINKIA_API_KEY" \
  -H "X-Tenant-Id: $LINKIA_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "activity_type": "call",
    "subject": "Discussed pricing",
    "activity_date": "2026-07-25T10:30:00Z",
    "duration_minutes": 15,
    "outcome": "follow_up_needed"
  }'
```

و`activity_type` واحدة من `call` أو `email` أو `meeting` أو `note` أو `task` أو `deal` أو
`support_ticket` أو `sms`. و`outcome` واحدة من `successful` أو `follow_up_needed` أو `no_answer`
أو `completed` أو `cancelled`.

<Warning>
  مسارات الأنشطة **بلا بادئة `/v1`** — `/api/activities/...` لا `/api/v1/activities/...`. والأمر
  نفسه ينطبق على جهات الاتصال. أما العملاء المحتملون والمراحل فيستخدمون `/v1`.
</Warning>

## جهات الاتصال في شركة

**العميل** هو الشركة، و**جهات الاتصال** هم الأشخاص فيها.

```bash theme={null}
curl https://api.linkiasoft.com/api/contacts/customer/$CUSTOMER_ID \
  -H "x-api-key: $LINKIA_API_KEY" \
  -H "X-Tenant-Id: $LINKIA_TENANT_ID"
```

وكل جهة اتصال تحمل `mobile` إلى جانب `phone` — فضّل `mobile` حين تنوي مراسلتهم على واتساب، ولاحظ
أن `is_primary` تحدد جهة الاتصال الرئيسية.

## النطاقات

| لتفعل هذا                                 | يحتاج المفتاح      |
| ----------------------------------------- | ------------------ |
| قراءة العملاء المحتملين والمراحل والأنشطة | `leads:read`       |
| إنشاء عميل محتمل                          | `leads:create`     |
| نقل مرحلة، أو إعادة إسناد، أو تسجيل نشاط  | `leads:update`     |
| حذف عميل محتمل                            | `leads:delete`     |
| قراءة العملاء وجهات الاتصال               | `customers:read`   |
| إنشاء جهة اتصال أو تعديلها                | `customers:update` |

وجهات الاتصال والأنشطة محكومة بنطاقَي `customers` و`leads` — فلا يوجد نطاق `contacts` أو
`activities`. والمفتاح الذي يفتقر إلى النطاق يحصل على `403` مع تسمية ما ينقصه.

## الجمع بينها

الاقتران البديهي مع واجهة المراسلة: حين يبلغ عميل محتمل مرحلة ما، راسله.

<Steps>
  <Step title="اكتشف التغيير">
    استطلع [`GET /v1/leads`](/api-reference/leads/list-leads) مُصفّى على المرحلة، أو شغّل من
    الشيء الذي نقل العميل المحتمل أصلًا.
  </Step>

  <Step title="احصل على رقم">
    `phone` العميل المحتمل نفسه، أو `mobile` جهة الاتصال الرئيسية من
    [`GET /contacts/customer/{customerId}`](/api-reference/contacts/list-contacts-for-a-company).
    وطبّعه إلى E.164 بدون `+` — راجع [البداية السريعة](/ar/quickstart).
  </Step>

  <Step title="أرسل قالبًا">
    [`POST /v1/conversations/send`](/api-reference/conversations/send-a-message) على
    `social.linkiasoft.com`. وخارج نافذة الـ 24 ساعة يجب أن يكون قالبًا.
  </Step>

  <Step title="سجّل ما فعلته">
    أنشئ نشاطًا على العميل المحتمل حتى يراه المندوب في الخط الزمني.
  </Step>
</Steps>