接続済みアカウント

GoogleとFacebookの接続、アカウント一覧の取得、掲載情報の照合とリンク、フォルダー、GMB作成、接続解除に関する、接続済みアカウントの全エンドポイントを、cURL、Python、Nodeのサンプル付きで説明します。

接続済みアカウントは、Google Business Profile または Facebook ページの所有者が付与した OAuth 認可を表し、API はそのアカウントでアクセスできる掲載情報を読み取り、管理できます。このリソースは、OAuth リンクの作成、アカウントの掲載情報と拠点の照合または関連付け、接続の解除という 3 つの処理を扱います。一覧と詳細を取得する 2 つの GET は Read(読み取り)キーで使用できますが、読み取り専用の掲載情報取得も含め、すべての POST には Write(書き込み)キーが必要で、書き込み操作に Read キーを使用すると、HTTP 400 と SY90016 が返されます。

以下のすべてのサンプルは、最初のサンプルに示す方法でクライアントを一度だけ作成することを前提とし、環境変数から LISTINGSAPI_KEY を読み取ります。ID には、一覧エンドポイントから取得した connectedAccountId UUID と base64 形式の拠点 ID(TG9jYXRpb246MTgwMDI4OQ==)を使用し、どちらも URL エンコードしないでください。

エンドポイント一覧

メソッドパス機能リファレンス
POST/connected-accounts/connect-googleGoogle アカウント用の、有効期間が 24 時間の一括接続リンクを作成します。Google アカウントの接続
POST/connected-accounts/connect-facebookFacebook アカウント用の、有効期間が 24 時間の一括接続リンクを作成します。Facebook アカウントの接続
POST/locations/oauth_connect_url1 つの拠点に紐付いた、1 回限り使用できる接続リンクを作成します。1 つの拠点用の OAuth 接続 URL
GET/connected-accounts接続済みアカウントの一覧を、接続状態と関連付け済み件数とともに取得します。接続済みアカウントの一覧取得
GET/connected-accounts/{connectedAccountId}/details照合ジョブの状態を含む、1 つのアカウントの情報を取得します。接続済みアカウントの詳細取得
POST/connected-accounts/connected-account-listingsアカウントがアクセスできる掲載先の掲載情報を一覧で取得します。接続済みアカウントの掲載情報の取得
POST/connected-accounts/trigger-matches1 つ以上のアカウントに対して、取得と照合を行うジョブをキューに追加します。拠点照合の実行
GET/connected-accounts/{connectedAccountId}/connection-suggestions拠点と掲載情報の関連付け候補を取得します。接続候補の一覧取得
POST/connected-accounts/confirm-matches候補を承認して、実際の関連付けを作成します。接続の照合結果の確定
POST/connected-accounts/connect-listing選択した 1 件の掲載情報を 1 つの拠点に関連付けます。掲載情報と拠点の接続
POST/connected-accounts/disconnect-listing1 つの拠点と 1 つの掲載先の関連付けを解除します。掲載情報と拠点の接続解除
POST/connected-accounts/create-location-from-listing掲載先の掲載情報から新しい拠点を作成します。掲載情報からの拠点作成
GET/connected-accounts/{connectedAccountId}/foldersGoogle アカウントのグループ(フォルダー)を一覧で取得します。GMB フォルダーの一覧取得
POST/locations/create/gmb-listing拠点用に Google Business Profile を新規作成します。GMB 掲載情報の作成
POST/connected-accounts/disconnect-googleGoogle アカウント全体の接続を解除します。Google アカウントの接続解除
POST/connected-accounts/disconnect-facebookFacebook アカウント全体の接続を解除します。Facebook アカウントの接続解除
POST/locations/oauth-disconnect1 つの拠点と掲載先の接続を解除します(disconnect-listing と同じ操作です)。1 つの拠点と掲載先の接続解除

POST /connected-accounts/connect-google

有効期間の短い OAuth URL を返します。アカウント所有者をその URL にリダイレクトすると、Google は所有者を指定された successUrl または errorUrl に戻します。リンクの対象は API キーを所有するアカウントに限定されるため、リクエストボディには 2 つのリダイレクト先のみを含めます。認可の有効期限が切れたアカウントのリンクを再発行すると、接続が重複して作成されるのではなく、既存の接続が更新されます。

名前指定場所必須備考
inputbodyはいラッパーオブジェクトで、ボディ全体をこの配下に配置します。
input.successUrlbodyはい自身で管理する https の絶対 URL です。同意後にこの URL に遷移します。
input.errorUrlbodyはい自身で管理する https の絶対 URL です。キャンセル時または失敗時にこの URL に遷移します。
Connect Google
curl -X POST https://listingsapi.com/api/v4/connected-accounts/connect-google \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "successUrl": "https://app.example.com/connect/google/success",    "errorUrl": "https://app.example.com/connect/google/error"  }}'
JSON
{  "data": {    "bulkConnectLinkForGoogle": {      "success": true,      "url": "https://connect.example.com/oauth?token=8f3c1d92-...",      "errors": null    }  }}

上記の url はプレースホルダーです。実際のレスポンスで返された url に所有者を誘導してください。

リンクの有効期間は 24 時間です。errors に値が設定されるのは生成に失敗した場合のみなので、url が null でないことを確認してください。フラットなボディ、または accountId を含むボディは HTTP 400 で拒否されます。

POST /connected-accounts/connect-facebook

Google 接続リンクに対応する Facebook 用のリンクで、同じリクエストボディを使用します。このフローでは、所有者が Facebook の利用規約に同意し、API に必要なページ管理権限を付与しますが、いずれかの権限の付与を省略すると、この接続では同期できないため、リンクを再発行して再度同意してもらってください。

名前指定場所必須備考
inputbodyはいラッパーオブジェクトです。
input.successUrlbodyはい自身で管理する https の絶対 URL です。
input.errorUrlbodyはい自身で管理する https の絶対 URL です。
Connect Facebook
curl -X POST https://listingsapi.com/api/v4/connected-accounts/connect-facebook \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "successUrl": "https://app.example.com/connect/facebook/success",    "errorUrl": "https://app.example.com/connect/facebook/error"  }}'
JSON
{  "data": {    "bulkConnectLinkForFacebook": {      "success": true,      "url": "https://connect.example.com/oauth?token=8f3c1d92-...",      "errors": null    }  }}

上記の url はプレースホルダーです。実際のレスポンスで返された url に所有者を誘導してください。

レスポンスのキーは bulkConnectLinkForFacebook で、それ以外は Google 接続リンクとまったく同じ方法で読み取ります。所有者が手続きを完了すると、アカウントは一覧エンドポイントに FacebookAccount として表示されます。

POST /locations/oauth_connect_url

オーナーが接続する拠点がすでにわかっている場合に使用します。リンクは指定した拠点に紐づくため、その後の照合処理はありません。オーナーが同意すると、認証情報がその拠点に直接紐づけられます。上記の2種類の一括接続リンクは、どちらもアカウント全体を接続します。

名前指定場所必須備考
inputbodyはいラッパーオブジェクトです。
input.locationIdbodyはいBase64形式の拠点ID、またはエンコード前の数値IDです。
input.sitebodyはいGOOGLE、FACEBOOK、またはAPPLEです。
input.successUrlbodyはい認可後の遷移先となる絶対URLです。
input.errorUrlbodyはいキャンセル時または失敗時の遷移先となる絶対URLです。
Single-location 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": "GOOGLE",    "successUrl": "https://app.example.com/locations/1800289/connected",    "errorUrl": "https://app.example.com/locations/1800289/connect-failed"  }}'
JSON
{  "data": {    "createConnectUrl": {      "success": true,      "url": "https://connect.example.com/oauth?token=8f3c1d92-...",      "errors": null    }  }}

上記のurlはプレースホルダーです。実際のレスポンスで返されたurlにオーナーを誘導してください。

リンクは1回しか使用できないため、キャッシュせず、試行ごとに新しく作成してください。リダイレクトURLが相対URLであるか解析できない場合は、null urlを伴うsuccess: trueが返されるため、successだけでなくurlも確認してください。この拠点へのアクセス権限がないキーを使用すると、SY90003を伴う403が返されます。SDKはsiteを自動的に大文字に変換します。

接続済みアカウントの一覧を取得する

GET /connected-accounts

APIアカウントに対して認可されたすべてのアカウントを、接続の正常性と各アカウントに紐づく拠点数とともに返します。オフセット方式のページで、records[]とpageInfo.totalRecordsを含み、ネストされていないクエリパラメータpageとperPageでページを指定します。並び順はアカウントのメールアドレスの昇順に固定されています。

名前指定場所必須備考
pagequeryいいえ1から始まるページ番号です。デフォルトは1です。
perPagequeryいいえ1ページあたりのレコード数です。デフォルトは20です。
publisherqueryいいえGoogleAccount、FacebookAccount、AppleAccount、YelpAccount、TripadvisorAccount、LinkedinAccount、PinterestAccount、またはTwitterAccountです。
statusqueryいいえConnected、NotConnected、またはConnectionIssueです。大文字と小文字が混在しています。
List accounts
curl "https://listingsapi.com/api/v4/connected-accounts?publisher=GoogleAccount&status=Connected&page=1&perPage=20" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "connectedAccountsInfo": {      "pageInfo": { "hasNextPage": false, "hasPreviousPage": false, "totalPages": 1, "totalRecords": 1 },      "records": [        {          "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",          "connectedAccountType": "GoogleAccount",          "email": "owner@brightsmile-dental.com",          "status": "CONNECTED",          "connectivityIssue": null,          "connectedLocationsCount": 0,          "requestMatchesStatus": "MATCH_COMPLETED",          "lastFetchMatchesRequestedAt": "2026-07-06 21:43:07 UTC"        }      ]    }  }}

emailが同意したオーナーに該当するレコードを選び、そのconnectedAccountIdを保持してください。以降のすべての呼び出しで使用します。4つのクエリパラメータ以外は拒否されずに無視されるため、JSONのpageInfoを送信しても、通知なくページ1が返されます。

レコードのstatus意味
CONNECTED認証情報は有効です。照合の実行や公開を行っても問題ありません。
MATCH_IN_PROGRESS照合処理がキューで待機中、または実行中です。
CONNECTIVITY_ISSUE認可の有効期限が切れています。connectivityIssueに理由が示されているため、接続リンクを再発行してください。

statusフィルターとレコードのstatusフィールドでは、使用する値が異なります。CONNECTEDをフィルターにそのまま渡すと、無効な列挙値として400が返されます。

1つのアカウントの詳細を取得する

GET /connected-accounts/{connectedAccountId}/details

1つのアカウントを対象に、一覧の1レコードと同じフィールドを返します。照合の開始後にrequestMatchesStatusをポーリングする場合や、アカウント経由で更新を送信する前にstatusとconnectivityIssueを確認する場合に使用します。

名前指定場所必須備考
connectedAccountIdpathはい一覧取得エンドポイントから取得したUUIDです。
Account details
curl https://listingsapi.com/api/v4/connected-accounts/4f712c17-4f95-42dd-90f4-97171a2e67b5/details \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "connectedAccountDetails": {      "details": {        "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",        "connectedAccountType": "GoogleAccount",        "status": "CONNECTED",        "connectivityIssue": null,        "connectedLocationsCount": 0,        "requestMatchesStatus": "MATCH_COMPLETED"      }    }  }}

レコードは1階層下のdata.connectedAccountDetails.detailsにあります。候補の準備ができると、requestMatchesStatusはMATCH_IN_PROGRESSからMATCH_COMPLETEDに変わります。Completedは照合処理が終了したことを意味し、何かが紐づけられたことを意味するわけではありません。掲載情報の確認または接続を行うまで、connectedLocationsCountは0のままです。

アカウントがアクセスできる掲載情報を取得する

POST /connected-accounts/connected-account-listings

拠点に紐づいているかどうかにかかわらず、アカウントがアクセスできるすべてのGoogle Business ProfileまたはFacebookの掲載情報を一覧表示します。各レコードのidは、connect-listingとcreate-location-from-listingに渡すconnectedAccountListingIdです。これは読み取りのみを行うPOSTであり、records[]とpageInfoを含むオフセット方式のページを返し、body内のネストされていないキーpageとperPageでページを指定します。

名前指定場所必須備考
connectedAccountIdbodyはい掲載情報を取得するアカウントのUUIDです。inputで囲みません。
pagebodyいいえページ番号です。デフォルトは1です。
perPagebodyいいえ1ページあたりのレコード数です。デフォルトは500で、これが最大値でもあります。
locationInfobodyいいえ名前、住所、市区町村、郵便番号、店舗コード、電話番号を対象としたフリーテキスト検索です。
Account listings
curl -X POST https://listingsapi.com/api/v4/connected-accounts/connected-account-listings \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5", "perPage": 50, "locationInfo": "William St" }'
JSON
{  "data": {    "connectedAccountListings": {      "pageInfo": { "hasNextPage": false, "totalPages": 1, "totalRecords": 60 },      "records": [        {          "id": "R21iQnVsa0RhdGFMYWtlOjA2MDQ4NmExLTA0NzQtNDc4NS1iMjNhLTBkOGM4MzhmNGQ5OA==",          "accountTypeName": "Google",          "locationName": "Trial",          "address": "123 William St, NY 10038, Manhattan, US",          "phone": "(718) 667-7787",          "liveLink": null        }      ]    }  }}

pageInfo.hasNextPageとpageInfo.totalPagesを使用して、結果をページごとに取得してください。SDKはconnectedAccountIdを自動的にbodyに含めるため、この点が影響するのは手動で実装したREST呼び出しのみです。

マッチングの開始

POST /connected-accounts/trigger-matches

指定したアカウントがアクセスできるすべてのプロフィールを取得し、それぞれをいずれかの拠点と対応付けるジョブをキューに登録します。マッチングの対象は、アクティブでアーカイブされておらず、まだ接続されていないすべての拠点です。候補のみを保存し、確定するまでは何もリンクされません。

名前指定場所必須備考
inputbodyはいラッパーオブジェクトです。
input.connectedAccountIdsbodyはい一覧エンドポイントから取得したアカウントの UUID の配列です。
Trigger matches
curl -X POST https://listingsapi.com/api/v4/connected-accounts/trigger-matches \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "connectedAccountIds": ["4f712c17-4f95-42dd-90f4-97171a2e67b5"] } }'
JSON
{  "data": {    "connectedAccountsTriggerMatches": {      "success": true,      "failedIds": null    }  }}

success: trueはジョブがキューに登録されたことを示し、マッチングが完了したことを示すものではありません。キューに登録できなかったアカウントはfailedIdsに記載され、successはfalseになります。候補を読み取る前に、requestMatchesStatusがMATCH_COMPLETEDになるまで詳細エンドポイントをポーリングしてください。上限を設けたループで15秒ごとにポーリングすると、Launch プランの1分あたり10リクエストという制限内に収まります。

接続候補の取得

GET /connected-accounts/{connectedAccountId}/connection-suggestions

マッチング処理で提案された組み合わせを返します。一方は拠点(locationInfoで、databaseIdはlocationId)、もう一方は掲載先の掲載情報(suggestedLocationInfo)です。このページはオフセット方式でページ分割され、ネストされていないクエリパラメーターpageとperPageでページを指定します。並び順は拠点情報の昇順に固定されています。

名前指定場所必須備考
connectedAccountIdpathはいアカウントの UUID です。
pagequeryいいえ1から始まるページ番号です。デフォルトは1です。
perPagequeryいいえ1ページあたりのレコード数です。デフォルトは20です。
Suggestions
curl "https://listingsapi.com/api/v4/connected-accounts/4f712c17-4f95-42dd-90f4-97171a2e67b5/connection-suggestions?page=1&perPage=20" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "connectionSuggestionsForAccount": {      "pageInfo": { "hasNextPage": false, "totalPages": 1, "totalRecords": 2 },      "records": [        {          "accountType": "GMB",          "matchedDataDatabaseId": "0d5e306f-0da0-46e3-929f-fd3c67ccd8cc",          "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",          "locationId": "73415",          "locationInfo": { "name": "My Business", "city": "Lincoln", "stateIso": "NE" },          "suggestedLocationInfo": { "locationInfo": { "name": "My Business", "city": "Lincoln" } }        }      ]    }  }}

候補にはidがありません。confirm-matches は id の生成にmatchedDataDatabaseIdとaccountTypeの両方を必要とするため、これらを一緒に保持してください。MATCH_COMPLETEDより前に読み取ると、エンドポイントはtotalRecords: 0を伴うrecords: []を返すため、「一致するものがなかった」場合とまったく同じに見えます。

accountType掲載先マッチングレコードの型
GMBGoogle Business ProfileGmbLocationMatchedData
FBFacebook PagesFbLocationMatchedData
APPLEApple Business ConnectAppleLocationMatchedData

マッチング結果の確定

POST /connected-accounts/confirm-matches

承認した候補を受け付け、実際のリンクを作成します。各 id は<MatchRecordType>:<matchedDataDatabaseId>を base64 でエンコードしたもので、型は上の表から選択します。アカウントはレコードから判定されるため、connectedAccountIdフィールドはありません。input内に未定義のフィールドがあると、400で拒否されます。

名前指定場所必須備考
inputbodyはいラッパーオブジェクトです。matchRecordIdsのみが宣言されています。
input.matchRecordIdsbodyはいbase64 でエンコードされたマッチングレコードの id の配列です。少なくとも1つ必要です。
Confirm matches
# base64 of GmbLocationMatchedData:0d5e306f-0da0-46e3-929f-fd3c67ccd8cccurl -X POST https://listingsapi.com/api/v4/connected-accounts/confirm-matches \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "matchRecordIds": ["R21iTG9jYXRpb25NYXRjaGVkRGF0YTowZDVlMzA2Zi0wZGEwLTQ2ZTMtOTI5Zi1mZDNjNjdjY2Q4Y2M="] } }'
JSON
{  "data": {    "confirmConnectMatches": {      "success": true,      "failedIds": null    }  }}

failedIdsには、すでに使用済みのレコードやマッチング後にアーカイブされた拠点など、確定できなかったもののデコード済みのmatchedDataDatabaseIdの値が含まれるため、候補レコードと照合してください。送信しなかった候補は変更されません。確定すると拠点と掲載情報がリンクされますが、それだけでは掲載先にデータは送信されません。

1つの掲載情報を拠点に接続

POST /connected-accounts/connect-listing

選択済みの1つの掲載情報を1つの拠点にリンクし、候補の提示や確定の手順はありません。近隣に似た名前の店舗が2つある場合など、マッチングの結果が曖昧で、担当者がアカウントの掲載情報から正しいものを選ぶ場合に使用します。

名前指定場所必須備考
inputbodyはいラッパーオブジェクトです。
input.locationIdbodyはいbase64 でエンコードされた拠点の id です。
input.connectedAccountIdbodyはい掲載情報を所有するアカウントの UUID です。
input.connectedAccountListingIdbodyはいアカウントの掲載情報エンドポイントから取得したレコードのidです。listingIdではありません。
Connect listing
curl -X POST https://listingsapi.com/api/v4/connected-accounts/connect-listing \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",    "connectedAccountListingId": "R21iQnVsa0RhdGFMYWtlOjA2MDQ4NmExLTA0NzQtNDc4NS1iMjNhLTBkOGM4MzhmNGQ5OA=="  }}'
JSON
{  "data": {    "connectListing": {      "success": true,      "message": null    }  }}

リンクに失敗すると、null ではないmessageを伴うsuccess: falseが返されます。たとえば、掲載情報の id に対応する掲載情報が見つからない場合はListing record not foundが、掲載情報がすでに別の拠点に接続されている場合はその旨のメッセージが返されます。両方の SDK で、このメソッドは connected accounts ではなく listings リソースにあります。

拠点から1つの掲載情報の接続を解除

POST /connected-accounts/disconnect-listing

1つの拠点と1つの掲載先の間のリンクを解除します。拠点とそのデータは保持され、その掲載先への送信同期のみが停止します。一括処理用のエンドポイントではないため、拠点ごとにループで呼び出してください。店舗の接続先を別の Google アカウントに変更するには、まずここで接続を解除し、その後、新しいアカウントでマッチングまたは接続を行ってください。

名前指定場所必須備考
inputbodyはいラッパーオブジェクトです。
input.locationIdbodyはい対象となる1つの拠点の、base64 でエンコードされた id です。
input.sitebodyいずれか1つGOOGLE、FACEBOOK、またはAPPLEです。providerIdを送信しない場合は必須です。
input.providerIdbodyいずれか1つsiteの代わりに指定する、掲載先独自のアカウント識別子です。
Disconnect listing
curl -X POST https://listingsapi.com/api/v4/connected-accounts/disconnect-listing \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "locationId": "TG9jYXRpb246MTgwMDI4OQ==", "site": "GOOGLE" } }'
JSON
{  "data": {    "disconnectConnectedAccountsLocations": {      "clientMutationId": null,      "success": true,      "errors": null    }  }}

siteもproviderIdも送信しない場合、SY10056が返されます。拠点にそのサイトへのアクティブな接続がない場合は、何もせず成功として扱うのではなくSY10057が返されるため、success: trueはリンクが実際に解除されたことを意味します。SDK はsiteのみを受け付け、大文字に変換します。

掲載情報から拠点を作成する

POST /connected-accounts/create-location-from-listing

マッチングでは、掲載情報を既存の拠点にのみ関連付けます。拠点がない掲載情報については、この操作で掲載先のデータから拠点を作成し、その場で掲載情報に関連付けます。Googleからは、名前、住所、座標、電話番号、ウェブサイト、説明、通常の営業時間と特別営業時間、カテゴリ、開業日、店舗コード、タイムゾーンに加え、掲載情報のGoogle属性から取得した支払い方法とソーシャルリンクをインポートします。Facebookからは、名前、拠点情報、営業時間、カテゴリ、説明、連絡先情報をインポートします。

GoogleからのインポートではデータをGoogleに再送信しないため、拠点の最初の更新がGoogleの掲載情報に反映されるまで、その掲載情報はIN_PROGRESSのままです。それ以外の掲載先には通常どおり送信され、このエンドポイントではサイトの対象範囲を指定できないため、拠点はアカウントの全掲載先を対象として作成されます。作成直後にenabledSiteIdsで対象を絞り込み、その更新をすぐに送信してください。ほかの掲載先の注文項目は作成後まもなく生成され、生成済みの項目はこの更新では取り消されません。

どちらのSDKもこのエンドポイントのラッパーをまだ提供していないため、PythonとNodeのサンプルでは同じヘッダーを使用してRESTを呼び出します。

名前指定箇所必須補足
inputbodyはいラッパーオブジェクトです。
input.connectedAccountIdbodyはい掲載情報を所有するアカウントのUUIDです。
input.connectedAccountListingIdbodyはいアカウントの掲載情報エンドポイントから取得したレコードのidです。listingIdではありません。
Create from listing
curl -X POST https://listingsapi.com/api/v4/connected-accounts/create-location-from-listing \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",    "connectedAccountListingId": "R21iQnVsa0RhdGFMYWtlOjA2MDQ4NmExLTA0NzQtNDc4NS1iMjNhLTBkOGM4MzhmNGQ5OA=="  }}'
JSON
{  "data": {    "createLocationFromConnectedAccountListing": {      "success": true,      "locationId": 88277,      "errors": null    }  }}

locationIdは、新しい拠点のプレーンなdatabaseIdです。失敗時はsuccessがfalse、locationIdがnullとなり、errorsにはSY81067(掲載情報のidに対応する掲載情報が見つからなかった)などの理由を示すコードが格納されます。ほかの原因として、掲載情報がすでに別の拠点に関連付けられている場合や、アカウントの認証情報の有効期限が切れている場合があります。作成後は、ほかの拠点と同様に管理できます。

Googleアカウントのフォルダ一覧を取得する

GET /connected-accounts/{connectedAccountId}/folders

接続済みのGoogleアカウントがアクセスできるGoogle Business Profileのアカウントグループ(フォルダ)を返します。新しいプロフィールが所有者の意図するグループに配置されるように、GMBの掲載情報を作成する前に使用してください。レスポンスのgetFoldersUnderGoogleAccountに含まれるのは通常の配列であり、ページではありません。このパスはGoogleAccountの接続でのみ有効です。

名前指定箇所必須補足
connectedAccountIdpathはいGoogleタイプのアカウントのUUIDです。
Folders
curl https://listingsapi.com/api/v4/connected-accounts/4f712c17-4f95-42dd-90f4-97171a2e67b5/folders \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "getFoldersUnderGoogleAccount": [      { "folderId": "accounts/104890024806530350198", "folderName": "Bright Smile Dental", "locationCount": null }    ]  }}

folderIdは数値ではなくaccounts/{id}文字列なので、そのまま使用してください。Googleから報告されない場合、locationCountはnullになることがあるため、任意の項目として扱ってください。

拠点のGoogle Business Profileを作成する

POST /locations/create/gmb-listing

Googleの掲載情報がない拠点に対して、接続済みのGoogleアカウントの配下に新しいGoogleの掲載情報を作成します。必要に応じてフォルダ内に作成できます。既存の掲載情報を関連付けるconnect-listingとは異なります。拠点には名前、住所、電話番号がすでに設定されている必要があり、1つの拠点に存在できるGoogleの掲載情報は1つだけです。

名前指定箇所必須補足
inputbodyはいラッパーオブジェクトです。
input.locationIdbodyはいBase64形式の拠点idです。
input.connectedAccountIdbodyはい掲載情報を作成するGoogleアカウントのUUIDです。
input.folderIdbodyいいえフォルダエンドポイントから取得したaccounts/{id}文字列です。アカウントのルートに作成する場合は省略してください。
Create GMB listing
curl -X POST https://listingsapi.com/api/v4/locations/create/gmb-listing \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",    "folderId": "accounts/104890024806530350198"  }}'
JSON
{  "data": {    "createGmbListingForLocation": {      "clientMutationId": null,      "success": true,      "errors": null    }  }}

作成は非同期で行われ、success: trueはリクエストが受理されたことを意味し、新しいプロフィールは公開前にGoogleの審査を受けます。successがfalseの場合、errorsに理由が示されます。理由には、必須フィールドの不足、既存のGoogleの掲載情報、アーカイブ済みの拠点、無効なアカウントがあります。

Google アカウント全体の接続を解除する

POST /connected-accounts/disconnect-google

アカウント全体の接続を解除します。そのアカウントを通じて接続されたすべての拠点で同期が停止します。locationIds フィールドはありません。アカウントを維持したまま1つの拠点の接続を解除するには、代わりに disconnect-listing を使用します。クライアントとの契約が終了した場合や、不具合のある認可を解消できず、新しい接続リンクでやり直す場合に使用します。

名前指定先必須補足
inputbodyはいラッパーオブジェクトです。
input.connectedAccountIdbodyはいGoogle アカウントの UUID です。アカウント全体の接続が解除されます。
Disconnect Google
curl -X POST https://listingsapi.com/api/v4/connected-accounts/disconnect-google \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "connectedAccountId": "d2397854-52c2-41d7-95f1-b90cba16498d" } }'
JSON
{  "data": {    "gmbBulkDisconnect": {      "success": true    }  }}

不明な connectedAccountId に対しても success: true が返されるため、これは「リクエストが処理された」ことを意味し、「有効な接続が削除された」ことを意味するものではありません。確実に確認するには、接続済みアカウントの一覧を再取得してください。

Facebook アカウント全体の接続を解除する

POST /connected-accounts/disconnect-facebook

同じリクエストボディを使用する、Facebook 向けの操作です。アカウントを通じて接続されたページの同期が停止し、Facebook でのインタラクションが表示されなくなります。

名前指定先必須補足
inputbodyはいラッパーオブジェクトです。
input.connectedAccountIdbodyはいFacebook アカウントの UUID です。アカウント全体の接続が解除されます。
Disconnect Facebook
curl -X POST https://listingsapi.com/api/v4/connected-accounts/disconnect-facebook \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "connectedAccountId": "d2397854-52c2-41d7-95f1-b90cba16498d" } }'
JSON
{  "data": {    "fbBulkDisconnect": {      "success": true    }  }}

レスポンスキーは fbBulkDisconnect です。Google と同様に、不明な id に対する success: true は、削除されたことではなく、処理されたことを意味します。

1つの拠点と掲載先の接続を解除する

POST /locations/oauth-disconnect

拠点単位の OAuth フローで接続解除を行う操作です。別のパスで提供される、disconnect-listing と同じ操作です。input のリクエストボディも、disconnectConnectedAccountsLocations レスポンスキーも同じです。連携コードで読みやすい方のパスを選んでください。

名前指定先必須補足
inputbodyはいラッパーオブジェクトです。
input.locationIdbodyはい対象となる1つの拠点の Base64 id です。
input.sitebodyいずれか1つGOOGLE、FACEBOOK、または APPLE です。providerId を送信しない場合は必須です。
input.providerIdbodyいずれか1つsite の代わりに指定する、掲載先独自のアカウント識別子です。
OAuth 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": "GOOGLE" } }'
JSON
{  "data": {    "disconnectConnectedAccountsLocations": {      "clientMutationId": null,      "success": true,      "errors": null    }  }}

同じ SY10056 と SY10057 のルールが適用され、この拠点を操作する権限のないキーを使用すると、SY90003 を含む 403 が返されます。接続を解除しても拠点とそのデータはそのまま残り、その掲載先への送信方向の同期のみが停止します。その後、正しい掲載情報を接続するには、所有者に接続 URL から再度手続きを行ってもらうか、マッチングと connect-listing を実行してください。

発生するエラー

不正な形式のリクエストや無効なキーに対しては、最上位の errors[] を含む 4xx が返され、その message はコードで始まります。書き込み操作では、success: false と、data.<operation> 内に理由を含む 200 が返される場合もあるため、すべての書き込み操作でレスポンスボディを確認してください。全一覧は エラーコード にあります。

コードまたはステータス意味対処方法
SY90016 (400)POST で Read キーが使用されました。Write キーを使用してください。
SY90003 (403)このキーには、この拠点の接続または接続解除を行う権限がありません。この拠点へのアクセス権を持つキーを使用してください。
SY10056 (200)接続解除リクエストで site も providerId も送信されていません。どちらか一方を送信してください。
SY10057 (200)この拠点には、そのサイトへの有効な接続がありません。削除する接続はありません。拠点の掲載情報を確認してください。
SY81067 (200)create-from-listing で connectedAccountListingId に対応する対象が見つかりませんでした。アカウントの掲載情報を再取得し、レコードの id を使用してください。
400, Variable "$input" ... was not providedリクエストボディが input でラップされていないか、必須フィールドがありません。リクエストボディを input の下にネストしてください。listingId ではなく connectedAccountListingId を使用してください。
400、無効な enumレコードの CONNECTED ステータスが、一覧取得の status フィルターにそのまま渡されました。Connected、NotConnected、または ConnectionIssue で絞り込んでください。
429レート制限を超えました。Retry-After に従って待機してください。レート制限 を参照してください。

次の手順