找出並修正商家資訊錯誤

篩選地點的商家資訊，保留需要處理的資料列，讀取發布平台提供的原因，套用對應的修正方式，安全地重新輪詢，並檢查整個帳戶。

大多數商家資訊都能自動同步。無法自動同步的商家資訊會在 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 則是發布平台本身提供的原因，前提是發布平台有提供。請同時閱讀這兩個欄位：在上述範例中，Local Mint 的 displayStatus 表示合作夥伴遇到問題，但 syncIssue 指出了真正的原因，也就是缺少網站。

欄位	範例	用途
`displayStatus`	`Connect your account to sync the listing`	向使用者顯示的說明文字。
`syncIssue`	`Publisher requires website URL`	選擇修正方式。發布平台未提供原因時為 `null`。
`actionRequired`	`true`	排序：`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` 進行比較。沒有可修正的項目；發布平台不會接受這筆商家資訊。
不支援隱藏地址	設有 `hideAddress: true` 的服務區域商家出現 `CANNOT_SUBMIT` 或 `FAILED`。	檢查該網站的 `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"

即使 syncStatus 尚未變更，lastUpdate 向前推進也表示發布平台已處理新提交的資料。如果您有設定 webhook，listing.submission 事件即可取代此輪詢迴圈。

若要找出整個帳戶中所有受阻的資料列，請逐頁讀取 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 需要填寫地點的某個欄位。

後續步驟

檢查商家資訊狀態與已上線連結：查看同一份資料中狀態正常的部分。
更新地點：設定 bizUrl、描述與類別。
連結 Google 並匯入地點與連結 Facebook 粉絲專頁：排除 REQUIRING_ACTION 資料列的問題。
參考資料：取得進階商家資訊、列出方案網站、列出所有地點、錯誤代碼。