Listings APIListings API
تسجيل الدخول

ربط صفحات Facebook

أنشئ رابطًا لربط Facebook، وطابق صفحات المالك مع مواقعك، وأكّد الروابط أو اخترها يدويًا، وافصل الحساب عند مغادرة العميل.

يتيح حساب Facebook المتصل النشر وإعداد التقارير لموقع على Facebook. بمجرد ربط صفحة، يمكن للمنشورات استهداف FACEBOOK في postSites، وتُرجع نقطة نهاية تحليلات Facebook مقاييس الصفحة بدلًا من null، وتُضاف الصفحة كمصدر للتقييمات لتصل تقييماتها مع بقية التقييمات، ويغادر صف Facebook في إدراجات الأنشطة التجارية المميزة للموقع الحالة REQUIRING_ACTION.

الخطوات هي نفسها المتبعة مع Google: أنشئ رابطًا، ودع المالك يمنح موافقته، ثم طابق وأكّد. ويُوضَّح أي اختلاف في القيم الخاصة بـ Facebook.

يجب أن تكون ساعات العمل محددة مسبقًا لصفحة Facebook على Facebook. يرفض Facebook أي تحديث من ListingsAPI إلى صفحة لا تتضمن ساعات عمل، حتى عندما يكون لدى الموقع businessHours. ويظل إدراج النشاط التجاري على Facebook عندئذٍ في الحالة IN_PROGRESS مع syncIssue بشأن عدم وجود ساعات العمل. لإصلاح ذلك، أضف ساعات العمل إلى الصفحة على Facebook، ثم أرسل تحديثًا للموقع.

يحتوي جسم الطلب على عنوانَي URL لإعادة التوجيه فقط. يقتصر نطاق الرابط على الحساب الذي يملك المفتاح، ويظل صالحًا لمدة 24 ساعة.

Connect link
curl -X POST https://listingsapi.com/api/v4/connected-accounts/connect-facebook \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "successUrl": "https://app.example.com/connect/facebook/success",    "errorUrl": "https://app.example.com/connect/facebook/error"  }}'
JSON
{  "data": {    "bulkConnectLinkForFacebook": {      "success": true,      "url": "https://connect.example.com/oauth?token=8f3c1d92-...",      "errors": null    }  }}

القيمة url أعلاه هي قيمة نائبة. وجّه المالك إلى url المُرجَع في الاستجابة الخاصة بك.

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

2. سرد الحسابات المتصلة بعد العودة من OAuth

صفِّ النتائج حسب publisher=FacebookAccount. هذه صفحة نتائج تعتمد على الإزاحة: records[] بالإضافة إلى pageInfo.totalRecords، مع التنقل بين الصفحات باستخدام page وperPage.

List accounts
curl "https://listingsapi.com/api/v4/connected-accounts?publisher=FacebookAccount&page=1&perPage=20" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "connectedAccountsInfo": {      "pageInfo": { "hasNextPage": false, "totalRecords": 1 },      "records": [        {          "connectedAccountId": "d2397854-52c2-41d7-95f1-b90cba16498d",          "connectedAccountType": "FacebookAccount",          "status": "CONNECTED",          "requestMatchesStatus": "MATCH_COMPLETED",          "connectedLocationsCount": 0        }      ]    }  }}

احتفظ بالقيمة connectedAccountId. تكون قيمة status إما CONNECTED أو MATCH_IN_PROGRESS أو CONNECTIVITY_ISSUE؛ وأي قيمة غير CONNECTED تعني أن على المالك إعادة التفويض حتى تعمل الخطوات التالية.

3. بدء المطابقة وانتظار اكتمالها

تسترجع المطابقة الصفحات التي يمكن للحساب الوصول إليها وتقرن كل صفحة بأحد مواقعك. تعمل المطابقة في الخلفية، لذا استعلم دوريًا عن تفاصيل الحساب حتى تصبح قيمة requestMatchesStatus هي MATCH_COMPLETED. تؤدي قراءة الاقتراحات قبل ذلك إلى إرجاع مصفوفة records فارغة تبدو وكأنها تعني «لا توجد مطابقات».

Trigger and poll
curl -X POST https://listingsapi.com/api/v4/connected-accounts/trigger-matches \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "connectedAccountIds": ["d2397854-52c2-41d7-95f1-b90cba16498d"] } }' # then, every 15 seconds until requestMatchesStatus is MATCH_COMPLETEDcurl https://listingsapi.com/api/v4/connected-accounts/d2397854-52c2-41d7-95f1-b90cba16498d/details \-H "Authorization: API $LISTINGSAPI_KEY"

يُرجَع سجل التفاصيل في data.connectedAccountDetails.details. تعني MATCH_COMPLETED أن أداة المطابقة قد انتهت؛ ولا يُربط أي شيء حتى تؤكّد، لذا تظل قيمة connectedLocationsCount هي 0 في الوقت الحالي.

4. مراجعة الاقتراحات وتأكيدها

يقرن كل سجل موقعك (locationInfo، locationId) بصفحة (suggestedLocationInfo). بالنسبة إلى حساب Facebook، تكون قيمة accountType هي FB بدلًا من GMB، وهذا يغيّر المعرّف الذي ترسله للتأكيد.

Suggestions
curl "https://listingsapi.com/api/v4/connected-accounts/d2397854-52c2-41d7-95f1-b90cba16498d/connection-suggestions?page=1&perPage=20" \-H "Authorization: API $LISTINGSAPI_KEY"

لا يحتوي الاقتراح على id. أنشئه بترميز <MatchRecordType>:<matchedDataDatabaseId> باستخدام base64، مع اختيار النوع من accountType. يعرض المرجع مثالًا خاصًا بـ Google فقط، ويكون ناتج فك ترميزه GmbLocationMatchedData:...؛ ويختلف النوع باختلاف منصة النشر. بالنسبة إلى Facebook، يكون النوع FbLocationMatchedData، لذا يُرمَّز FB مع 0d5e306f-0da0-46e3-929f-fd3c67ccd8cc إلى RmJMb2NhdGlvbk1hdGNoZWREYXRhOjBkNWUzMDZmLTBkYTAtNDZlMy05MjlmLWZkM2M2N2NjZDhjYw==.

accountTypeنوع سجل المطابقة
GMBGmbLocationMatchedData
FBFbLocationMatchedData
APPLEAppleLocationMatchedData
Confirm matches
# base64 of FbLocationMatchedData:0d5e306f-0da0-46e3-929f-fd3c67ccd8cccurl -X POST https://listingsapi.com/api/v4/connected-accounts/confirm-matches \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "matchRecordIds": ["RmJMb2NhdGlvbk1hdGNoZWREYXRhOjBkNWUzMDZmLTBkYTAtNDZlMy05MjlmLWZkM2M2N2NjZDhjYw=="] } }'

تكون الاستجابة data.confirmConnectMatches مع success وfailedIds، وهي معرّفات قاعدة البيانات التي فُك ترميزها وتعذّر تأكيدها. يؤدي إرسال معرّف أُنشئ بنوع خاطئ إلى إرجاع 200 مع success: false ومن دون failedIds، لذا تحقّق دائمًا من success.

5. ربط صفحة بموقع يدويًا

عندما تكون أداة المطابقة غير متأكدة، أو تكون صفحة قد أُنشئت بعد تشغيل المطابقة، اسرد الصفحات التي يمكن للحساب رؤيتها واربط إحداها مباشرةً. يُوضَع connectedAccountId في جسم JSON لطلب إدراجات الأنشطة التجارية؛ وإذا أُرسل كمعامل استعلام، فسيُتجاهَل وستحصل على إدراجات الأنشطة التجارية الخاصة بأول حساب متصل.

Pick and link
curl -X POST https://listingsapi.com/api/v4/connected-accounts/connected-account-listings \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "connectedAccountId": "d2397854-52c2-41d7-95f1-b90cba16498d", "locationInfo": "Lincoln" }' curl -X POST https://listingsapi.com/api/v4/connected-accounts/connect-listing \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "connectedAccountId": "d2397854-52c2-41d7-95f1-b90cba16498d",    "connectedAccountListingId": "<id from the listings response>"  }}'

يحتوي كل سجل لإدراج نشاط تجاري على id وlocationName وaddress وliveLink. وقيمة id فيه هي connectedAccountListingId التي يقبلها connect-listing؛ ولا يُسمّى الحقل listingId. تُرجِع عملية الربط الفاشلة success: false مع message مثل Listing record not found.

6. فصل الحساب عند مغادرة العميل

يُطبَّق فصل الحساب على كل الصفحات دفعة واحدة: تتوقف مزامنة كل صفحة مرتبطة عبر الحساب، ويتوقف وصول تفاعلات Facebook. لفصل موقع واحد مع الإبقاء على الحساب، استخدم disconnect-listing بدلاً من ذلك.

Disconnect
curl -X POST https://listingsapi.com/api/v4/connected-accounts/disconnect-facebook \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "connectedAccountId": "d2397854-52c2-41d7-95f1-b90cba16498d" } }'

تكون الاستجابة data.fbBulkDisconnect مع success. وتكون true حتى إذا كان connectedAccountId غير معروف، لذا فهي تعني "تمت المعالجة"، وليس "تمت إزالة اتصال قائم". اعرض قائمة الحسابات المتصلة مرة أخرى إذا كنت بحاجة إلى التأكد.

7. ما يحدث بعد ذلك

يُطلَق حدث connection.location_connected مع data.platform: "facebook" لكل موقع مرتبط، ويُطلَق connection.location_disconnected عند إلغاء الربط. إذا أبطل Facebook التفويض، فستتلقى connection.reauth_required: أنشئ رابطاً جديداً (الخطوة 1) واطلب من المالك الموافقة مجدداً على منح جميع الأذونات. بمجرد الربط، ينتقل صف Facebook ضمن إدراجات الأنشطة التجارية المميزة للموقع إلى SYNCED، ويصبح postSites: ["FACEBOOK"] هدفاً صالحاً، وتبدأ نقطة نهاية تحليلات Facebook بإرجاع البيانات.

الخطوات التالية