/api/v4/connected-accounts/connected-account-listingsجلب إدراجات الأنشطة التجارية لحساب متصل
يُرجع إدراجات الأنشطة التجارية على Google Business Profile أو Facebook التي يمكن لحساب متصل الوصول إليها، مع إمكانية التصفية وتقسيم النتائج إلى صفحات.
المعلمات
النص الأساسي
| الاسم | النوع | مطلوب | الوصف |
|---|---|---|---|
| connectedAccountId | string | مطلوب | UUID of the connected account whose listings to fetch. Send this in the JSON body: as a query parameter it is ignored. |
| page | integer | اختياري | Page number to fetch. Defaults to 1. |
| perPage | integer | اختياري | Records per page. Defaults to 500, which is also the maximum. |
| locationInfo | string | اختياري | Free-text search within the account's listings. Matches business name, address lines, locality, postal code, store code, and phone. |
مثال على الطلب
نص جاهز للصق. استبدل المعرّفات والقيم النموذجية بقيمك.
{ "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5", "perPage": 50}الاستجابات
200List of listings accessible to the account, with pagination metadata.
{ "data": { "connectedAccountListings": { "pageInfo": { "hasNextPage": false, "hasPreviousPage": false, "totalPages": 1, "totalRecords": 60 }, "records": [ { "accountTypeName": "Google", "address": "123 William St, NY 10038, Manhattan, US", "id": "R21iQnVsa0RhdGFMYWtlOjA2MDQ4NmExLTA0NzQtNDc4NS1iMjNhLTBkOGM4MzhmNGQ5OA==", "liveLink": null, "locationName": "Trial", "phone": "(718) 667-7787" } ] } }}401Unauthenticated, missing or invalid API key.
429Rate limit exceeded. Retry after the `Retry-After` header value.
يُرجع إدراجات الأنشطة التجارية على Google Business Profile أو Facebook التي يملك حساب متصل صلاحية الوصول إليها. يتضمن كل سجل id الخاص بإدراج النشاط التجاري (معرّفًا بتنسيق base64)، وlocationName، وaddress، وphone، وliveLink. على الرغم من أن هذا الطلب يستخدم POST، فهو عملية قراءة، لكن يجب إرسال خيارات الحساب وتقسيم النتائج إلى صفحات في جسم JSON.
حالة استخدام: إنشاء أداة لاختيار إدراج نشاط تجاري. بعد أن يربط العميل حساب Google يملك عشرات إدراجات الأنشطة التجارية، استدعِ نقطة النهاية هذه لعرض قائمة قابلة للبحث. ضع عبارة البحث التي يكتبها العميل في locationInfo (فهي تبحث عن تطابق داخل الاسم والعنوان ورقم الهاتف والرمز البريدي ورمز المتجر) ليتمكن من العثور على المتجر الصحيح بسرعة.
حالة استخدام: تزويد connect-listing بالبيانات. إن id في كل سجل هو بالضبط connectedAccountListingId الذي يتوقعه connect-listing. اجلب إدراجات الأنشطة التجارية، ودع العميل (أو منطق المطابقة لديك) يختار أحدها، ثم مرّر id الخاص به مع locationId المستهدف في Listings API إلى connect-listing لربطهما.
قسّم النتائج إلى صفحات باستخدام المفتاحين page وperPage مباشرةً في الجسم؛ القيمة الافتراضية لـ perPage هي 500، وهي أيضًا الحد الأقصى. اقرأ pageInfo.hasNextPage وpageInfo.totalPages من الاستجابة للتنقل عبر صفحات مجموعة النتائج كاملةً. تُحتسب طلبات نقطة النهاية هذه ضمن حد معدل الطلبات للحساب، وتتضمن استجابة 429 ترويسة Retry-After.
تحققنا من بنية الطلب أعلاه على واجهة API الفعلية. نموذج الاستجابة توضيحي.
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 }'