التعامل مع الشركات

نشرح في هذا المقال طريقة التعامل مع الشركات التي تدير مركز المساعدة وتشرف على الوكلاء المسؤولين عن تقدين الدعم. سنوضح طريقة عرض الشركات، ووسومها، وحالتها، وإنشاء شركة جديدة، وتعديلها وحذفها من خلال الواجهة البرمجية لزيتون. لتطبيق الأمثلة، سنفترض وجود مركز مساعدة على النطاق example.com، ومفتاح الواجهة البرمجية لزيتون مخزن ضمن متغير باسم TOKEN$ لاستخدامه في الطلبات المختلفة.

export TOKEN="YOUR_API_KEY"

عرض الشركات

لعرض بيانات شركة محددة نرسل طلب GET لنقطة الوصول Show a company مع تمرير الرقم التعريفي للشركة ضمن عنوان الطلب.

ولعرض بيانات كافة الشركات المحفوظة في مركز المساعدة نرسل طلب GET لنقطة الوصول List all companies ويمكننا من خلال هذه النقطة تصفية الخيارات التي نحتاجها لتحديد الشركات المطلوبة.

شركة واحدة

لعرض بيانات شركة محددة لها الرقم التعريفي 1002 نرسل الطلب التالي:

curl "https://example.com/api/agent/v1/companies/1002" \
  -H "Authorization: Bearer @TOKEN"

كافة الشركات

لعرض كافة الشركات المضافة لمركز المساعدة نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/companies?limit=25" \
  -H "Authorization: Bearer @TOKEN"

شركات مُسندة لوكيل

لعرض الشركات المسندة للوكيل رقم 1008 في مركز المساعدة نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/companies?assign_to[]=1008" \
  -H "Authorization: Bearer @TOKEN" \
  --globoff

شركات بفئة محددة

لعرض الشركات التي تنتمي إلى الفئة رقم 700 في مركز المساعدة نكتب:

curl "https://example.com/api/agent/v1/companies?segment_ids[]=700" \
  -H "Authorization: Bearer @TOKEN" \
  --globoff

شركات بوسوم محددة

لعرض كافة الفئات التي تملك الوسم "it"والوسم "vip" نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/companies?tags[]=it&tags[]=vip" \
  -H "Authorization: Bearer @TOKEN" \
  --globoff

عرض ملاحظات شركة

يمكن عرض قائمة بكافة الملاحظات المكتوبة عن شركة معينة بارسال طلب GET لنقطة الوصول List all company notes مع تمرير رقم الشركة المطلوبة ضمن عنوان الطلب.

ولعرض ملاحظة محدد نرسل طلب GET لنقطة الوصول Retrieve a company note مع تمرير رقم الملاحظة ورقم الشركة ضمن عنوان الطلب.

كافة الملاحظات

لعرض كافة ملاحظات الشركة رقم 1002 نرسل الطلب التالي:

curl "https://example.com/api/agent/v1/companies/1002/notes" \
  -H "Authorization: Bearer @TOKEN"

ملاحظة واحدة

لعرض الملاحظة رقم 1014 المكتوبة عن الشركة رقم 1002 نرسل الطلب التالي:

curl "https://example.com/api/agent/v1/companies/1002/notes/1014" \
  -H "Authorization: Bearer @TOKEN"

إضافة شركة

لإضافة شركة جديدة لمركز المساعدة، نرسل طلب POST لنقطة الوصول Create a company ونمرر بيانات الشركة في جسم الطلب.

شركة واحدة

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

curl "https://example.com/api/agent/v1/companies" \
  -X POST \
  -H "Authorization: Bearer @TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
       "name": "company_name",
       "logo": "company_logo_in_base64",
       "status": "active",
       "numbers": [
           {
               "country_code": 999,
               "number": 12345
           },
           {
               "country_code": 999,
               "number": 12345
           }
       ],
       "tags": ["new"],
       "emails": ["email@example.com"],
       "assign_to": 1008,
       "segment_ids": [700]
   }'

إضافة وسم لشركة

يمكننا إضافة وسم معين لشركة بإرسال طلب POST لنقطة الوصول Add a company tag مع تمرير الرقم التعريفي للشركة في عنوان الطلب، واسم الوسم المطلوب في جسم الطلب.

وسم واحد

لإضافة الوسم "عاجل" للشركة رقم 1002نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/companies/1002/tags" \
  -X POST \
  -H "Authorization: Bearer @TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
       "name": "عاجل"
   }'

إضافة ملاحظة عن شركة

يمكن إضافة ملاحظة حول شركة معينة بإرسال طلب من نوع POST إلى نقطة الوصول Create a form submission note مع تمرير الرقم التعريفي للشركة المطلوبة في عنوان الطلب، وبيانات الملاحظة في جسم الطلب.

ملاحظة واحدة

لإضافة ملاحظة جديدة للشركة رقم 1002 نكتب الطلب على النحو التالي:

curl "https://example.com/api/agent/v1/companies/1002/notes" \
  -X POST \
  -H "Authorization: Bearer @TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
       "details": "ملاحظة جديدة",
       "attachments": [1013]
   }'

تعديل إعدادات الشركات

يمكن تعديل إعدادات شركة محددة بإرسال طلب PUT لنقطة الوصول Update a company مع تمرير رقم الشركة ضمن عنوان الطلب، والبيانات المطلوب تعديلها في جسم الطلب.

كما يمكن تعديل عدة شركات معًا بإرسال طلب PUT لنقطة الوصول Mass update companies.

شركة واحدة

لإضافة وسم جديد باسم "it"، وعنوان بريد إلكتروني جديد، ورابط LinkedIn للشركة رقم 1002 في مركز المساعدة نرسل الطلب التالي:

curl "https://example.com/api/agent/v1/companies/1002" \
  -X PUT \
  -H "Authorization: Bearer @TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
       "name": "company_name",
       "status": "active",
       "tags": ["new", "it"],
       "fields": [
           {
               "key": "linkedin",
               "value": "https://www.linkedin.com/exampel/",
               "type": "url"
           }
       ],
       "emails": ["email1@example.com", "email2@example.com"]
   }'

عدة شركات

لتعديل الشركات رقم 12 و 102 و 1002 في مركز المساعدة، وإضافة الوسم "مهم" لها، وحذف الوسم "جديدة"منها، وإسنادها إلى الوكيل رقم 1008، وتعديل حالتها لتصبح فعالة نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/companies" \
  -X PUT \
  -H "Authorization: Bearer @TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
       "company_ids": [12, 102, 1002],
       "added_tags": ["مهم"],
       "deleted_tags": ["جديدة"],
       "assign_to": 1008,
       "status": "active"
   }'

تعديل حالة شركة

يمكنك تعديل حالة الشركة من خلال إرسال طلب من نوع PUT إلى نقطة الوصول
Update company status مع تمرير الرقم التعريفي للشركة ضمن عنوان الطلب، واسم الحالة المطلوبة في جسم الطلب.

حالة واحدة

لتعديل حالة الشركة رقم 1002 وجعلها محذوفة، نرسل الطلب التالي:

curl "https://example.com/api/agent/v1/companies/1002/status" \
  -X PUT \
  -H "Authorization: Bearer @TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "deleted"
  }'

تعديل ملاحظة شركة

يمكنك تعديل المحتوى النصي أو المرفقات الخاصة بأي ملاحظة مضافة لشركة ما بإرسال طلب PUT إلى نقطة الوصول Update a company note مع تمرير رقم الشركة ورقم الملاحظة في عنوان الطلب، والبيانات المطلوب تعديلها في جسم الطلب.

ملاحظة واحدة

لتعديل المحتوى النصي للملاحظة رقم 1014 المكتوبة عن الشركة رقم 1002 مع إضافة ملف جديد إلى مرفقاتها له الرقم 1013 نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/companies/1002/notes/1014" \
  -X PUT \
  -H "Authorization: Bearer @TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "details": "ملاحظة معدلة",
    "attachments": [1013]
  }'

حذف شركة

لحذف شركة من الشركات المحفوظة في مركز المساعدة، نرسل طلب DELETE لنقطة الوصول Delete a company مع تمرير رقمها التعريفي في عنوان الطلب. وتجدر الإشارة لأن الحذف بهذه الطريقة يختلف عن تعديل حالة الشركة إلى deleted فعند تغيير الحالة يمكن استعادة الشركة أو إعادة تعديل حالتها إلى active بسهولة.

شركة واحدة

لحذف الشركة رقم 1002من مركز المساعدة نرسل الطلب التالي:

curl "https://example.com/api/agent/v1/companies/1002" \
  -X DELETE \
  -H "Authorization: Bearer @TOKEN"

حذف وسم لشركة

يمكننا حذف وسم معين من شركة بإرسال طلب DELETE لنقطة الوصول Delete a company tag مع تمرير رقم الشركة ورقم الوسم ضمن عنوان الطلب. ولمعرفة الأرقام التعريفية لوسوم شركة نرسل طلب GET لنقطة الوصول List all tags.

وسم واحد

لحذف الوسم "عاجل" رقم 700 من الشركة رقم 1002 نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/companies/1002/tags/700" \
  -X DELETE \
  -H "Authorization: Bearer @TOKEN"

حذف ملاحظة عن شركة

لحذف ملاحظة خاصة بشركة معينة، نرسل طلب من نوع DELETE إلى نقطة الوصول Delete a company note مع تمرير رقم الشركة ورقم الملاحظة ضمن عنوان الطلب.

ملاحظة واحدة

لحذف الملاحظة رقم 1014 من ملاحظات الشركة رقم 1002 نكتب الطلب التالي:

curl "https://example.com/api/agent/v1/companies/1002/notes/1014" \
  -X DELETE \
  -H "Authorization: Bearer @TOKEN"