查找并修复商家信息错误

筛选出某个地点的商家信息中需要关注的记录，读取发布平台给出的原因，采取相应的修复措施，安全地重新轮询，并检查整个账户。

大多数商家信息无需干预即可同步。无法同步的商家信息会通过 displayStatus 和 syncIssue 说明原因，而且几乎每种原因都对应 5 种修复方法中的一种。本指南从原始商家信息记录入手，逐步生成按账户汇总的报告，说明哪些记录受阻以及应如何处理。

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. 读取原因

有 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），并为每个地点调用 1 次高级商家信息端点。将有问题的行汇总为一份以地点为键的报告。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 行的问题。
参考：获取高级商家信息、列出套餐站点、列出所有地点、错误代码。