/api/v4/locations/oauth_connect_url為單一地點建立 OAuth 連結網址
建立用於連結單一地點的發布平台 OAuth 連結,並使用您自訂的成功與錯誤重新導向網址。
參數
請求主體
| 名稱 | 類型 | 必填 | 說明 |
|---|---|---|---|
| input | object | 必填 | Wrapper object. The entire request body must be nested under `input`. |
| input.locationId | string | 必填 | Location the connection will be attached to. Accepts a Base64-encoded Relay ID (e.g. `TG9jYXRpb246MTgwMDI4OQ==`) or a raw numeric location ID. |
| input.site | string | 必填 | Publisher to connect: `GOOGLE`, `FACEBOOK`, or `APPLE`. |
| input.successUrl | string | 必填 | Absolute URL the publisher returns the user to after they grant access. |
| input.errorUrl | string | 必填 | Absolute URL the publisher returns the user to if they cancel or the grant fails. |
請求範例
可直接貼上的請求主體。請將預留位置 ID 與值換成您自己的。
{ "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.
{ "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 憑證。上方的範例請求與回應僅供示範。
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" } }'