/api/v4/connected-accounts/{connectedAccountId}/connection-suggestionsعرض اقتراحات الربط
يعيد التطابقات المقترحة بين مواقع Listings API وإدراجات الأنشطة التجارية على Google Business Profile أو Facebook لحساب متصل.
المعلمات
المسار
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| connectedAccountId | string | مطلوب | UUID of the connected account to list suggestions for. |
الاستعلام
| الاسم | النوع | مطلوب | الوصف | الافتراضي |
|---|---|---|---|---|
| page | integer | اختياري | 1-based page number. | 1 |
| perPage | integer | اختياري | Records per page. | 20 |
الاستجابات
200Paginated list of connection suggestions.
{ "data": { "connectionSuggestionsForAccount": { "pageInfo": { "hasNextPage": false, "hasPreviousPage": false, "totalPages": 1, "totalRecords": 2 }, "records": [ { "accountEmail": "contact@brightsmile-dental.com", "accountType": "GMB", "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5", "locationId": "73415", "matchedDataDatabaseId": "0d5e306f-0da0-46e3-929f-fd3c67ccd8cc", "locationInfo": { "name": "My Business", "city": "Lincoln", "stateIso": "NE" }, "suggestedLocationInfo": { "locationInfo": { "name": "My Business", "city": "Lincoln" } } } ] } }}401Unauthenticated, missing or invalid API key.
429Rate limit exceeded. Retry after the `Retry-After` header value.
يعيد عمليات الاقتران المقترحة بين مواقع Listings API وإدراجات الأنشطة التجارية على Google Business Profile أو Facebook التي اكتُشفت عند تشغيل المطابقة على الحساب المتصل. يعرض كل سجل تفاصيل موقع Listings API وإدراج النشاط التجاري المطابق على منصة النشر، ليتمكن المشغّل من المقارنة بينهما قبل التأكيد.
تُنشأ الاقتراحات بشكل غير متزامن بواسطة POST /connected-accounts/trigger-matches. إذا كنت قد ربطت حسابًا للتو، فاستدعِ trigger-matches أولًا، وإلا فستكون records فارغة وستكون قيمة pageInfo.totalRecords هي 0. (عند استدعاء نقطة النهاية هذه فعليًا لحساب رُبط حديثًا ولم تتوفر له أي تطابقات بعد، فإنها تعيد {"data":{"connectionSuggestionsForAccount":{"pageInfo":{"hasNextPage":false,"hasPreviousPage":false,"totalPages":0,"totalRecords":0},"records":[]}}}.) يوضّح المثال أعلاه بنية سجل يحتوي على بيانات.
حالة الاستخدام: سير عمل المراجعة قبل التأكيد. بعد استيراد حساب Google الخاص بعميل، استعلم دوريًا من نقطة النهاية هذه لعرض كل تطابق مقترح في واجهة المراجعة الخاصة بك. يوافق المشغّل على عمليات الاقتران الصحيحة، ثم تمرّر معرّفات السجلات المعتمدة إلى POST /connected-accounts/confirm-matches.
تحديد معرّف السجل. لا يحتوي سجل الاقتراح على حقل id. معرّفه هو matchedDataDatabaseId، وهو المفتاح الأساسي لسجل المطابقة الذي يستند إليه؛ وتخبرك accountType بنوع سجل المطابقة (GMB أو FB أو APPLE). تتطلب عملية تأكيد مطابقات الربط كلتا القيمتين لإنشاء قيمة id التي تقبلها، لذا احتفظ بهما معًا عند تجهيز الاقتراحات للمراجعة.
تقسيم النتائج إلى صفحات وحدود معدل الطلبات. تنقّل بين الصفحات باستخدام معاملَي الاستعلام غير المتداخلين page وperPage (مثل ?page=2&perPage=50)، وراقب pageInfo.hasNextPage. لا يوجد أي معامل باسم pageInfo أو filters أو sortBy أو accountId: يُحدَّد الحساب المتصل من المسار، ويكون الترتيب ثابتًا وتصاعديًا بحسب معلومات الموقع، ويُتجاهل أي شيء آخر ترسله بدلًا من رفضه. تخضع نقطة النهاية هذه لحدود معدل الطلبات مثل نقاط النهاية الأخرى الخاصة بعرض القوائم؛ عند تلقي 429، باعد بين المحاولات وأعِد المحاولة بعد المدة المحددة في قيمة ترويسة Retry-After، بدلًا من تقليص الفاصل الزمني بين الاستعلامات الدورية.
curl -X GET 'https://listingsapi.com/api/v4/connected-accounts/<connectedAccountId>/connection-suggestions' \ -H "Authorization: API $LISTINGSAPI_KEY"