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