الانتقال إلى المحتوى الرئيسي
تتيح لك نقطة نهاية إنشاء العميل المحتمل إضافة عملاء محتملين جدد إلى مساحة عمل AgencyHandy برمجيًا من أي نظام خارجي — نموذج ويب، أو نظام إدارة علاقات العملاء (CRM)، أو منصة أتمتة التسويق، أو سكريبت مخصص. تظهر العملاء المحتملون الذين تم إنشاؤهم عبر هذه النقطة النهائية في قمع المبيعات الخاص بك فورًا، تمامًا كما لو تمت إضافتهم يدويًا.
قبل استخدام هذه النقطة النهائية، أكمل دليل البدء السريع للحصول على مفتاح API ومعرّف الشركة. تحتاج أيضًا إلى جلب معرّف دور العميل، وهو مطلوب عند إنشاء عميل محتمل.

​
المتطلبات الأساسية

  • ✅ مفتاح API تم إنشاؤه من تكوين مساحة العمل ← مفتاح API
  • ✅ معرّف الشركة المسترد من GET {{URL}}/accounts/companies
  • ✅ معرّف دور العميل المسترد (انظر الخطوة 1 أدناه)

​
الخطوة 1: الحصول على معرّف دور العميل

قبل إنشاء عميل محتمل، تحتاج إلى معرّف الدور لدور client في شركتك.

​
النقطة النهائية

GET {{URL}}/roles?type=company

​
الترويسات

الترويسةالقيمة
x-api-keyمفتاح API الخاص بك
companyidمعرّف الشركة الخاص بك

​
مثال على الطلب

cURL
curl --request GET "https://api.agencyhandy.com/roles?type=company" \
  --header "x-api-key: <YOUR_API_KEY>" \
  --header "companyid: <YOUR_COMPANY_ID>"

​
مثال على الاستجابة

{
  "roles": [
    {
      "_id": "6525994184e9ddd798534535",
      "role": {
        "_id": "6525994184e9ddd79853451e",
        "responsibility": "",
        "name": "client"
      },
      "company": "6525994184e9ddd79853450e",
      "createdAt": "2023-10-10T18:34:41.567Z",
      "updatedAt": "2024-10-01T07:28:48.340Z",
      "__v": 0,
      "type": "company"
    }
  ]
}
ابحث عن الإدخال حيث roles[0].role.name === "client" واستخرج _id الخارجي — أي roles[0]._id، وليس roles[0].role._id. 
const clientRoleId = roles.find(r => r.role.name === "client")._id;
// e.g. "6525994184e9ddd798534535"
استخدم roles[0]._id (معرّف ربط دور الشركة)، وليس roles[0].role._id (معرّف تعريف الدور). استخدام المعرّف الخاطئ سيتسبب في فشل طلب إنشاء العميل المحتمل.

​
الخطوة 2: إنشاء عميل محتمل جديد

​
النقطة النهائية

POST {{URL}}/members/bulk-lead

​
الترويسات

الترويسةالقيمة
x-api-keyمفتاح API الخاص بك
companyidمعرّف الشركة الخاص بك
Content-Typeapplication/json

​
نص الطلب

نص الطلب هو مصفوفة JSON — يمكنك إنشاء عميل محتمل واحد أو أكثر في استدعاء واحد.
​
firstName
string
مطلوب
الاسم الأول للعميل المحتمل.
​
lastName
string
مطلوب
الاسم الأخير للعميل المحتمل.
​
email
string
مطلوب
عنوان البريد الإلكتروني للعميل المحتمل. يجب أن يكون فريدًا داخل مساحة عملك.
​
role
string
مطلوب
معرّف دور العميل المسترد في الخطوة 1 (أي roles[0]._id).
​
isConvertedClient
boolean
مطلوب
يجب تعيينه على false عند إنشاء عميل محتمل. عيّنه على true فقط عند تحويل عميل محتمل إلى عميل كامل.
​
status
string
حالة العميل المحتمل في قمع المبيعات. القيم الشائعة: New، Contacted، Qualified. الإعداد الافتراضي New إذا تُرك فارغًا.
​
contactNo
string
رقم هاتف العميل المحتمل.
​
source
string
كيف حصلت على هذا العميل المحتمل. أمثلة على القيم: website، referral، social.
​
positionInBoard
number
موضع العميل المحتمل (الترتيب) داخل عمود لوحة قمع المبيعات. الإعداد الافتراضي 1.

​
مثال على الطلب

cURL
curl --request POST "https://api.agencyhandy.com/members/bulk-lead" \
  --header "x-api-key: <YOUR_API_KEY>" \
  --header "companyid: <YOUR_COMPANY_ID>" \
  --header "Content-Type: application/json" \
  --data '[
    {
      "firstName": "John",
      "lastName": "Doe",
      "email": "john.doe@example.com",
      "role": "6525994184e9ddd798534535",
      "isConvertedClient": false,
      "status": "New",
      "contactNo": "1234567890",
      "source": "website",
      "positionInBoard": 1
    }
  ]'

​
استجابة النجاح

{
  "message": "Lead created successfully",
  "createdMembers": [
    {
      "_id": "NEW_MEMBER_ID",
      "name": "John Doe",
      "status": "New",
      "role": "client"
    }
  ]
}
​
message
string
سلسلة تأكيد: "Lead created successfully".
​
createdMembers
array
مصفوفة كائنات العملاء المحتملين الذين تم إنشاؤهم.
​
createdMembers[].\_id
string
المعرّف الفريد للعميل المحتمل الذي تم إنشاؤه. احتفظ به إذا كنت بحاجة إلى الرجوع إلى العميل المحتمل في استدعاءات API اللاحقة.
​
createdMembers[].name
string
الاسم الكامل للعميل المحتمل (الاسم الأول + الاسم الأخير).
​
createdMembers[].status
string
حالة العميل المحتمل في قمع المبيعات كما تم تخزينها.
​
createdMembers[].role
string
اسم الدور المُعيَّن للعضو — سيكون "client".
يمكنك تمرير كائنات عملاء محتملين متعددة في المصفوفة لإنشاء عدة عملاء محتملين في استدعاء API واحد. يجب أن يتضمن كل كائن جميع الحقول المطلوبة مع عنوان بريد إلكتروني فريد خاص به.