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

# إدارة علاقات العملاء للمبيعات

> إدارة العملاء المحتملين والمنتجات ودفاتر الأسعار ومسودات عروض الأسعار عبر واجهات معزولة حسب الحساب.

واجهة Sales CRM هي الواجهة البرمجية التي تدعم مساحة **المبيعات** في HueChat.
تجمع السجلات اليدوية مع العملاء القادمين من واتساب وإنستغرام وماسنجر
والنماذج والمواعيد والإعلانات، وتوفر كتالوج المنتجات ودفاتر الأسعار وسجل
مسودات عروض الأسعار. يبقى كل سجل معزولاً داخل الحساب الذي أصدر مفتاح API.

## قبل البدء

أنشئ مفتاح API مقيّداً من **الحساب ← واجهة المطور** بصلاحية `leads:read` لعرض العملاء
وقراءة تفاصيلهم وسجلهم. أضف `leads:write` للإنشاء أو تغيير الحالة. يحتاج
التحويل أيضاً إلى `deals:write`. يبقى إنشاء المفتاح وتدويره وإلغاؤه داخل
تطبيق HueChat الموثق.

يجب تفعيل ميزتي **الصفقات** و**عملاء المبيعات المحتملين** في خطة الحساب.
يعيد الخادم `402` مع `code: "plan_disabled"` عندما تكون إحداهما معطلة، حتى
إذا كانت صلاحيات المفتاح صحيحة. يتم هذا الفحص قبل قراءة بيانات العملاء أو
تغييرها.

تتطلب المنتجات ودفاتر الأسعار وعروض الأسعار ميزتي **الصفقات** و**منتجات
وعروض المبيعات**. استخدم `deals:read` لمسارات العرض و`deals:write` لمسارات
الإنشاء والأرشفة وإضافة بنود الأسعار. ينطبق عقد الخطأ `402` نفسه قبل قراءة أي
بيانات تابعة للحساب.

<Warning>
  استخدم معرّف الحساب الذي أصدر المفتاح. لا يتم حل عميل أو جهة اتصال أو شركة أو
  فرع أو محادثة أو صفقة من حساب آخر.
</Warning>

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

لا يحمل مفتاح API هوية عضو فريق، لذلك أرسل `owner_id` للعضو الذي سيملك
العميل. يمكن لتطبيق HueChat عند استخدام جلسة عضو مصادق عليه حذف هذا الحقل.
تُحفظ بيانات العميل وأول سجل للحالة وأول سجل للملكية في معاملة واحدة، لذلك
لا يُحفظ عميل بلا مالك.

```bash theme={null}
curl -X POST "https://app.huechat.ai/api/v2/accounts/$ACCOUNT_ID/leads" \
  -H "Authorization: Bearer $HUECHAT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "manual",
    "owner_id": 42,
    "full_name": "سارة العتيبي",
    "phone": "+966501234567",
    "email": "sara@example.com",
    "company": "شركة المثال",
    "rating": "warm",
    "product_interest": "إدارة تفاعل العملاء",
    "next_action": "تحديد مكالمة استكشاف",
    "next_action_at": "2026-09-21T09:00:00Z",
    "dedup_key": "crm-import-8842"
  }'
```

القيمة `source: "ad"` مرفوضة عمداً. تكاملات Meta وTikTok وSnap وGoogle هي
المسؤولة عن هذه السجلات، فلا يستطيع عميل API إنشاء سجل يبدو كأنه نتيجة حملة
إعلانية حقيقية.

## العرض والتصفية

استخدم `GET /api/v2/accounts/{accountId}/leads`. تعود النتائج من الأحدث إلى
الأقدم. استخدم `page` و`per_page` (بحد أقصى 100)، ويمكنك التصفية بواسطة
`source` أو `status` أو `owner_id` أو `branch_id` أو `unassigned=true`.

```bash theme={null}
curl --get "https://app.huechat.ai/api/v2/accounts/$ACCOUNT_ID/leads" \
  -H "Authorization: Bearer $HUECHAT_API_KEY" \
  --data-urlencode "status=qualified" \
  --data-urlencode "per_page=30"
```

## تغيير حالة التأهيل

أرسل الحالة إلى `/leads/{leadId}/status`. الحالات المدعومة هي `new`
و`working` و`qualified` و`disqualified` و`processed`. أرسل
`disqualified_reason` عند الاستبعاد، ويمكن استخدام `recycle_at` لإعادة العميل
لاحقاً.

لا ترسل `converted` إلى هذه النقطة. للتحويل نقطة مستقلة لأنها تملك ربط الصفقة
وضمان التكرار الآمن.

## تحويل عميل محتمل مؤهل

تستطيع `POST /leads/{leadId}/convert` ربط العميل بصفقة موجودة، أو إنشاء الشركة
والصفقة اللتين راجعهما المستخدم في معاينة التحويل ضمن معاملة واحدة. أرسل
ترويسة `Idempotency-Key` فريدة؛ يعيد تكرار المفتاح النتيجة الأصلية، بينما
يعيد استخدامه لعميل آخر `409`.

```bash theme={null}
curl -X POST "https://app.huechat.ai/api/v2/accounts/$ACCOUNT_ID/leads/$LEAD_ID/convert" \
  -H "Authorization: Bearer $HUECHAT_API_KEY" \
  -H "Idempotency-Key: lead-conversion-8842" \
  -H "Content-Type: application/json" \
  -d '{
    "deal_id": "b8cb6c91-a805-41f4-ac4f-beb462bb7a31",
    "reason": "اكتملت مكالمة الاستكشاف"
  }'
```

لإنشاء فرصة جديدة أرسل `create_deal: true` واسم الصفقة والمبلغ والعملة وتاريخ
الإغلاق وفئة التوقع. ينشئ `create_company: true` مع `company_name` الشركة في
المعاملة نفسها. إذا حُوّل العميل بمفتاح آخر أو ارتبط بصفقة أخرى يعيد الخادم
`409`.

## قراءة سجل التدقيق

تعيد `GET /leads/{leadId}/history` قائمتي `status_history` و
`ownership_history` كسجلين متتابعين غير قابلين لإعادة الكتابة، من الأحدث إلى
الأقدم وبحد 200 إدخال لكل قائمة. استخدم هذه الإيصالات للمزامنة والتدقيق بدلاً
من استنتاج التاريخ من القيم الحالية فقط.

## المنتجات والخدمات

استخدم `GET /sales/products` لعرض كتالوج الحساب مع مرشحات `q` و`active`
و`page` و`per_page`. أنشئ منتجاً أو خدمة عبر `POST /sales/products`، وأرسل
`standard_price` كنص عشري دقيق مثل `"1250.00"`، مع رمز عملة من ثلاثة أحرف
كبيرة. استخدم `PATCH /sales/products/{productId}/active` للأرشفة أو الاستعادة.

رمز SKU فريد داخل الحساب فقط. تواريخ الصلاحية تواريخ تقويمية، ولا يمكن أن
يسبق `valid_until` قيمة `valid_from` عند إرسالهما معاً.

## دفاتر الأسعار

أنشئ دفاتر الأسعار واعرضها في `/sales/price-books`. تُدار بنود الدفتر عبر
`/sales/price-books/{priceBookId}/entries`، ويحفظ كل بند سعر قائمة لمنتج نشط.
يجب أن يكون الدفتر والمنتج نشطين ومن الحساب نفسه وبالعملة نفسها. تكرار المنتج
نفسه داخل دفتر واحد يعيد `409`.

استنسخ دفتراً كاملاً عبر
`POST /sales/price-books/{priceBookId}/clone` مع `name` فريد. تتم العملية داخل
معاملة واحدة، وتنسخ البنود النشطة والمؤرشفة، وتنشئ دائماً دفتراً مخصصاً حتى
لا تستبدل الدفتر القياسي للعملة.

## سجل المبيعات بزاوية 360 درجة

لا تنشئ المبيعات قاعدة عملاء ثانية. يرتبط العميل المحتمل بجهة الاتصال
الأساسية في Customer CDP، وتجمع الشركة العلاقات التجارية، وتحمل الصفقة خط
المبيعات والمهام والمنتجات والعروض والمدفوعات والمواعيد والنماذج والنشاط
المسموح من المحادثات. استخدم `GET /sales/overview` للملخص، و
`GET /sales/companies/{companyId}` لسجل الشركة، و
`GET /sales/deals/{dealId}` للسجل الكامل للفرصة. تعرض واجهات Customer CDP
هوية الشخص نفسه وموافقاته وعضوياته والرحلات والخط الزمني الموحد.

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

## المهام والعروض المحفوظة

المسار `/sales/tasks` هو قائمة العمل المشتركة للعملاء المحتملين والصفقات
والشركات وجهات الاتصال. تدعم المهمة التعيين إلى عضو أو طابور والأولوية
والتذكير والنتيجة والتكرار اليومي أو الأسبوعي أو الشهري. ينشئ إكمال المهمة
المتكررة الموعد التالي مرة واحدة فقط. تحفظ `/sales/saved-views` مرشحات القائمة
أو Kanban؛ وتبقى العروض الشخصية خاصة بصاحبها.

## عروض الأسعار ذات الإصدارات والمدفوعات

تعيد `GET /sales/quotes` سجل عروض الأسعار وتدعم `status` و`approval_status`
و`payment` و`deal_id` و`page` و`per_page`. استخدم `payment=requested` لطابور
روابط الدفع أو `payment=outstanding` للعروض المقبولة ذات الرصيد المتبقي.
تنشئ `POST /sales/quotes` المسودة وكل لقطات البنود في معاملة واحدة. أرسل من
بند واحد إلى 200 بند، ويحسب الخادم الإجمالي الفرعي والخصومات والضريبة
والإجمالي من مبالغ عشرية دقيقة بمنزلتين.

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

<Note>
  انتقالات دورة العرض صريحة. يسجل
  `PATCH /sales/quotes/{quoteId}/lifecycle` الإرسال أو العرض أو القبول أو الرفض
  أو الانتهاء، وينشئ `/revisions` مسودة بإصدار جديد. يتطلب القبول مفتاح تكرار
  آمن. يحافظ مسار دورة الحياة على حالتي الدفع والموافقة ولا يستطيع استبدالهما.
  يقرر مسؤول الحساب الموافقة المعلقة للخصم المرتفع عبر
  `PATCH /sales/quotes/{quoteId}/approval` بقيمة `approved` أو `rejected` وسبب
  تدقيق إلزامي. يسجل طلب الدفع المبلغ وحالة المزود، لكنه لا يعني أن المزود قبله
  أو سوّاه.
</Note>

### إرفاق ملف PDF لعرض السعر

يمكن لكل إصدار من عرض السعر الاحتفاظ بملف PDF واحد موقّع أو مصمم. ارفعه أو
استبدله بصيغة multipart، واعرضه أو نزّله أو احذفه من دون حذف العرض:

```bash theme={null}
curl -X POST \
  "https://app.huechat.ai/api/v2/accounts/$ACCOUNT_ID/sales/quotes/$QUOTE_ID/pdf" \
  -H "Authorization: Bearer $HUECHAT_API_KEY" \
  -F "file=@quotation.pdf;type=application/pdf"
```

يُقبل ملف PDF حقيقي حتى 20 MB فقط. الاستبدال آمن عند التزامن، ولا يُحذف
الملف السابق إلا بعد حفظ المرجع الجديد داخل الحساب. يعرض `GET .../pdf`
الملف، وينزله `GET .../pdf?download=1`، ويحذفه `DELETE .../pdf`.

### مشاركة عرض سعر خاص

أنشئ رابط العميل أو دوّره عبر
`POST /sales/quotes/{quoteId}/share-link`. يتطلب المسار صلاحية `deals:write`،
ويعيد الرابط الخام مرة واحدة فقط، وينقل المسودة إلى حالة `sent`. لا يمكن
مشاركة عرض ينتظر الموافقة أو رُفضت موافقته أو انتهت صلاحيته أو استُبدل بإصدار
أحدث.

لا يُخزن سر العميل إلا كبصمة مشفرة، ويوضع في جزء fragment من الرابط حتى لا
يظهر في عنوان طلب HTTP أو سجلات الوصول. ينتهي في تاريخ انتهاء العرض أو بعد
30 يوماً، أيهما أقرب، ويُلغي تدويره الرابط السابق فوراً. يسجل أول فتح حقيقي
حالة `viewed` ويعرض للعميل عرض السعر وبنوده وشروطه وملف PDF فقط، من دون كشف
الحساب أو مفتاح API أو أي سجل CRM آخر.

## التوقعات والتقارير والإعدادات

يعيد `GET /sales/forecast` فئات خط المبيعات وتجميعات الملاك والحصص واللقطات.
تُحفظ الحصص في `/sales/forecast/quotas` واللقطات في
`/sales/forecast/snapshots`. يوفر `GET /sales/reports` مقاييس التحويل وخط
المبيعات والإيراد والنشاط من دون خلط العملات.

تحتوي `/sales/settings` سياسات الهوية والتكرار والتعيين التلقائي وقواعد
المراحل. تستطيع رحلات العملاء تعيين المالك أو الطابور، وتحديث العميل أو
الصفقة، وتحريك المرحلة، وإنشاء مهمة أو عرض أو طلب دفع، وتشغيل خطوات واتساب
أو النماذج المعتمدة، وإشعار المدير وإرسال أحداث موقّعة، مع فحوص الخطة والحساب
نفسها المستخدمة في الواجهة.

يحتوي مرجع API التفاعلي على جميع حقول الطلب والاستجابة والحالات والمرشحات
لسطح Sales CRM API المنشور هنا.