Listings APIListings API
登录

连接 Apple Business Connect

通过所有者已验证的 Apple Business 账户将地点发布到 Apple Maps；如果所有者没有此类账户，则通过 ListingsAPI 账户发布，然后检查商家信息，并在客户离开时断开连接。

ListingsAPI 通过以下 2 种方式之一，将地点的名称、类别、地址、电话、网站和营业时间发布到 Apple Maps 和 Siri。

商家所有者的账户情况处理方式
拥有已验证的 Apple Business 组织账户所有者通过 OAuth 链接将该账户连接到地点（步骤 1 和 2），ListingsAPI 随后通过其账户发布。
没有已验证的 Apple Business 组织账户无需连接。ListingsAPI 通过自己的 Apple Business Connect 账户提交地点，Apple 会先验证提交内容，再发布数据。请转到步骤 3。

OAuth 每次连接 1 个地点，site 设置为 APPLE。

如果所有者没有已验证的 Apple Business 组织账户，请跳过步骤 1 和 2。

POST /locations/oauth_connect_url 返回一个作用范围限定为单个地点的 OAuth URL。请在请求中发送 site: "APPLE"、地点 ID 和您的 2 个重定向 URL。参考：将地点连接到 Apple Business Connect。

Connect link
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"  }}'

响应为 data.createConnectUrl，包含 success、url 和 errors。将所有者重定向到 url。所有者登录其已验证的 Apple Business 组织账户并授予访问权限后，将被重定向到您的 successUrl；如果所有者取消或授权失败，则会被重定向到 errorUrl。

此链接只能使用 1 次，因此每次尝试都需要创建新链接。如果重定向 URL 是相对 URL 或无法解析，则会返回 success: true，但 url 为 null，因此请在重定向前检查 url。如果密钥无权操作此地点，则会收到 403，其中包含 SY90003。

2. 确认连接

所有者返回您的 successUrl 后，列出已连接账户，并筛选出 Apple 账户。此处采用偏移量分页：records[] 加上 pageInfo.totalRecords，使用 page 和 perPage 进行分页。

List accounts
curl "https://listingsapi.com/api/v4/connected-accounts?publisher=AppleAccount&page=1&perPage=20" \-H "Authorization: API $LISTINGSAPI_KEY"

保存 connectedAccountId。status 的值为 CONNECTED、MATCH_IN_PROGRESS 或 CONNECTIVITY_ISSUE；只要不是 CONNECTED，所有者就必须打开新的连接链接，之后才能通过其账户进行更新。

3. 检查 Apple Maps 商家信息

无论所有者是否连接了账户，此步骤都相同。GET /locations/{locationId}/listings/premium 为套餐中的每个高级发布平台返回 1 条记录。Apple Maps 记录的 site.url 设置为 business.apple.com。

Apple Maps status
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY"

在 Apple 发布地点卡片之前，记录不是 SYNCED，且 listingUrl 为 null。如果地点通过 ListingsAPI 账户提交，Apple 会先验证提交内容，再进行发布。Apple 发布后，记录为 SYNCED，且 listingUrl 设置为已上线的 Apple Maps URL。完整的状态表请参阅查看商家信息状态和上线链接。

Siri 结果来自该地点的 Apple Maps 商家信息。其状态由 GET /locations/{locationId}/voice-assistants 返回，位于 SIRI voiceIdentifier 下。

4. 确认建议的匹配项

如果连接建议包含 Apple 记录，这些记录的 accountType 为 APPLE，而您为确认连接匹配项 编码的匹配记录类型为 AppleLocationMatchedData。对 AppleLocationMatchedData:<matchedDataDatabaseId> 做 base64 编码得到 ID，并在 matchRecordIds 中发送该 ID。

5. 客户离开时断开地点连接

此步骤仅适用于通过 OAuth 连接的地点。POST /locations/oauth-disconnect 会移除一个地点与所有者的 Apple Business 账户之间的连接。发送 site: "APPLE"。该地点会保留在您的账户中，其与其他发布平台的连接不受影响。参考：断开地点与 Apple Business Connect 的连接。

Disconnect
curl -X POST https://listingsapi.com/api/v4/locations/oauth-disconnect \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "site": "APPLE" } }'

响应为 data.disconnectConnectedAccountsLocations，其中包含 success 和 errors。如果地点没有有效的 Apple 连接，则返回 SY10057；如果请求既不包含 site 也不包含 providerId，则返回 SY10056。

6. 后续流程

Apple 没有 connection.* webhook 事件。如果所有者通过 OAuth 建立了连接，请通过列出账户来确认连接（步骤 2）。在这两种情况下，都应通过读取 Apple Maps 记录来检查发布状态（步骤 3）。listing.submission 事件会在每次向发布平台提交的内容达到终态时报告该次提交。

如果连接之后报告 CONNECTIVITY_ISSUE，请创建新的连接链接（步骤 1），并请所有者重新登录。

后续步骤