POST/api/v4/locations/oauth_connect_url

为一个地点创建 OAuth 连接 URL

创建用于连接单个地点的发布平台 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。将最终用户引导至 url;用户完成操作后,发布平台会将其重定向至您的 successUrl(或 errorUrl),生成的凭据会以已连接账户的形式关联到该地点。

这是批量流程 批量连接 Google 账号和 批量连接 Facebook 账号的单地点版本;这些批量流程会创建适用于整个账户的链接,然后通过匹配来关联商家信息。如果您已经知道用户要连接哪个地点,并希望用户返回您自己产品中该地点的页面,请使用此路由。

两个重定向 URL 均为必填项,且必须是绝对 URL;如果传入相对 URL 或无法解析的值,响应仍为 success: true,但 url 为 null,因此请检查 url,而不只是 success。该链接只能使用一次,且与您指定的地点绑定,因此请为每次尝试创建新链接,不要缓存链接。

使用场景:从您自己的应用连接一家门店

当用户从您的应用连接一家门店时,请使用该地点的 ID、site: "GOOGLE" 以及指向您应用内部的重定向 URL,以 POST 方法调用此路由。通过弹出窗口或整页重定向将用户引导至 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"    }  }'