接続済みアカウント

listingsapi-js SDKを使用して、Google、Facebook、Apple Business Connectのアカウントを接続し、それらの掲載情報を拠点に対応付け、アカウントの接続を解除します。

接続済みアカウントは、Google Business Profile、Facebook Pages、または Apple Business Connect の所有者による OAuth の認可です。認可が得られると、プラットフォームはそのアカウントが所有する掲載情報を読み取り、それぞれを拠点に紐付けることができます。接続済みアカウントのすべてのメソッドは、ListingsAPI クライアントインスタンスにあります。

通常は、接続リンクを作成し、所有者が認可するのを待ち、アカウントの一覧を取得して connectedAccountId を入手し、マッチングを開始し、候補を確認してから、その候補を確定するか、掲載情報を手動で紐付けます。各メソッドの解決値は、それぞれ固有のレスポンスキー配下にあるペイロードであり、そのキーは以下の各セクションに記載しています。

connectGoogleAccount

Google Business Profile 用に、1 つのアカウント全体を対象とする OAuth リンクを作成します。返された url に所有者を誘導してください。同意画面が閉じると、所有者は指定した successUrl または errorUrl に戻ります。

const link = await client.connectGoogleAccount('https://app.example.com/onboarding/google/done','https://app.example.com/onboarding/google/failed',); console.log(link.url);

パラメータ

解決値は、url、success、errors を含む bulkConnectLinkForGoogle ペイロードです。使用できないリダイレクトでも、url が null の成功レスポンスが返される場合があるため、success だけでなく url も確認してください。リンクの有効期間は短いため、試行のたびに新しいリンクを作成してください。

connectFacebookAccount

connectGoogleAccount に対応する Facebook Pages 用のメソッドで、同じ 2 つのリダイレクト引数を受け取ります。

const link = await client.connectFacebookAccount('https://app.example.com/onboarding/facebook/done','https://app.example.com/onboarding/facebook/failed',); console.log(link.url);

パラメータ

解決値は、url、success、errors を含む bulkConnectLinkForFacebook ペイロードです。

getOauthConnectUrl

アカウント全体ではなく、1 つの拠点を対象とする OAuth リンクを作成します。所有者が接続する拠点がすでにわかっていて、自社の製品内にあるその拠点の画面に所有者を戻したい場合に使用します。

const link = await client.getOauthConnectUrl(1800289,'GOOGLE','https://app.example.com/locations/1800289/connected','https://app.example.com/locations/1800289/connect-failed',); console.log(link.url);

パラメータ

解決値は、url、success、errors を含む createConnectUrl ペイロードです。両方のリダイレクト先が必須で、いずれも絶対 URL である必要があります。リンクは 1 回限り使用でき、指定した拠点に紐付いています。

fetchConnectedAccounts

利用中のアカウントで認可された Google および Facebook のアカウントを、接続の健全性と紐付け済み拠点数とともに一覧で取得します。以降のすべてのメソッドで必要となる connectedAccountId は、ここで取得します。

const page1 = await client.fetchConnectedAccounts({publisher: 'GoogleAccount',status: 'Connected',page: 1,perPage: 20,}); for (const record of page1.records ?? []) {console.log(record.email, record.connectedAccountId, record.status);}

オプション

解決値は connectedAccountsInfo ペイロードで、records 配列と、hasNextPage、hasPreviousPage、totalPages、totalRecords を含む pageInfo で構成されます。各レコードには、connectedAccountId、email、connectedAccountType、connectedLocationsCount、connectivityIssue、status、requestMatchesStatus が含まれます。

フィルターとフィールドでは、使用する値が異なります。status オプションは 'Connected'、'NotConnected'、'ConnectionIssue' のいずれかを受け取りますが、レコード自体の status は CONNECTED、MATCH_IN_PROGRESS、CONNECTIVITY_ISSUE のいずれかです。レコードの値をそのままフィルターに渡すと拒否されます。

fetchConnectedAccountDetails

ID を指定して 1 つのアカウントを読み取ります。ID がすでにわかっている場合は一覧全体をページごとに取得するよりも負荷が低く、マッチングの実行中にポーリングする際にもこのメソッドを使用します。

const details = await client.fetchConnectedAccountDetails('4f712c17-4f95-42dd-90f4-97171a2e67b5',); console.log(details.details.requestMatchesStatus); // MATCH_IN_PROGRESS, then MATCH_COMPLETED

パラメータ

解決値は connectedAccountDetails ペイロードで、details の配下に、一覧で返されるものと同じフィールドを持つレコードが格納されます。候補の準備ができたかどうかは requestMatchesStatus を監視して確認し、再認可を求めるかどうかは status と connectivityIssue を読み取って判断してください。

fetchConnectedAccountFolders

接続済みアカウントがアクセスできる Google アカウントグループ（フォルダー）を一覧で取得します。所有者が特定のグループに新しい掲載情報を作成したい場合は、createGmbListing の前にこのメソッドを呼び出してください。

const folders = await client.fetchConnectedAccountFolders('4f712c17-4f95-42dd-90f4-97171a2e67b5',); for (const folder of folders) {console.log(folder.folderId, folder.folderName, folder.locationCount);} // Narrow by nameconst matching = await client.fetchConnectedAccountFolders('4f712c17-4f95-42dd-90f4-97171a2e67b5',{ folderName: 'West Region' },);

オプション

解決値は getFoldersUnderGoogleAccount 配列で、デフォルトは空の配列です。各フォルダーには、folderId（変更せずにそのまま渡す accounts/<id> 文字列）、folderName、locationCount が含まれ、Google が件数を返さない場合、最後のフィールドは null になることがあります。このパスは、種類が Google のアカウントでのみ有効です。

fetchConnectedAccountListings

接続済みアカウントがアクセスできる掲載先の掲載情報を一覧で取得します。各レコードの id は、connectListing が受け取る connectedAccountListingId そのものなので、このメソッドを使って掲載情報の選択機能を実装できます。

const listings = await client.fetchConnectedAccountListings('4f712c17-4f95-42dd-90f4-97171a2e67b5',{ locationInfo: 'William St', page: 1, perPage: 50 },); for (const record of listings.records ?? []) {console.log(record.id, record.locationName, record.address);}

オプション

解決値は、records と pageInfo を含む connectedAccountListings ペイロードです。各レコードには、id、locationName、address、phone、liveLink、accountTypeName が含まれます。内部では書き込みのような形式のリクエストを使いますが、この操作は読み取りであり、SDK はエンドポイントの要件に従って、アカウント ID とページング情報をリクエストボディに格納します。

triggerConnectedAccountMatches

指定されたアカウントがアクセスできるすべてのプロフィールを取得し、利用中のアカウントの拠点と照合するジョブをキューに追加します。所有者が同意画面での操作を終えた直後と、拠点を一括作成した後に呼び出してください。

const result = await client.triggerConnectedAccountMatches(['4f712c17-4f95-42dd-90f4-97171a2e67b5',]); console.log(result.success, result.failedIds);

パラメータ

解決値は、success と failedIds を含む connectedAccountsTriggerMatches ペイロードです。success が true であることは、ジョブがキューに追加されたことを示し、マッチングの完了を意味するものではありません。requestMatchesStatus が MATCH_COMPLETED になるまで fetchConnectedAccountDetails をポーリングし、その後で候補を読み取ってください。

fetchConnectionSuggestions

マッチングによって生成された組み合わせを読み取り、紐付けを行う前に、担当者が各拠点と掲載先の掲載情報を比較できるようにします。

const suggestions = await client.fetchConnectionSuggestions('4f712c17-4f95-42dd-90f4-97171a2e67b5',{ page: 1, perPage: 50 },); for (const record of suggestions.records ?? []) {console.log(record.accountType, record.matchedDataDatabaseId, record.locationInfo.name);}

オプション

解決値は、records と pageInfo を含む connectionSuggestionsForAccount ペイロードです。候補レコードには id フィールドがありません。識別子は matchedDataDatabaseId で、accountType（GMB、FB、APPLE のいずれか）がマッチングレコードの種類を示します。confirmConnectedAccountMatches が受け取る ID の生成には両方が必要なため、この 2 つを一緒に保持してください。まだ一致するものがないアカウントでは、空の records 配列が返されます。

confirmConnectedAccountMatches

確認済みの組み合わせを承認します。確定すると、各拠点が掲載先の掲載情報に紐付けられ、以降の拠点の更新が反映されるようになります。

各 ID は候補レコードから生成します。マッチングレコードの型名とレコードの matchedDataDatabaseId をコロンで連結し、それを base64 エンコードしてください。GMB は GmbLocationMatchedData に、FB は FbLocationMatchedData に、APPLE は AppleLocationMatchedData に対応します。

const TYPES: Record<string, string> = {GMB: 'GmbLocationMatchedData',FB: 'FbLocationMatchedData',APPLE: 'AppleLocationMatchedData',}; const matchRecordId = (record: any) =>Buffer.from(TYPES[record.accountType] + ':' + record.matchedDataDatabaseId).toString('base64'); const approved = (suggestions.records ?? []).map(matchRecordId);const result = await client.confirmConnectedAccountMatches(approved); console.log(result.success, result.failedIds);

パラメータ

解決値は、success と failedIds を含む confirmConnectMatches ペイロードです。呼び出すたびに success を確認してください。ID をデコードした結果が 3 種類のいずれにも該当しない場合、成功時と同じ形式のレスポンスが返されますが、success は false で、failedIds は含まれません。一部の ID で失敗した場合、failedIds に格納されるのは送信したエンコード済みの値ではなく、デコードされたデータベース ID なので、matchedDataDatabaseId と照合してください。

1件の掲載情報と1つの拠点の関連付け

照合済みの掲載情報1件と拠点1つの関連付けを完了するためのメソッドは3つあります。重複して説明せず、他の掲載情報エンドポイントとともに説明しています。

• connectListingは、照合済みの掲載情報を拠点に関連付けます。
• disconnectListingは、その関連付けを解除します。
• createGmbListingは、Google Business Profileがない拠点に対して、fetchConnectedAccountFoldersで取得したフォルダ内に新しいGoogle Business Profileを作成します。

confirmConnectedAccountMatchesでアカウント内の大部分を処理した後、まだ手動で関連付ける必要がある店舗が1つ残っている場合に、これらを使用します。

oauthDisconnect

拠点ごとのOAuth経由で、同じ単一拠点の接続解除を実行します。同じ引数を受け取り、同じペイロードで解決されるため、コード内で読みやすい方の名前を選んでください。

await client.oauthDisconnect(1800289, 'GOOGLE');

パラメータ

disconnectConnectedAccountsLocationsペイロードで解決され、キーはdisconnectListingが返すものと同じです。

disconnectGoogleAccount

Googleアカウント全体の接続を解除すると、そのアカウント経由で関連付けられたすべての拠点が更新を受信しなくなります。顧客が解約する場合や所有権を譲渡する場合に使用します。

await client.disconnectGoogleAccount('4f712c17-4f95-42dd-90f4-97171a2e67b5');

パラメータ

successを含むgmbBulkDisconnectペイロードで解決されます。この操作では一部だけを解除できないため、アカウントを維持したまま1つの拠点の関連付けを解除するには、disconnectListingを使用してください。不明なIDであってもsuccessがtrueで返されるため、確実に確認する必要がある場合は、後でfetchConnectedAccountsを読み取ってください。

disconnectFacebookAccount

Facebook用の対応するメソッドで、引数は同じであり、一部だけを解除できない点も同じです。

await client.disconnectFacebookAccount('9d2b5a41-0c7e-4f83-bb16-2ac43e70d915');

パラメータ

successを含むfbBulkDisconnectペイロードで解決されます。同じ注意点が当てはまり、不明なIDでも成功が報告されるため、fetchConnectedAccountsで確認してください。

一般的な初期設定の流れ

import { ListingsAPI } from 'listingsapi-js'; const client = new ListingsAPI(); // reads LISTINGSAPI_KEY from env // 1. Send the owner through the consent screenconst link = await client.connectGoogleAccount('https://app.example.com/onboarding/google/done','https://app.example.com/onboarding/google/failed',);console.log('open:', link.url); // 2. After they return, pick up the account IDconst accounts = await client.fetchConnectedAccounts({ publisher: 'GoogleAccount' });const accountId = accounts.records[0].connectedAccountId; // 3. Match its listings against your locationsawait client.triggerConnectedAccountMatches([accountId]); // 4. Poll until matching finisheslet details = await client.fetchConnectedAccountDetails(accountId);while (details.details.requestMatchesStatus !== 'MATCH_COMPLETED') {await new Promise((resolve) => setTimeout(resolve, 5000));details = await client.fetchConnectedAccountDetails(accountId);} // 5. Read the suggestions and confirm the approved onesconst suggestions = await client.fetchConnectionSuggestions(accountId, { perPage: 100 });console.log('found ' + (suggestions.records ?? []).length + ' suggested matches');

関連リソース

• 掲載情報：掲載情報に関する同じ接続メソッドと接続解除メソッドの説明です
• 拠点：拠点IDを検索します
• エラー処理：各メソッドがスローする型付きエラーの説明です
• 接続済みアカウントのエンドポイント：これらのメソッドで使用するREST操作の手順です
• Googleへの接続と拠点のインポート：初期設定全体のガイドです
• Facebookページへの接続：Facebook向けの手順です
• Google Business Profileの作成：createGmbListingのガイドです
• RESTリファレンス：アカウント一覧、アカウントの詳細、フォルダ、アカウントの掲載情報、照合の開始、接続候補、照合結果の確定、掲載情報の接続、掲載情報の接続解除