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

العثور على أخطاء إدراجات الأنشطة التجارية وإصلاحها

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

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

1. اجلب إدراجات الأنشطة التجارية واحتفظ بالصفوف التي بها مشكلات

اجلب إدراجات الأنشطة التجارية المميزة واستبعد كل ما هو سليم. يحتاج الصف إلى اهتمام عندما تكون قيمة actionRequired هي true، أو عندما تكون قيمة syncStatus هي FAILED أو CANNOT_SUBMIT أو REQUIRING_ACTION. لا تشير IN_PROGRESS وPENDING_APPROVAL إلى أخطاء؛ بل إلى وجود الصف في قائمة انتظار منصة النشر.

Problem rows
curl -s https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '[.data.listingsForLocation[]       | select(.actionRequired                or (.syncStatus | IN("FAILED", "CANNOT_SUBMIT", "REQUIRING_ACTION")))]'
JSON
{  "data": {    "listingsForLocation": [      {        "site": { "name": "Google Maps", "url": "maps.google.com" },        "syncStatus": "REQUIRING_ACTION",        "displayStatus": "Connect your account to sync the listing",        "actionRequired": true,        "syncIssue": null      },      {        "site": { "name": "Local Mint", "url": "localmint.com" },        "syncStatus": "FAILED",        "displayStatus": "Partner experiencing issues; awaiting response",        "actionRequired": false,        "syncIssue": "Publisher requires website URL"      }    ]  }}

2. اقرأ السبب

يوضح حقلان مشكلة الصف. يقدم displayStatus ملخص المنصة للحالة الحالية للصف. ويقدم syncIssue السبب الذي ذكرته منصة النشر نفسها، إذا كانت قد قدمت سببًا. اقرأ كليهما: في المثال أعلاه، يذكر displayStatus الخاص بـ Local Mint أن الشريك يواجه مشكلات، لكن syncIssue يوضح السبب الفعلي، وهو عدم وجود موقع إلكتروني.

الحقلمثالالغرض من استخدامه
displayStatusConnect your account to sync the listingالنص الذي تعرضه للشخص.
syncIssuePublisher requires website URLاختيار الإصلاح. تكون القيمة null عندما لا تقدم منصة النشر سببًا.
actionRequiredtrueالفرز: تعني true أن شيئًا لن يتقدم حتى تتخذ إجراءً.

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

3. حدّد الإصلاح المناسب للسبب

تتسبب مجموعة صغيرة من الأسباب في تعطل جميع الصفوف تقريبًا.

السببكيف يظهرالإصلاح
الحساب غير متصلGoogle Maps أو Facebook بالحالة REQUIRING_ACTION مع Connect your account to sync the listing.اربط حساب منصة النشر تلك: ربط Google واستيراد المواقع أو ربط صفحات Facebook. لا يحتاج Apple Maps إلى ربط؛ راجع ربط Apple Business Connect.
الموقع الإلكتروني غير موجودFAILED مع syncIssue: Publisher requires website URL.عيّن قيمة bizUrl للموقع. راجع تحديث موقع.
البلد غير مدعوم لدى منصة النشرCANNOT_SUBMIT، دون syncIssue.قارن countryIso الخاص بالموقع مع supportedCountries الخاص بموقع النشر ذاك من سرد مواقع النشر ضمن الخطة. لا يوجد ما يمكن إصلاحه؛ فلن تقبله منصة النشر.
إخفاء العنوان غير مدعومCANNOT_SUBMIT أو FAILED لنشاط تجاري يخدم منطقة محددة مع hideAddress: true.تحقق من hideAddressSupportedCountries الخاص بموقع النشر. إما أن تُظهر العنوان أو تقبل تخطي منصة النشر هذه.
صفحة Facebook لا تتضمن ساعات عملFacebook بالحالة IN_PROGRESS مع syncIssue: Temporary status is not applicable for this listing because it has no hours or opening information.أضف ساعات العمل إلى الصفحة على Facebook، ثم أرسل تحديثًا للموقع. راجع تحديث موقع.
رُفض الوصف أو الفئةFAILED مع syncIssue يذكر اسم الحقل.حدّث الوصف أو subCategoryId في الموقع، ثم أعد الاستعلام.

للتحقق من قواعد البلد وإخفاء العنوان، اجلب مواقع النشر ضمن الخطة مرة واحدة وخزّنها مؤقتًا؛ فالقائمة غير مقسمة إلى صفحات ونادرًا ما تتغير.

Plan sites
curl -s https://listingsapi.com/api/v4/plan-sites \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.planSites[] | select(.name == "Yelp")      | {name, supportedCountries, hideAddressSupportedCountries}'
JSON
{  "name": "Yelp",  "supportedCountries": ["US", "CA", "GB", "DE", "FR"],  "hideAddressSupportedCountries": ["US", "CA", "AU", "GB"]}

إذا لم يكن countryIso الخاص بالموقع ضمن supportedCountries، فلن يغادر صف منصة النشر تلك الحالة CANNOT_SUBMIT أبدًا. استبعده من حساب التغطية بدلًا من إعادة المحاولة.

4. أعد الاستعلام بعد الإصلاح

يؤدي تحديث الموقع إلى إرسال جديد إلى منصات النشر المتأثرة. يعود الصف من FAILED أو REQUIRING_ACTION إلى IN_PROGRESS، ثم ينتقل إلى SYNCED عندما تقبله منصة النشر. تستغرق منصات النشر من دقائق إلى أسابيع، لذا استعلم وفق جدول زمني تُقاس فواصله بالساعات، لا بالثواني.

تُحتسب كل عملية استعلام ضمن حد معدل الطلبات. عند تلقي 429، اقرأ Retry-After وانتظر ذلك العدد من الثواني؛ وتُطلق حزم SDK الاستثناء RateLimitError بالقيمة نفسها.

Re-poll
# -D - prints response headers so you can see Retry-After on a 429curl -s -D - https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY" \| grep -i -E "^HTTP|^Retry-After"

يشير تقدّم lastUpdate إلى أن منصة النشر قد عالجت الإرسال الجديد، حتى قبل أن يتغير syncStatus. إذا كانت لديك webhooks، فإن الحدث listing.submission يحل محل هذه الحلقة.

5. أجرِ فحصًا شاملًا على مستوى الحساب

للعثور على كل صف متوقف على مستوى الحساب، تنقّل عبر صفحات GET /locations (اتصال قائم على المؤشرات: first، after، edges[].node) واستدعِ نقطة نهاية الإدراجات المميزة مرة واحدة لكل موقع. اجمع الصفوف التي بها مشكلات في تقرير واحد مرتّب حسب الموقع. تتتبّع حزمة Python SDK المؤشرات باستخدام auto_paging_iter()؛ وتفعل حزمة Node SDK ذلك باستخدام fetchAll: true. تعيد الأمثلة استخدام الدالة المساعدة للتراجع التدريجي بين المحاولات من الخطوة 4.

Account sweep
# One page of locations, then one listings call per location.# Repeat with &after=<pageInfo.endCursor> while hasNextPage is true.curl -s "https://listingsapi.com/api/v4/locations?first=50" \-H "Authorization: API $LISTINGSAPI_KEY" \| jq -r '.data.allLocations.edges[].node.id' \| while read -r id; do    curl -s "https://listingsapi.com/api/v4/locations/$id/listings/premium" \      -H "Authorization: API $LISTINGSAPI_KEY" \      | jq --arg id "$id" '[.data.listingsForLocation[]           | select(.syncStatus != "SYNCED" and .syncStatus != "COMPLETED")           | {location: $id, site: .site.name, status: .syncStatus, issue: .syncIssue}]'    sleep 6   # stay under 10 requests a minute on Launch  done

يجمع التقرير الصفوف التي لا تزال قيد المعالجة مع الصفوف المتوقفة فعليًا. قسّمه وفقًا للجدول في الخطوة 3 قبل تسليمه إلى أي شخص: يتطلب IN_PROGRESS وPENDING_APPROVAL الانتظار، ويتطلب REQUIRING_ACTION اتصالًا، ويتطلب FAILED حقلًا في الموقع.

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