إضافة شركة جديدة إلى جهات الاتصال

نشرح في هذا المقال طريقة إضافة شركة ما إلى مركز المساعدة ونورد أمثلة عملية توضيحية على إضافة شركة جديدة لمركز مساعدة تجريبي يدعى "المناسب" له النطاق الفرعي al-munasib.zaetoon.com.

إضافة شركة جديدة لجهات الاتصال

لإضافة شركة جديدة إلى جهات اتصال مركز المساعدة، أرسل طلب من نوع POST إلى نقطة الاتصال companies/ وفق التالي:

• عنوان URL لنقطة الاتصال:
  https://{your_subdomain}/api/agent/v1/companies.
• نوع الطلب: POST.
• جسم الطلب Body: يُكتب بصيغة JSON ويتضمن المعاملات التالية:
• • name: معامل إجباري، نوعه سلسلة نصية string، يُحَدِّد اسم الشركة الجديدة المراد إضافتها.
  • logo: نوعه سلسلة نصية string، تُمَرِر ضمنه صورة شعار الشركة الجديدة مُرَمَّزة بصيغة base64.
  • status: نوعه سلسلة نصية string، يُحَدِّد حالة الشركة ويقبل حصرًا إحدى القيم التالية:
  • • active فعَّالة.
    • inactive غير فعَّالة.
    • banned محظورة.
    • deleted محذوفة.
  • tags: نوعه مصفوفة من السلاسل النصية array، تُكتب ضمنه الوسوم التي ترغب بإضافتها إلى الشركة الجديدة، ولا يُشترط أن تكون الوسوم موجودة مسبقًا في مركز المساعدة إذ مجرد كتابتها هنا يعني إضافتها إلى وسوم المركز.
  • fields نوعه مصفوفة array، وهو خاص بإضافة حقول جديدة إلى إعدادات الشركات مثل روابط مواقع الويب URLs العائدة للشركة، وهي نوعية الحقول المتاحة حاليًّا.
    تتألف المصفوفة fields من عدة عناصر objects، يمثل كل عنصر رابط معين ويتضمن(key اسم الرابط، value الرابط، type نوع الحقل، وهو دائمًا "url" كما في المثال التالي:

"fields": [
   {
      "key": "الموقع الرئيسي للشركة",
       "value": "https://exampel.com",
       "type": "url"
   },
  {
      "key": "الموقع الثاني للشركة",
      "value": "https://exampel2.com",
      "type": "url"
   }
]

• • numbers: نوعه مصفوفة من العناصر array، يمثل كل عنصر object منها رقم جوال للشركة يتكون من جزأين: رمز الدولة country_code والرقم number كما في المثال التالي:

"numbers" :[
    {
       "country_code": 999,
       "number" : 123456789
   },
   {
       "country_code": 999,
       "number" : 111111111
    }
     ]

• • emails: نوعه مصفوفة من السلاسل النصية array، يتضمن عناوين البريد الإلكتروني للشركة الجديدة.
  • custom_fields: نوعه عنصر object مركب من عدة عناصر، يمثل كل عنصر منها أحد الحقول المخصصة الخاصة بتعريف الشركات (في حال استخدامك لها) ويكتب وفق الصيغة العامة التالية:

"custom_fields": {
           "field_{field id}": "your custom field value"
     }

علمًا أنك تستطيع معرفة الرقم التعريفي للحقل المخصص الفرعي {field id} ضمن مجموعة الحقول المخصصة المستخدمة لتعريف الشركات في مركزك عبر إرسال طلب GET إلى نقطة الاتصال {custom-fields/{id/ (حيث "id" فيها هو الرقم التعريفي لمجموعة الحقول المخصصة).

تختلف قيمة الحقل المخصص حسب نوعه:

• • إذا كان الحقل المخصص من نوع نص text فتكتب قيمة الحقل بصيغة سلسلة نصية string، كما في المثال التالي الخاص بحقل "عنوان الشركة" أو غيره :

"custom_fields": {
           "field_33525": "عنوان الشركة"
     }

• • إذا كان الحقل المخصص من نوع ملفات files، فلديك احتمالان: إما تمرير الملفات بصيغة base64 أو binary كما يلي:

"custom_fields": {
           "field_33525":{
                "files": ["files as base64"]
             }
     }

أو تمرير الأرقام التعريفية للملفات المُحَمَّلة مسبقًا (بواسطة نقطة الاتصال files/ أو files/images/) وفق المثال التالي:

"custom_fields": {
           "field_33525":{
                 "ids": [1, 2, 3]
             }
     }

• • إذا كان الحقل المخصص من نوع checkbox يتضمن عدة اختيارات، فيُكتب بصيفة مصفوفة تتضمن الأرقام التعريفية للاختيارات المطلوبة وفق التالي:

"custom_fields": {
           "field_35413": [1, 2, 3]
     }

• • assign_to: نوعه عدد صحيح integer، تُمَرِر ضمنه الرقم التعريفي id للمستخدم أو موظف مركز المساعدة الذي تود إسناد الشركة الجديدة إليه.
  • segment_ids: نوعه مصفوفة array، تُكتب ضمنه الأرقام التعريفية للفئات segments التي تنتمي إليها الشركة الجديدة.

مثال

يوضح المثال التالي طريقة إضافة شركة جديدة اسمها "company_name" إلى الشركات المحفوظة في مركز مساعدة "المناسب":

curl -X POST --header 'Authorization: Bearer your_token' 'Content-Type: application/json' --data '{
"name": "company_name",
"logo": "company_logo_in_base64",
"status": "active",
"numbers" :[
    {
       "country_code": 999,
       "number" : 12345000
   },
   {
       "country_code": 999,
       "number" : 12340000
    }
     ],
"tags": ["new"],
"emails":["info@exampel.com"],
"assign_to": 1434,
"segment_ids": [2380]
}' 'https://al-munasib.zaetoon.com/api/agent/v1/companies'