建立 listings scan

啟動對單一商家的掃描。掃描會稽核商家是否已在各類目錄平台上刊登商家資訊，以及資訊是否正確：這些平台包括 Google、Bing、Apple Maps、Yelp、Facebook 和 MapQuest 等地圖與搜尋引擎、資料彙整平台與在地目錄，以及 ChatGPT 和 Gemini 等 AI 助理。依國家而定，1 次掃描最多會檢查約 60 個目錄。商家不需要是您帳戶中的地點，因此您可以稽核潛在客戶，或在客戶導入前進行稽核。

呼叫會立即傳回狀態為 QUEUED 的掃描。目錄檢查會在背景執行，您可透過 GET /listings/scans/{scanId} 讀取結果。

使用案例：稽核潛在客戶的商家資訊。您的銷售工具收集商家名稱、地址和電話號碼。建立掃描、儲存傳回的 scan.id，並在收到 listing_scan.completed 事件時，從 data.scan 讀取已完成的掃描。summary 提供摘要（多少個目錄找到該商家，以及其中多少個目錄的資訊正確），results[] 則提供各目錄的詳細資料，供報告呈現。

使用案例：檢查您已管理的商家資訊是否正常。使用您其中 1 個地點的商家詳細資料進行掃描。掃描會辨識出該地點，並使用該地點的實際商家資訊產生結果，而不會重新搜尋（請參閱重複使用與免費掃描）。

掃描如何結束

掃描會依序進入 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 秒讀取 1 次掃描，直到 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，不要只檢查狀態碼。唯讀金鑰無法建立掃描：這是唯一的請求層級失敗情況，會傳回帶有 SY90016 的 HTTP 400。

完整的代碼清單請見錯誤代碼。

注意事項。

• 請求主體必須包在 input 物件中。
• 請檢查 errors，而非 HTTP 狀態。遭拒的建立請求會傳回 HTTP 200。
• 電話號碼會在掃描執行前正規化，而僅在格式、字母大小寫或空白上有差異的 2 個請求會被視為同一商家。
• 無論掃描檢查多少個目錄，每次建立請求都會計入您的速率限制，占用 1 次請求額度。
• 掃描會保留 90 天。之後，讀取該掃描會傳回帶有 SY83005 的 404。
• 此呼叫需要 Write（寫入）金鑰。