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

ربط Google Business Profile واستيراد مواقعك

أنشئ رابط ربط Google، وطابق إدراجات أنشطة المالك التجارية على Google مع مواقعك، وأكّد المطابقات، واستورد إدراجات الأنشطة التجارية التي لا موقع لها بعد.

يتيح ربط حساب Google النشر وإعداد التقارير لموقع على Google. إلى أن يُربط حساب، يظل صف Google Maps ضمن إدراجات النشاط التجاري المميزة للموقع في الحالة REQUIRING_ACTION، ولا تُجلب تقييمات Google، ولا يمكن نشر المنشورات على GOOGLE، وتُرجع تحليلات Google القيمة null. يحل ربط الحساب المشكلات الأربع.

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

يقتصر نطاق الرابط على الحساب الذي يملك مفتاح API، لذا لا يتضمن جسم الطلب سوى عنوانَي URL لإعادة التوجيه. وجّه المالك إلى url المُعاد في الاستجابة؛ ويعيده Google إلى successUrl أو errorUrl عند الانتهاء.

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

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

الرابط صالح لمدة 24 ساعة. تحقّق من أن قيمة url ليست null بدلًا من الاعتماد على success وحده. إذا انتهت صلاحية بيانات اعتماد المالك لاحقًا، فأنشئ رابطًا جديدًا بالطريقة نفسها: يُجدَّد الاتصال الحالي ولا يُنشأ اتصال مكرر.

2. اعرض قائمة الحسابات المرتبطة بعد العودة من OAuth

عندما يصل المالك إلى successUrl لديك، اعرض قائمة حسابات Google. تستخدم هذه الصفحة تقسيمًا إلى صفحات قائمًا على الإزاحة: records[] مع pageInfo.totalRecords، ويجري التنقل بين الصفحات باستخدام page وperPage.

List accounts
curl "https://listingsapi.com/api/v4/connected-accounts?publisher=GoogleAccount&page=1&perPage=20" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "connectedAccountsInfo": {      "pageInfo": { "hasNextPage": false, "totalRecords": 1 },      "records": [        {          "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",          "email": "owner@brightsmile-dental.com",          "status": "CONNECTED",          "requestMatchesStatus": "MATCH_COMPLETED",          "connectedLocationsCount": 0        }      ]    }  }}

اختر السجل الذي يشير فيه email إلى المالك الذي منح الموافقة للتو، واحتفظ بقيمة connectedAccountId فيه. يستخدم كل استدعاء لاحق معرّف UUID هذا.

statusالمعنى
CONNECTEDبيانات الاعتماد صالحة. يمكن بدء المطابقة بأمان.
MATCH_IN_PROGRESSعملية مطابقة في قائمة الانتظار أو قيد التنفيذ.
CONNECTIVITY_ISSUEانتهت صلاحية التفويض. يوضح connectivityIssue السبب؛ أصدِر رابط الربط مجددًا.

يستخدم مرشّح الاستعلام الاختياري status كلمات مختلفة (Connected، NotConnected، ConnectionIssue)؛ ويؤدي تمرير قيمة status الخاصة بالسجل نفسه إلى إرجاع 400.

3. ابدأ المطابقة

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

Trigger matches
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": ["4f712c17-4f95-42dd-90f4-97171a2e67b5"] } }'

تكون الاستجابة data.connectedAccountsTriggerMatches وتتضمن success وfailedIds. تعني success: true أن المهمة أُضيفت إلى قائمة الانتظار؛ ويُدرج أي حساب تعذّرت إضافته إلى قائمة الانتظار في failedIds.

4. استعلم دوريًا حتى الوصول إلى MATCH_COMPLETED

استعلم عن تفاصيل الحساب كل 15 ثانية باستخدام حلقة لها حد أقصى. وتُبقي هذه الفترة الفاصلة خطة Launch أيضًا ضمن حدها البالغ 10 طلبات في الدقيقة.

Poll details
curl https://listingsapi.com/api/v4/connected-accounts/4f712c17-4f95-42dd-90f4-97171a2e67b5/details \-H "Authorization: API $LISTINGSAPI_KEY"

يُعاد السجل في data.connectedAccountDetails.details ويحتوي على الحقول نفسها التي يحتوي عليها سجل القائمة. تكون قيمة requestMatchesStatus هي MATCH_IN_PROGRESS أثناء تنفيذ المهمة، وتصبح MATCH_COMPLETED عندما تكون الاقتراحات جاهزة. تعني Completed أن أداة المطابقة انتهت، ولا تعني أن أي شيء قد رُبط: تظل قيمة connectedLocationsCount هي 0 حتى تؤكد.

5. راجع الاقتراحات وأكّدها

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

Suggestions
curl "https://listingsapi.com/api/v4/connected-accounts/4f712c17-4f95-42dd-90f4-97171a2e67b5/connection-suggestions?page=1&perPage=20" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "connectionSuggestionsForAccount": {      "pageInfo": { "hasNextPage": false, "totalRecords": 2 },      "records": [        {          "accountType": "GMB",          "matchedDataDatabaseId": "0d5e306f-0da0-46e3-929f-fd3c67ccd8cc",          "locationId": "73415",          "locationInfo": { "name": "My Business", "city": "Lincoln", "stateIso": "NE" },          "suggestedLocationInfo": { "locationInfo": { "name": "My Business", "city": "Lincoln" } }        }      ]    }  }}

لا يحتوي الاقتراح على id. لتأكيده، أنشئ معرّف سجل مطابقة: ناتج ترميز <MatchRecordType>:<matchedDataDatabaseId> باستخدام base64، مع اختيار النوع من accountType. بالنسبة إلى Google (GMB)، يكون النوع GmbLocationMatchedData، لذا يُرمَّز السجل أعلاه إلى R21iTG9jYXRpb25NYXRjaGVkRGF0YTowZDVlMzA2Zi0wZGEwLTQ2ZTMtOTI5Zi1mZDNjNjdjY2Q4Y2M=. يستخدم Facebook (FB) النوع FbLocationMatchedData، وتستخدم Apple (APPLE) النوع AppleLocationMatchedData.

Confirm matches
# base64 of GmbLocationMatchedData: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": ["R21iTG9jYXRpb25NYXRjaGVkRGF0YTowZDVlMzA2Zi0wZGEwLTQ2ZTMtOTI5Zi1mZDNjNjdjY2Q4Y2M="] } }'

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

6. استيراد إدراجات الأنشطة التجارية التي ليس لها موقع بعد

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

Account listings
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": "4f712c17-4f95-42dd-90f4-97171a2e67b5", "perPage": 50 }'
JSON
{  "data": {    "connectedAccountListings": {      "pageInfo": { "hasNextPage": false, "totalRecords": 60 },      "records": [        {          "id": "R21iQnVsa0RhdGFMYWtlOjA2MDQ4NmExLTA0NzQtNDc4NS1iMjNhLTBkOGM4MzhmNGQ5OA==",          "locationName": "Trial",          "address": "123 William St, NY 10038, Manhattan, US",          "liveLink": null        }      ]    }  }}

مرّر locationInfo مع عبارة بحث لتصفية نتائج حساب كبير حسب الاسم أو العنوان أو الهاتف أو الرمز البريدي أو رمز المتجر. قيمة id في كل سجل هي connectedAccountListingId التي يقبلها الاستدعاءان التاليان. لا يوفّر أيّ من حزمتَي SDK دالة لاستدعاء create-location-from-listing بعد، لذا تستدعي أمثلة Python وNode واجهة REST مباشرةً باستخدام الترويسة نفسها.

Create from listing
curl -X POST https://listingsapi.com/api/v4/connected-accounts/create-location-from-listing \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",    "connectedAccountListingId": "R21iQnVsa0RhdGFMYWtlOjA2MDQ4NmExLTA0NzQtNDc4NS1iMjNhLTBkOGM4MzhmNGQ5OA=="  }}'
JSON
{  "data": {    "createLocationFromConnectedAccountListing": { "success": true, "locationId": 88277, "errors": null }  }}

يُنشأ الموقع من بيانات Google (الاسم والعنوان وساعات العمل والفئات والهاتف والسمات)، ويُربط بإدراج النشاط التجاري فورًا. يبقى إدراج النشاط التجاري على Google في حالة IN_PROGRESS حتى يُنشر أول تحديث للموقع عليه. قيمة locationId هي databaseId فقط. عند الفشل، تكون قيمة success هي false، ويحمل errors رمزًا مثل SY81067 (لم يُعثر على إدراج النشاط التجاري باستخدام معرّفه). اسم الحقل هو connectedAccountListingId؛ ويرفض المخطط listingId.

إذا كان إدراج النشاط التجاري يخص موقعًا موجودًا لديك، فاربطه بدلًا من إنشاء موقع مكرر.

Link a listing
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": "4f712c17-4f95-42dd-90f4-97171a2e67b5",    "connectedAccountListingId": "R21iQnVsa0RhdGFMYWtlOjA2MDQ4NmExLTA0NzQtNDc4NS1iMjNhLTBkOGM4MzhmNGQ5OA=="  }}'

عند فشل الربط، تُرجَع success: false مع message، مثل Listing record not found، أو ملاحظة تفيد بأن إدراج النشاط التجاري مرتبط بالفعل بموقع آخر.

7. ربط موقع واحد بدلًا من ذلك

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

Single-location link
curl -X POST https://listingsapi.com/api/v4/locations/oauth_connect_url \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "site": "GOOGLE",    "successUrl": "https://app.example.com/locations/1800289/connected",    "errorUrl": "https://app.example.com/locations/1800289/connect-failed"  }}'

تكون الاستجابة data.createConnectUrl مع success وurl وerrors. الرابط صالح للاستخدام مرة واحدة، لذا أنشئ رابطًا جديدًا لكل محاولة. إذا كان عنوان URL لإعادة التوجيه نسبيًا أو تعذّر تحليله، تُرجَع success: true مع null url، لذا تحقّق من url. إذا لم يكن المفتاح مخوّلًا للوصول إلى هذا الموقع، تُرجَع 403 مع SY90003.

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

بمجرد ربط إدراج نشاط تجاري، ينتقل صف Google Maps ضمن إدراجات الأنشطة التجارية المميزة للموقع من REQUIRING_ACTION، ويمرّ عبر IN_PROGRESS، ثم يستقر عند SYNCED مع listingUrl. تُضاف Google تلقائيًا كمصدر للتقييمات، فتبدأ التقييمات بالوصول إلى قائمة التفاعلات، وتُطبّق التحديثات التي تجريها على الموقع على الملف التجاري.

عند تعيين عنوان URL لـ webhook في لوحة التحكم، لا تحتاج إلى الاستعلام الدوري. تتضمن كل حمولة location_id وdata.connected_account_id.

الحدثمتى يُطلَقالإجراء المطلوب
connection.location_connectedعند ربط إدراج نشاط تجاري بموقع؛ تكون قيمة data.platform هي google.حدّد حالة الموقع على أنه متصل في واجهة المستخدم لديك.
connection.reauth_requiredأُبطلت بيانات اعتماد الحساب. لا تتم مزامنة أي شيء حتى يُمنح التفويض مجددًا.أنشئ رابطًا جديدًا (الخطوة 1) واطلب من المالك تسجيل الدخول مجددًا.
connection.listing_inaccessibleبيانات الاعتماد سليمة، لكن أُزيل إذن الوصول إلى إدراج النشاط التجاري المحدد فقط.اطلب من المالك استعادة إذن الوصول على Google، أو اربط إدراج نشاط تجاري آخر.

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