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

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

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

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

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

​
الترويسات

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

​
نص الطلب

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

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

cURL
curl --request POST "https://api.agencyhandy.com/members/bulk-client" \
  --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",
      "isConvertedClient": false,
      "status": "New",
      "contactNo": "1234567890",
      "source": "website",
      "positionInBoard": 1
    }
  ]'

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

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