Listings APIListings API
サインイン

Apple Business Connect に接続する

オーナーの確認済み Apple Business アカウントを通じて、またはオーナーにそのアカウントがない場合は ListingsAPI アカウントを通じて、拠点を Apple Maps に公開し、その後で掲載情報を確認して、クライアントが契約を終了したら接続を解除します。

ListingsAPI は、次の 2 つの方法のいずれかで、拠点の名前、カテゴリ、住所、電話番号、ウェブサイト、営業時間を Apple Maps と Siri に公開します。

ビジネスオーナーのアカウント保有状況処理内容
確認済みの Apple Business 組織アカウントがある場合オーナーが OAuth リンクでそのアカウントを拠点に接続し（手順 1 と 2）、ListingsAPI がオーナーのアカウントを通じて公開します。
確認済みの Apple Business 組織アカウントがない場合接続は不要です。ListingsAPI が自社の Apple Business Connect アカウントを通じて拠点を送信し、Apple が送信内容を確認してからデータを公開します。手順 3 に進んでください。

OAuth では、site を APPLE に設定して、拠点を 1 つずつ接続します。

オーナーに確認済みの Apple Business 組織アカウントがない場合は、手順 1 と 2 をスキップしてください。

POST /locations/oauth_connect_url は、1 つの拠点を対象とする OAuth URL を返します。拠点 ID と 2 つのリダイレクト URL を指定して site: "APPLE" を送信します。リファレンス：拠点を 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 または解析できない URL の場合も success: true が返されますが、url は null になります。そのため、リダイレクトする前に url を確認してください。この拠点へのアクセス権限がないキーを使用すると、SY90003 を含む 403 が返されます。

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 に指定して送信します。

5. クライアントとの契約が終了したら拠点の接続を解除する

この手順は、OAuth で接続された拠点にのみ適用されます。POST /locations/oauth-disconnect は、1 つの拠点とオーナーの 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）、オーナーに再度サインインするよう依頼します。

次の手順