POST/api/v4/locations/oauth_connect_url

為單一地點建立 OAuth 連結網址

建立用於連結單一地點的發布平台 OAuth 連結,並使用您自訂的成功與錯誤重新導向網址。

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

參數

請求主體

名稱類型必填說明
inputobject必填Wrapper object. The entire request body must be nested under `input`.
input.locationIdstring必填Location the connection will be attached to. Accepts a Base64-encoded Relay ID (e.g. `TG9jYXRpb246MTgwMDI4OQ==`) or a raw numeric location ID.
input.sitestring必填Publisher to connect: `GOOGLE`, `FACEBOOK`, or `APPLE`.
input.successUrlstring必填Absolute URL the publisher returns the user to after they grant access.
input.errorUrlstring必填Absolute URL the publisher returns the user to if they cancel or the grant fails.

請求範例

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

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

回應

200A single-use OAuth URL to send the user to. `errors` is `null` on success. The `url` shown is a placeholder; send the user 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`).

傳回僅適用於單一地點的發布平台 OAuth 網址。將終端使用者導向 url;完成後,發布平台會將使用者重新導向您的 successUrl(或 errorUrl),並將產生的憑證以已連結帳戶的形式附加至該地點。

這是批次流程的單一地點版本;批次流程包括批次連結 Google 帳戶和批次連結 Facebook 帳戶,會建立適用於整個帳戶的連結,再透過比對附加商家資訊。當您已知道使用者要連結哪個地點,並希望使用者返回您自家產品中該地點的頁面時,請使用此路由。

兩個重新導向網址都是必填,且必須是絕對網址;若值為相對網址或無法剖析,仍會傳回 success: true,但 url 為 null,因此請檢查 url,而非僅檢查 success。此連結只能使用一次,且綁定您指定的地點,因此每次嘗試時都應建立新連結,而非快取連結。

使用案例:從您自家的應用程式連結單一商店

當使用者從您的應用程式連結單一商店時,請使用 POST 呼叫此路由,並提供該地點的 ID、site: "GOOGLE",以及指向您應用程式內頁面的重新導向網址。透過彈出式視窗或整頁重新導向,將使用者導向 url。使用者返回後,請讀取取得已連結帳戶的詳細資料或該地點的連結資訊,確認連結已成功建立,再於您的應用程式中顯示已連結狀態。若使用者中途放棄流程,便會前往 errorUrl,且不會附加任何帳戶,因此請建立新連結,讓使用者再試一次。

使用案例:透過擁有者的 Apple Business 帳戶發布

傳送 site: "APPLE",將單一地點連結至擁有者已通過驗證的 Apple Business 組織帳戶。擁有者開啟 url、登入該帳戶,並授予存取權限。此後,ListingsAPI 會透過擁有者的帳戶發布該地點的 Apple Maps 資料。

若擁有者沒有已通過驗證的 Apple Business 組織帳戶,請略過此流程。ListingsAPI 會透過自有的 Apple Business Connect 帳戶發布該地點,而 Apple 會在發布前驗證提交內容。每個地點皆個別連結,因此同一個帳戶可以同時包含這兩種地點。

擁有者返回 successUrl 後,請使用 publisher=AppleAccount 呼叫列出已連結帳戶,並確認該帳戶的 status 為 CONNECTED。如需完整流程,包括如何檢查 Apple Maps 商家資訊,請參閱連結 Apple Business Connect。

此端點會建立可實際使用的 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": "GOOGLE",      "successUrl": "https://app.example.com/locations/1800289/connected",      "errorUrl": "https://app.example.com/locations/1800289/connect-failed"    }  }'