创建 listings scan

启动对一家商家的扫描。扫描会检查该商家是否已在目录网络中收录，以及商家信息的准确性：检查范围包括 Google、Bing、Apple Maps、Yelp、Facebook 和 MapQuest 等地图和搜索引擎、数据聚合平台和本地目录，以及 ChatGPT 和 Gemini 等 AI 助手。根据所在国家或地区，一次扫描最多检查约 60 个目录。该商家不必是您账户中的地点，因此您可以在接入前审查潜在客户或现有客户。

调用会立即返回，扫描状态为 QUEUED。目录检查在后台运行，可通过 GET /listings/scans/{scanId} 读取结果。

使用场景：审查潜在客户的商家信息。您的销售工具收集商家名称、地址和电话号码。创建扫描，保存返回的 scan.id，并在收到 listing_scan.completed 事件时，通过 data.scan 读取已完成的扫描。summary 提供概览（有多少个目录找到了该商家，其中有多少个目录的商家信息准确），results[] 则提供各目录的详细信息，供报告展示。

使用场景：检查您已管理的商家的信息状况。使用您自己的某个地点的商家详细信息进行扫描。扫描会识别出该商家，并根据该地点的实际商家信息生成结果，无需再次搜索（请参阅复用与免费扫描）。

扫描如何结束

扫描会依次进入 QUEUED、IN_PROGRESS 状态，最终以 COMPLETED 或 FAILED 状态结束。大多数扫描会在 1 至 7 分钟内完成。如果某个目录在约 15 分钟后仍未响应，其结果将设为 UNAVAILABLE，扫描将使用其他结果完成。

• 优先使用 webhook。listing_scan.completed 和 listing_scan.failed 事件每次扫描各投递 1 次，携带的扫描对象与 GET /listings/scans/{scanId} 返回的相同，其中包含结果。这些事件会发送到已启用 webhook 且 webhook URL 已验证的账户，并与其他事件一样进行签名。请参阅 listing_scan.completed。
• 无法接收 webhook 时使用轮询。如果您无法接收 webhook，请每 15 秒读取一次扫描，直到 status 为 COMPLETED 或 FAILED。提高轮询频率没有任何收益，还会消耗您的请求配额。

必填字段

name、street、city、countryIso 和 phone 始终为必填项。以下 2 个字段是否必填取决于国家或地区：

如果值缺失或格式错误，请求将被拒绝并返回 SY83003，错误信息会指出对应字段。phone 必须包含 6 至 15 位数字，countryIso 必须为 2 个字母。

复用与免费扫描

扫描并不总是执行新的搜索。返回的扫描对象中的 source 字段说明了结果的来源：

如果您在 7 天内再次扫描同一商家，系统会返回您账户中现有的扫描，而不会创建新扫描，响应中会包含 reused: true。系统不会启动新扫描，也不会发送新的 webhook，因此请读取返回的扫描（它可能仍在运行），无需等待另一个事件。在复用期限内再次扫描您自己的某个地点时，行为也相同。

每月额度

付费套餐包含 Listings scans，每月额度取决于您的套餐。免费沙盒单日通行证不提供此功能。只有新执行的 DIRECTORY_SEARCH 扫描才会占用额度。以下情况免费：

• 7 天内对同一商家重复扫描（reused: true），
• RECENT_SCAN 副本，
• LOCATION_LISTINGS 扫描，
• 扫描失败，不计入额度。

额度随您账户的账单周期重置。每个创建响应都包含 quota，其中含有 limit、used、remaining 和 resetsAt，即使请求被拒绝也不例外。请参阅套餐和附加项。

错误

创建请求被拒绝时，会返回 HTTP 200，其中包含 scan: null，拒绝原因位于 errors[] 中，因此请检查 errors，而不只是状态码。只读密钥无法创建扫描：这是唯一的请求级失败，会返回 HTTP 400，其中包含 SY90016。

完整代码列表请参阅错误代码。

注意事项。

• 请求体必须封装在 input 对象中。
• 请检查 errors，而不是 HTTP 状态码。 创建请求被拒绝时会返回 HTTP 200。
• 扫描运行前会对电话号码进行标准化处理，仅在格式、字母大小写或空格方面存在差异的 2 个请求会被视为针对同一商家。
• 无论扫描检查多少个目录，此调用都会占用您的速率限制中的 1 次请求。
• 扫描会保留 90 天。此后，读取该扫描会返回 404，其中包含 SY83005。
• 此调用需要 Write（写入）密钥。