Listings APIListings API
登入
POST/api/v4/locations/oauth_connect_url

將地點連結至 Apple Business Connect

為一個地點建立 Apple Business Connect OAuth 連結，讓 ListingsAPI 透過擁有者已通過驗證的 Apple Business 帳戶，將該地點發布至 Apple Maps。

需要 API 金鑰。標頭格式與金鑰輪替請參閱驗證。

參數

請求主體

名稱類型必填說明
inputobject必填Wrapper object. The entire request body must be nested under `input`.
input.locationIdstring必填Location to connect. Accepts a Base64-encoded Relay ID (e.g. `TG9jYXRpb246MTgwMDI4OQ==`) or a raw numeric location ID.
input.sitestring必填Set to `APPLE`.
input.successUrlstring必填Absolute URL in your application the owner returns to after granting access.
input.errorUrlstring必填Absolute URL in your application the owner returns to if they cancel or the grant fails.

請求範例

可直接貼上的請求主體。請將預留位置 ID 與值換成您自己的。

Request body
{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "site": "APPLE",    "successUrl": "https://app.example.com/locations/1800289/apple/connected",    "errorUrl": "https://app.example.com/locations/1800289/apple/connect-failed"  }}

回應

200A single-use link to send the owner to. `errors` is `null` on success. The `url` shown is a placeholder; send the owner to the `url` returned in your own response.
Response
{  "data": {    "createConnectUrl": {      "success": true,      "url": "https://connect.example.com/oauth?token=8f3c1d92-...",      "errors": null    }  }}
401Unauthenticated, missing or invalid API key.
403The key is valid but not permitted to connect this location (`SY90003`).

當商家擁有者具有已通過驗證的 Apple Business 組織帳戶時，請使用此端點。將擁有者導向 url；擁有者會登入 Apple Business Connect、授予存取權，然後回到您的 successUrl。此後，ListingsAPI 會透過擁有者的帳戶，將該地點的名稱、類別、地址、電話、網站和營業時間發布至 Apple Maps。如果擁有者取消或授權失敗，就會回到 errorUrl，且不會建立任何連結。

如果擁有者沒有已通過驗證的 Apple Business 組織帳戶，請略過此呼叫。ListingsAPI 會透過自己的 Apple Business Connect 帳戶發布該地點，而 Apple 會先驗證提交的內容，再將其發布。

Apple 的每個連結只能連結一個地點。若要連結多個地點，請為每個地點各建立一個連結。兩個重新導向 URL 都必須是絕對 URL；若值為相對 URL 或無法解析，仍會傳回 success: true，但 url 為 null，因此請在重新導向前檢查 url。此連結只能使用一次，因此每次嘗試時都請建立新的連結。

確認連結

擁有者回到 successUrl 後，請使用 publisher=AppleAccount 呼叫 列出已連結的帳戶。status 為 CONNECTED 表示更新會透過擁有者的帳戶進行。MATCH_IN_PROGRESS 或 CONNECTIVITY_ISSUE 表示擁有者必須開啟新的連結網址。

若要停止透過擁有者的帳戶發布，請使用 中斷地點與 Apple Business Connect 的連結。如需完整流程，包括如何檢查 Apple Maps 商家資訊，請參閱 連結 Apple Business Connect。

本頁說明 為一個地點建立 OAuth 連結 URL 中的 site: "APPLE" 情境。

此端點會建立可實際使用的 OAuth 憑證。上方的範例請求與回應僅供示範。

Request
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"    }  }'
Run in playground