‏‎Business Management APIs‎‏

الإنابة عن النشاط التجاري

تسمح API الإنابة عن النشاط التجاري للشريك بما يلي:

  • الحصول على صلاحية الوصول للتصرف نيابةً عن العميل
  • إنشاء مستخدم نظام ضمن "مدير الأعمال" الخاص بالعميل والحصول على رمز الوصول الخاص به

يتم تعريف مستخدم النظام على أنه شخص قد يقوم بمهام برمجية متكررة، مثل تحديث كتالوج المنتجات أو إرسال أحداث من خادم إلى خادم أو تحديث الجماهير المخصصة وما إلى ذلك.

في هذا السيناريو، تتوفر لدى مستخدم النظام إمكانية الوصول كموظف ولا يمكنه الوصول إلا إلى الأصول المخصصة (في وقت الإنشاء) باستخدام رمز وصول المستخدم المسؤول.

ميزة استخدام مستخدم النظام مقابل رمز وصول المستخدم - يمكن للمستخدمين التوقف عن استخدام النشاط التجاري، ولكن تظل رموز وصول مستخدم النظام بدون انتهاء صلاحيتها. في هذا النهج، يستمر العميل في باعتباره مالك النشاط التجاري ويسمح للشريك بالوصول إلى مدير الأعمال والأصول عبر مستخدم النظام. تتوفر لدى العميل القدرة على الانتقال إلى مدير الأعمال الخاص به وإلغاء وصول مستخدم النظام أو إزالة إمكانية الوصول إلى أصول معينة من الشريك برمجيًا.

البدء

قبل البدء، نوصي بمراجعة هذه المتطلبات والمعلومات:

مدير الأعمال الخاص بالعميل

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

إذا لم يكن هناك مدير أعمال للعميل، فيجب إنشاء مدير أعمال قبل المتابعة. للحصول على التعليمات، راجع API مدير الأعمال.

أذونات التطبيق

  • business_management

المعرفات

  • PARTNER_BM_ID: معرف مدير أعمال الشريك الذي يجب أن يمتلك التطبيق.
  • CLIENT_BM_ID: معرف مدير الأعمال الخاص بالعميل الذي يمتلك صفحة فيسبوك المرتبطة بالحساب التجاري الخاص بالعميل.

رموز الوصول

  • USERS_ACCESS_TOKEN: رمز وصول مسؤول مدير الأعمال الخاص بالعميل، والذي تم إنشاؤه من خلال أذونات business_manage باستخدام التطبيق المملوك لمدير الأعمال الخاص بالشريك. يتم إنشاء هذا الرمز من خلال تسجيل دخول فيسبوك.
  • PARTNER_BM_ADMIN_SYSTEM_USER_ACCESS_TOKEN: رمز وصول مستخدم النظام المسؤول في مدير أعمال الشريك للتطبيق.
  • CLIENT_BM_SU_ACCESS_TOKEN: رمز وصول مستخدم النظام ضمن مدير الأعمال الخاص بالعميل.
  • CLIENT_BM_SU_PAGE_ACCESS_TOKEN: رمز وصول الصفحة الخاص بمستخدم النظام ضمن مدير الأعمال الخاص بالعميل.

الخطوات الموصى بها

الخطوة الأولى

قم بإنشاء علاقة الإنابة بين الشريك ومدير أعمال العميل.

يؤدي هذا إلى إنشاء عنصر ربط للعلاقة بين مدير أعمال الشريك ومدير أعمال العميل. هذا يمكّن الشريك من إنشاء مستخدم نظام (SU) عبر API في الخطوة التالية.

رمز الوصول المستخدم:USERS_ACCESS_TOKEN


curl -i -X POST \
 "https://graph.facebook.com/v21.0/<PARTNER_BM_ID>/managed_businesses?existing_client_business_id=<CLIENT_BM_ID>&access_token=<USERS_ACCESS_TOKEN>"

الخطوة الثانية

احصل على رمز وصول مستخدم النظام ضمن مدير أعمال العميل. يؤدي هذا إلى تثبيت التطبيق في مدير الأعمال الخاص بالعميل وإنشاء مستخدم نظام. بشكل افتراضي، يكون اسم مستخدم النظام "{Client_Business_Manager_Name} SYSTEM USER". سيتمكن العميل من عرض تطبيق الشركاء في مدير الأعمال الخاص به كأصل مشترك. (لن تتوفر لديه أي صلاحية وصول إلى التطبيق إلا كمستخدم اختباري على الأكثر.)

في المعلمة scope، يجب تضمين أي أذونات تحتاج إلى أن يمتلكها مستخدم النظام للوصول إلى نقاط نهاية API ذات الصلة. يمكنك الرجوع إلى مراجع API الأفراد للتعرف على الأذونات المطلوبة للوصول إلى نقاط النهاية تلك.

رمز الوصول المستخدم:PARTNER_BM_ADMIN_SYSTEM_USER_ACCESS_TOKEN. يحتاج رمز الوصول هذا إلى إذن business_management وجميع الأذونات المضمنة في معلمات scope أعلاه.


curl -i -X POST \
 "https://graph.facebook.com/v21.0/<CLIENT_BM_ID>/access_token?scope=ads_management,pages_read_engagement&app_id=<APP_ID>&access_token=<PARTNER_BM_ADMIN_SYSTEM_USER_ACCESS_TOKEN>"

تحتوي الاستجابة على رمز مستخدم النظام المرتبط بعلاقات الإنابة (OBO). لا تحتاج إلى إنشاء أي مستخدم نظام آخر أو استخدامه لدمج المعاملات التجارية.

الخطوة الثالثة

احصل على معرف مستخدم النظام.

رمز الوصول المستخدم:CLIENT_BM_SU_ACCESS_TOKEN

curl -i -X GET \
 "https://graph.facebook.com/v21.0/me?access_token=<CLIENT_BM_SU_ACCESS_TOKEN>"

الخطوة الرابعة

قم بتعيين الأصول (الصفحة والكتالوج) إلى مستخدم النظام في مدير الأعمال الخاص بالعميل.

رمز الوصول المستخدم:USERS_ACCESS_TOKEN

curl -i -X POST \
 "https://graph.facebook.com/v21.0/<ASSET_ID>/assigned_users?user=<SYSTEM_USER_ID>&tasks=MANAGE&access_token=<USERS_ACCESS_TOKEN>"

الخطوة الخامسة

قم بتخزين CLIENT_BM_SU_ACCESS_TOKEN هذا في قاعدة بيانات آمنة واستخدمه للوصول إلى واجهات API التي تتطلب رمز وصول المستخدم، مثل إدارة الكتالوج.

الخطوة السادسة

أنشئ رمز وصول الصفحة باستخدام CLIENT_BM_SU_ACCESS_TOKEN عن طريق استدعاء:

curl -i -X GET \
 "https://graph.facebook.com/v21.0/me/accounts?access_token=<CLIENT_BM_SU_ACCESS_TOKEN>"

سيدرج هذا الطلب جميع الصفحات التي يديرها مستخدم النظام بما في ذلك access_token المطابق. مثال على الاستجابة:

{
  "data": [
    {
      "access_token": "<access token sanitized>",
      "category": "Retail Company",
      "category_list": [
        {
          "id": "2239",
          "name": "Retail Company"
        }
      ],
      "name": "Test_Shop_Page",
      "id": "<content sanitized>",
      "tasks": [
        "ANALYZE",
        "ADVERTISE",
        "MODERATE",
        "CREATE_CONTENT",
        "MANAGE"
      ]
    }
  ],
  "paging": {
    "cursors": {
      "before": "<content sanitized>",
      "after": "<content sanitized>"
    }
  }
}

انسخ access_token المطابق للصفحة المرتبطة بالحساب التجاري للعميل، وقم بتخزينه بشكل آمن. ستستخدمه للوصول إلى واجهات API التي تتطلب رمز وصول الصفحة نيابةً عن "الحساب التجاري"، مثل إدارة الطلبات وإعداد التقارير المالية.

الأسئلة المتكررة

كيف يمكنني حذف علاقة "الإنابة" لإزالة مستخدم النظام ضمن مدير أعمال العميل الذي تم تعيينه لي؟


curl -i -X DELETE \
 "https://graph.facebook.com/v21.0/<PARTNER_BM_ID>/managed_businesses?existing_client_business_id=<CLIENT_BM_ID>&access_token=<USERS_ACCESS_TOKEN>"

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