قبل البدء
أنشئ مفتاح 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، واعرضه أو نزّله أو احذفه من دون حذف العرض: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 المنشور هنا.
