Listings APIListings API
登入

連結 Apple Business Connect

透過擁有者已驗證的 Apple Business 帳戶，或在擁有者沒有此類帳戶時透過 ListingsAPI 帳戶，將地點發布至 Apple Maps，接著檢查商家資訊，並在客戶離開時中斷連結。

ListingsAPI 會透過下列兩種方式之一，將地點的名稱、類別、地址、電話、網站和營業時間發布至 Apple Maps 和 Siri。

商家擁有者的帳戶狀況處理方式
擁有已驗證的 Apple Business 組織帳戶擁有者透過 OAuth 連結將該帳戶連結至地點（步驟 1 和 2），ListingsAPI 就會透過擁有者的帳戶發布資料。
沒有已驗證的 Apple Business 組織帳戶無須連結帳戶。ListingsAPI 會透過自己的 Apple Business Connect 帳戶提交地點，Apple 則會先驗證提交內容，再發布資料。請前往步驟 3。

OAuth 每次只能連結一個地點，且 site 須設為 APPLE。

如果擁有者沒有已驗證的 Apple Business 組織帳戶，請略過步驟 1 和 2。

POST /locations/oauth_connect_url 會傳回僅適用於一個地點的 OAuth URL。請傳送 site: "APPLE"，並附上地點 ID 和您的兩個重新導向 URL。參考文件：將地點連結至 Apple Business Connect。

Connect link
curl -X POST https://listingsapi.com/api/v4/locations/oauth_connect_url \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "site": "APPLE",    "successUrl": "https://app.example.com/locations/1800289/apple/connected",    "errorUrl": "https://app.example.com/locations/1800289/apple/connect-failed"  }}'

回應為 data.createConnectUrl，內含 success、url 和 errors。請將擁有者重新導向至 url。擁有者登入已驗證的 Apple Business 組織帳戶並授予存取權後，會重新導向至您的 successUrl；若擁有者取消或授權失敗，則會重新導向至 errorUrl。

此連結只能使用一次，因此每次嘗試都必須建立新連結。若重新導向 URL 是相對 URL 或無法剖析，系統會傳回 success: true，其中 url 為 null，因此請在重新導向前檢查 url。若金鑰無權存取此地點，系統會傳回 403，並附上 SY90003。

2. 確認連線

擁有者返回您的 successUrl 後，請列出已連結的帳戶，並篩選出 Apple 帳戶。此回應採用位移分頁：包含 records[] 和 pageInfo.totalRecords，並以 page 和 perPage 控制分頁。

List accounts
curl "https://listingsapi.com/api/v4/connected-accounts?publisher=AppleAccount&page=1&perPage=20" \-H "Authorization: API $LISTINGSAPI_KEY"

請保留 connectedAccountId。status 的值為 CONNECTED、MATCH_IN_PROGRESS 或 CONNECTIVITY_ISSUE；只要不是 CONNECTED，擁有者就必須開啟新的連結網址，才能透過其帳戶更新資料。

3. 檢查 Apple Maps 商家資訊

無論擁有者是否已連結帳戶，此步驟都相同。GET /locations/{locationId}/listings/premium 會針對方案中的每個進階發布平台各傳回一筆記錄。Apple Maps 記錄的 site.url 設為 business.apple.com。

Apple Maps status
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY"

在 Apple 發布地點資訊卡之前，記錄不會是 SYNCED，且 listingUrl 為 null。若地點是透過 ListingsAPI 帳戶提交，Apple 會先驗證提交內容，再進行發布。Apple 發布後，記錄就會是 SYNCED，且 listingUrl 會設為已上線的 Apple Maps URL。如需完整的狀態表，請參閱檢查商家資訊狀態與已上線的連結。

Siri 結果來自該地點的 Apple Maps 商家資訊。其狀態由 GET /locations/{locationId}/voice-assistants 傳回，位於 SIRI 的 voiceIdentifier 下。

4. 確認建議的相符項目

如果連結建議包含 Apple 記錄，這些記錄的 accountType 為 APPLE，而您為確認連結相符項目 進行編碼時，使用的相符記錄類型為 AppleLocationMatchedData。請將 AppleLocationMatchedData:<matchedDataDatabaseId> 以 base64 編碼來建立 ID，並透過 matchRecordIds 傳送。

5. 客戶離開時，中斷地點的連線

此步驟僅適用於透過 OAuth 連結的地點。POST /locations/oauth-disconnect 會移除單一地點與擁有者的 Apple Business 帳戶之間的連線。傳送 site: "APPLE"。該地點會保留在您的帳戶中，它與其他發布平台的連線不受影響。參考文件：中斷地點與 Apple Business Connect 的連線。

Disconnect
curl -X POST https://listingsapi.com/api/v4/locations/oauth-disconnect \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "site": "APPLE" } }'

回應為 data.disconnectConnectedAccountsLocations，並包含 success 和 errors。若地點沒有有效的 Apple 連線，則會回傳 SY10057；若請求既未包含 site 也未包含 providerId，則會回傳 SY10056。

6. 接下來會發生什麼事

Apple 沒有 connection.* webhook 事件。如果擁有者透過 OAuth 連結，請列出帳戶以確認連線（步驟 2）。無論是哪種情況，請讀取 Apple Maps 記錄以檢查發布狀態（步驟 3）。listing.submission 事件會在每筆發布平台提交作業達到最終狀態時回報。

如果連線之後回報 CONNECTIVITY_ISSUE，請建立新的連結網址（步驟 1），並請擁有者重新登入。

後續步驟