‏‎Business Management APIs‎‏

بدء الاستخدام

المستندات المرجعية

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

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

المتطلبات

إنشاء مدير أعمال جديد

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

على سبيل المثال، أنشئ مدير أعمال جديدًا من خلال طلب POST:

curl \
  -F "name=Pomni Media" \
  -F "vertical=ADVERTISING" \
  -F "primary_page=<PAGE_ID>" \
  -F "timezone_id=1" \
  -F "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/<USER_ID>/businesses"

المتطلبات

لإنشاء نشاط تجاري، تحتاج إلى:

  • رمز وصول
  • معرف صفحة
  • مجال
  • معرف المستخدم على مستوى التطبيق

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

المجال هو أحد ثوابت السلسلة هذه:

ADVERTISING , AUTOMOTIVE , CONSUMER_PACKAGED_GOODS , ECOMMERCE , EDUCATION , ENERGY_AND_UTILITIES , ENTERTAINMENT_AND_MEDIA , FINANCIAL_SERVICES , GAMING , GOVERNMENT_AND_POLITICS ,MARKETING , ORGANIZATIONS_AND_ASSOCIATIONS , PROFESSIONAL_SERVICES , RETAIL , TECHNOLOGY , TELECOM , TRAVEL , OTHER

لعرض أصول نشاط تجاري، استخدم المعرف الخاص به:

curl "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>?access_token=<ACCESS_TOKEN>"

يمكنك أيضًا الاطلاع على قائمة بحسابات مدير الأعمال التي يمكنك الوصول إليها:

curl "https://graph.facebook.com/<API_VERSION>/me/businesses?access_token=<ACCESS_TOKEN>"

تتضمن حقول الاستجابة:

الاسم الوصف

name

النوع: string (سلسلة)

اسم النشاط التجاري

timezone_id

النوع: int (عدد صحيح)

معرف المنطقة الزمنية للنشاط التجاري

primary_page

النوع: JSON object (كائن بلغة JSON)

كائن الصفحة الأساسية المرتبطة بمدير الأعمال هذا.

{ "category": "App page", "name": "Sample Primary Page", "id": "123456789" }

id

النوع: long (قيمة طويلة)

معرف مدير الأعمال

update_time

النوع: string (سلسلة)

تاريخ آخر تحديث لمدير الأعمال

updated_by

النوع: JSON object (كائن بلغة JSON)

آخر مستخدم، بالاسم والمعرف، قام بتحديث مدير الأعمال

creation_time

النوع: string (سلسلة)

وقت إنشاء النشاط التجاري

created_by

النوع: JSON object (كائن بلغة JSON)

اسم المستخدم والمعرف الذي أنشأ مدير الأعمال

تحديث حسابات مدير الأعمال

قم تحديث الحقول في مدير الأعمال بإرسال طلب POST إلى https://graph.facebook.com/{API_VERSION}/{BUSINESS_ID}. على سبيل المثال، قم بتغيير اسم النشاط التجاري:

curl \
-F "name=My Actual Business Name" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/"

قم بتغيير مجال النشاط التجاري عن طريق إرسال طلب POST التالي:

curl \
-F "vertical=RETAIL" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/"

تتوفر لديك الخيارات التالية:

الاسم الوصف

name

مطلوب

اسم النشاط التجاري

primary_page

معرف الصفحة الأساسية المرتبطة بمدير الأعمال هذا.

يمكنك تحديث الصفحة الأساسية عن طريق إرسال طلب POST التالي. يجب أن تكون الصفحة الأساسية مملوكة لمدير الأعمال.

curl \
  -F "primary_page=<PAGE_ID>" \
  -F "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/"

يمكنك أيضًا تحديث كل ما سبق في طلب POST واحد:

curl \
  -F "name=My Actual Business Name" \
  -F "vertical=RETAIL" \
  -F "primary_page=<PAGE_ID>" \
  -F "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/"

إدارة الأشخاص والأدوار

هناك نوعان من الأدوار في مدير الأعمال:

الاسم ثابت API الوصف

المسؤول

ADMIN

  • يمكنه التحكم في كل ما يتعلق بالنشاط التجاري بما في ذلك تعديل الحساب أو حذفه وإضافة أشخاص إلى قائمة الموظفين أو إزالتهم.
  • يمتلك صلاحية الوصول READ وWRITE إلى جميع الأصول التي يرتبط بها مدير الأعمال.

الموظف

EMPLOYEE

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

لمزيد من المعلومات حول الأدوار، راجع إعداد أدوار الكتالوج في مدير الأعمال.

في الأساس، يكون منشئ النشاط التجاري هو المستخدم الوحيد في النشاط التجاري ولديه صلاحية المسؤول.

دعوة الأشخاص

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

لدعوة شخص ما كمسؤول، أرسل طلب POST:

curl \
-F "email=some@email.com" \
-F "role=ADMIN" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/business_users"

لدعوة شخص ما كموظف، أرسل طلب POST:

curl \
-F "email=some@email.com" \
-F "role=EMPLOYEE" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/business_users"

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

الأشخاص في مدير الأعمال

اعتبارًا من الإصدار 2.11 ستكون لدينا نقاط نهاية منفصلة للحصول على المستخدمين بناءً على حالتهم. أرسل طلب GET لاسترداد كل مجموعة من المستخدمين. للحصول على جميع مستخدمي النشاط التجاري (يرجى ملاحظة أن الوصول المتقدم مطلوب.):

curl "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/business_users?access_token=<ACCESS_TOKEN>"

للحصول على مستخدمي النظام، الذين لديهم صلاحية الوصول على مستوى النظام:

curl "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/system_users?access_token=<ACCESS_TOKEN>"

للحصول على المستخدمين المعلقين الذين تمت دعوتهم للوصول إلى نشاط تجاري، ولكنهم لم يقبلوا بعد:

curl "https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/pending_users?access_token=<ACCESS_TOKEN>"

ترجع نقاط النهاية المستخدمين النشطين أو المعلقين أو مستخدمي النظام في نشاطك التجاري. على سبيل المثال:

{
  "data": [
    {
      "id": "<BUSINESS_ID>",
      "name": "Alpha MK",
      "email": "some@email.com",
      "role": "EMPLOYEE",
    }
  ]
}

تبدو نتائج المستخدمين المعلقين كما يلي:

{
  "data": [
    {
      "id": "<BUSINESS_ID>",
      "email": "some@email.com",
      "role": "EMPLOYEE",
      "status": "PENDING",
      "owner": {
        "id": "USER_ID",
        "name": "Generic Emporium"
      }
    }
  ]
}

تبدو تعريفات الحقول التي تم إرجاعها كالتالي:

الاسم الوصف

id

النوع: long (قيمة طويلة)

معرف هذا المستخدم المخصص لهذا النشاط التجاري.

name

النوع: string (سلسلة)

اسم هذا المستخدم ضمن هذا النشاط التجاري

business

النوع: JSON object (كائن بلغة JSON)

مدير الأعمال الذي ينتمي إليه هذا المستخدم

first_name

النوع: string (سلسلة)

الاسم الأول لهذا المستخدم ضمن هذا النشاط التجاري

last_name

النوع: string (سلسلة)

اسم العائلة للمستخدم ضمن هذا النشاط التجاري

title

النوع: string (سلسلة)

لقب المستخدم ضمن هذا النشاط التجاري

role

النوع: string (سلسلة)

الدور الذي يمتلكه الشخص في هذا النشاط التجاري. EMPLOYEE أو ADMIN

email

النوع: string (سلسلة)

عنوان البريد الإلكتروني للمستخدم

تغيير الأدوار

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

curl \
  -F "role=ADMIN" \
  -F "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/<BUSINESS_SCOPED_USER_ID>"

لتغيير شخص ما من دور المسؤول إلى دور الموظف، أرسل طلب POST:

curl \
  -F "role=EMPLOYEE" \
  -F "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/<BUSINESS_SCOPED_USER_ID>"

يمكنك تغيير دور المستخدم المعلق من خلال إرسال طلب POST هذا:

curl \
  -F "role=EMPLOYEE" \
    -F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<PENDING_USER_ID>"

إزالة المستخدمين

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

لإزالة مستخدم نشط من نشاطك التجاري، قم بتنفيذ استدعاء DELETE:

curl \
  -X DELETE \
  -F "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/<BUSINESS_SCOPED_USER_ID>"

لإلغاء مستخدم معلق من خلال طلب DELETE:

curl \
  -X DELETE \
  -F "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/<API_VERSION>/<PENDING_USER_ID>"

يؤدي هذا إلى إزالة المستخدمين من نشاطك التجاري وإزالة صلاحية الوصول إلى أصول النشاط التجاري.

الحصول على كائنات الاتصال

المستندات المرجعية

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

  • الصفحات والأماكن
  • الأحداث
  • التطبيقات
  • النطاقات

راجع عينة من الاستفسارات وتعرف على المزيد على كائنات الاتصال.

الفواتير

المستندات المرجعية

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

يمتلك مدير الأعمال حد ائتمان عادي

بالنسبة لشركاء API التسويق الذين قاموا بتمكين الفواتير، يمكنك الاستفادة من حد الائتمان العادي المملوك لمدير الأعمال.

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

بالنسبة للحسابات الإعلانية التي تم إنشاؤها عبر API التالية، سنقوم بتوزيع الائتمان بشكل ديناميكي عبر الحسابات وتحديث حدود الائتمان والإنفاق لتجنب الوصول إلى حدود الائتمان. ستتمكن أيضًا من رؤية ملخص الرصيد المتاح ومبلغ الرصيد في كل حساب إعلاني.

ندعم المسؤولية العادية فقط حاليًا، ولا ندعم المسؤولية التسلسلية. ستظل عملية الإعداد من دون تغيير.

فواتير نهاية الشهر

بمجرد إعداد حد الائتمان لنشاط تجاري ما واستخدامه لعرض الإعلانات، نقوم بإنشاء فواتير نهاية الشهر لحساب الأعمال. لعرض فواتير النشاط التجاري، تحتاج إلى دور مالي. بالنسبة للمسؤولين العاديين والموظفين في النشاط التجاري، يمكنك تعيين الأذونات ضمن People في مدير الأعمال. يمكنك أيضًا تعيين أذونات مالية لمستخدمي النظام باستخدام مدير الأعمال.

لاسترداد الفواتير ضمن حساب أعمال باستخدام API، أرسل طلب GET:

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/business_invoices?start_date=2017-01-01&end_date=2017-04-01"

تبدو عينة النتائج كما يلي:

{
  "business_invoices": {
    "data": [
      {
        "id": "1659175694099710",
        "billing_period": "2017-03-01"
      },
      {
        "id": "1303851778395619",
        "billing_period": "2017-01-01"
      },
      {
        "id": "1415846861611329",
        "billing_period": "2017-02-01"
      }
    ],
    "paging": {
      "cursors": {
        "before": "MAZDZD",
        "after": "MgZDZD"
      }
    }
  },
  "id": "249554531892085"
}

يمكنك الحصول على تفاصيل الفاتورة على مستوى الحملة الإعلانية من خلال هذا الطلب:

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/business_invoices?fields=billed_amount_details,billing_period,entity,id,invoice_id,payment_term,type,campaigns&start_date=2019-06-01&end_date=2019-07-01"

ستكون الاستجابة مشابهة لما يلي:

{
  "business_invoices": {
    "data": [
      {
        "billed_amount_details": {
          "currency": "USD",
          "net_amount": "387.70",
          "tax_amount": "0.00",
          "total_amount": "387.70"
        },
        "billing_period": "2017-03-01",
        "entity": "FBUS",
        "id": "1659175694099710",
        "invoice_id": "22736800",
        "liability_type": "Normal",
        "invoice_type": "Invoice",
        "payment_term": "CUSTOMER",
        "type": "Invoice",
        "campaigns": {
          "data": [
            {
              "campaign_id": "6056967798500",
              "campaign_name": "Nhận ưu đãi",
              "tags": [
                "hello2"
              ],
              "billed_amount_details": {
                "currency": "USD",
                "net_amount": "207.62",
                "tax_amount": "0.00",
                "total_amount": "207.62"
              }
            },
            {
              "campaign_id": "6056958052500",
              "campaign_name": "Nhận ưu đãi",
              "billed_amount_details": {
                "currency": "USD",
                "net_amount": "180.08",
                "tax_amount": "0.00",
                "total_amount": "180.08"
              }
              "impressions": 100,
              "clicks": 50,
              "conversions": 30
            }
          ]
        }
      },
      {
        "billed_amount_details": {
          "currency": "USD",
          "net_amount": "382.99",
          "tax_amount": "0.00",
          "total_amount": "382.99"
        },
        ......
    "paging": {
      "cursors": {
        "before": "MAZDZD",
        "after": "MgZDZD"
      }
    }
  },
  "id": "1515766328651000"
}

يمكنك أيضًا استرداد حقول الفوترة الإضافية:

  • invoice_date - التاريخ الذي أنشأ فيه فيسبوك الفاتورة
  • due_date - تاريخ استحقاق الفاتورة
  • payment_status - يظهر ما إذا كانت الفاتورة بالحالة Paid أو Unpaid أو Partially Paid
  • amount_due - المبلغ المستحق حاليًا والمعلق على الفاتورة
  • download_uri - تنزيل ملف PDF للفاتورة على محدد URI هذا

API مصدر التمويل

لاسترداد مصدر تمويل الرصيد الائتماني موسّع المرتبط بمدير الأعمال، أرسل طلب GET هذا.

curl "https://www.graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/extendedcredits"

لإعداد مصدر تمويل لنشاط تجاري، انتقل إلى قسم الإعدادات في نشاطك التجاري ضمن مدير الأعمال.

التخصيص الديناميكي للرصيد

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

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