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

قبل البدء

أنشئ مفتاح API مقيّداً من الحساب ← واجهة المطور بصلاحية leads:read لعرض العملاء وقراءة تفاصيلهم وسجلهم. أضف leads:write للإنشاء أو تغيير الحالة. يحتاج التحويل أيضاً إلى deals:write. يبقى إنشاء المفتاح وتدويره وإلغاؤه داخل تطبيق HueChat الموثق. يجب تفعيل ميزتي الصفقات وعملاء المبيعات المحتملين في خطة الحساب. يعيد الخادم 402 مع code: "plan_disabled" عندما تكون إحداهما معطلة، حتى إذا كانت صلاحيات المفتاح صحيحة. يتم هذا الفحص قبل قراءة بيانات العملاء أو تغييرها. تتطلب المنتجات ودفاتر الأسعار وعروض الأسعار ميزتي الصفقات ومنتجات وعروض المبيعات. استخدم deals:read لمسارات العرض وdeals:write لمسارات الإنشاء والأرشفة وإضافة بنود الأسعار. ينطبق عقد الخطأ 402 نفسه قبل قراءة أي بيانات تابعة للحساب.
استخدم معرّف الحساب الذي أصدر المفتاح. لا يتم حل عميل أو جهة اتصال أو شركة أو فرع أو محادثة أو صفقة من حساب آخر.

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

لا يحمل مفتاح API هوية عضو فريق، لذلك أرسل owner_id للعضو الذي سيملك العميل. يمكن لتطبيق HueChat عند استخدام جلسة عضو مصادق عليه حذف هذا الحقل. تُحفظ بيانات العميل وأول سجل للحالة وأول سجل للملكية في معاملة واحدة، لذلك لا يُحفظ عميل بلا مالك.
القيمة 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.

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

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

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

تستطيع POST /leads/{leadId}/convert ربط العميل بصفقة موجودة، أو إنشاء الشركة والصفقة اللتين راجعهما المستخدم في معاينة التحويل ضمن معاملة واحدة. أرسل ترويسة Idempotency-Key فريدة؛ يعيد تكرار المفتاح النتيجة الأصلية، بينما يعيد استخدامه لعميل آخر 409.
لإنشاء فرصة جديدة أرسل 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 بند، ويحسب الخادم الإجمالي الفرعي والخصومات والضريبة والإجمالي من مبالغ عشرية دقيقة بمنزلتين. لا تُقبل مراجع الصفقة أو جهة الاتصال أو الشركة أو المنتج إلا إذا كانت من الحساب نفسه. يجب أن يستخدم بند المنتج عملة المنتج. يجب أن يرتبط عرض السعر الأساسي بصفقة، وعند تعيينه أساسياً يلغي الخادم حالة الأساسي عن العرض السابق للصفقة نفسها داخل المعاملة.
انتقالات دورة العرض صريحة. يسجل PATCH /sales/quotes/{quoteId}/lifecycle الإرسال أو العرض أو القبول أو الرفض أو الانتهاء، وينشئ /revisions مسودة بإصدار جديد. يتطلب القبول مفتاح تكرار آمن. يحافظ مسار دورة الحياة على حالتي الدفع والموافقة ولا يستطيع استبدالهما. يقرر مسؤول الحساب الموافقة المعلقة للخصم المرتفع عبر PATCH /sales/quotes/{quoteId}/approval بقيمة approved أو rejected وسبب تدقيق إلزامي. يسجل طلب الدفع المبلغ وحالة المزود، لكنه لا يعني أن المزود قبله أو سوّاه.

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

يمكن لكل إصدار من عرض السعر الاحتفاظ بملف PDF واحد موقّع أو مصمم. ارفعه أو استبدله بصيغة multipart، واعرضه أو نزّله أو احذفه من دون حذف العرض:
يُقبل ملف 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 المنشور هنا.