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

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

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

export TOKEN="YOUR_API_KEY"

عرض الشركات

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

شركة واحدة

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

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

كافة الشركات

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

الشركات المضافة بين تاريخين

لعرض الشركات المضافة إلى مركز المساعدة بين تاريخين مثلًا من 2025/01/01 لغاية 2025/04/01 نكتب الطلب على النحو التالي:

curl --globoff \
     --header 'Authorization: Bearer @TOKEN' \
     'https://example.com/api/agent/v1/companies?after[created_at]=2025-01-01&before[created_at]=2025-04-01&limit=25'

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

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

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

بيانات تفصيلية للشركات

لنعرض معلومات تفصيلية لكافة الشركات مثل أرقام الهواتف، وعناوين البريد الإلكتروني، والحقول المخصصة، والوكلاء إليهم نكتب الطلب كالتالي:

curl --globoff \
     --header 'Authorization: Bearer @TOKEN' \
     'https://example.com/api/agent/v1/companies?expand[]=numbers&expand[]=emails&expand[]=urls&expand[]=custom_fields&expand[]=assigned_agent'

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

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

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

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

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

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

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

يمكن عرض قائمة بكافة الملاحظات المكتوبة عن شركة معينة بارسال طلب من نوع GET لنقطة الوصول List all company notes مع تمرير رقم الشركة المطلوبة ضمن عنوان الطلب، أما إذا رغبنا بعرض ملاحظة بعينها فقط، فيمكن إرسال طلب GET إلى نقطة الوصول Retrieve a company note مع تمرير رقم الملاحظة ورقم الشركة ضمن عنوان الطلب.

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

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

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

ملاحظة واحدة

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

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

إضافة شركة

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

شركة واحدة

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

curl -X POST \
     --header 'Authorization: Bearer @TOKEN' \
     --header '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": ["email@example.com"],
         "assign_to": 1008,
         "segment_ids": [2380]
     }' \
     'https://example.com/api/agent/v1/companies'

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

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

وسم واحد

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

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

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

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

ملاحظة واحدة

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

curl -X POST \
     --header 'Authorization: Bearer @TOKEN' \
     --header 'Content-Type: application/json' \
     --data '{
         "details": "write your note",
         "attachments": [1013]
     }' \
     'https://example.com/api/agent/v1/companies/1002/notes'

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

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

شركة واحدة

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

curl -X PUT \
     --header 'Authorization: Bearer @TOKEN' \
     --header 'Content-Type: application/json' \
     --data '{
         "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"]
     }' \
     'https://example.com/api/agent/v1/companies/1002'

عدة شركات

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

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

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

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

• active
• inactive
• deleted
• banned

حالة واحدة

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

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

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

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

ملاحظة واحدة

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

curl -X PUT \
     --header 'Authorization: Bearer @TOKEN' \
     --header 'Content-Type: application/json' \
     --data '{
         "details": "write your new note",
         "attachments": [1013]
     }' \
     'https://example.com/api/agent/v1/companies/1002/notes/1014'

حذف شركة

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

شركة واحدة

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

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

حذف وسم لشركة

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

وسم واحد

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

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

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

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

ملاحظة واحدة

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

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