연결된 계정

Google, Facebook, Apple Business Connect 계정을 연결하고, 해당 계정의 등록 정보를 사업장과 연결하고, client.connected_accounts을 통해 계정 연결을 해제합니다.

연결된 계정의 모든 메서드는 client.connected_accounts에 있습니다. 연결된 계정은 플랫폼에 권한을 부여한 Google Business Profile, Facebook Pages 또는 Apple Business Connect 로그인 하나를 의미하며, connected_accounts.list에서 얻는 connectedAccountId로 식별합니다.

연결 방법은 2가지입니다. 일괄 연결 방식에서는 게시 플랫폼 계정 전체에 대한 권한을 부여한 다음 해당 계정의 등록 정보를 사업장과 매칭합니다. 단일 사업장 연결 방식에서는 사업장 하나에 대한 OAuth 링크 하나를 생성하며, 앱에서 매장을 하나씩 연결할 때 사용합니다. location_id를 받는 메서드는 숫자 또는 base64로 인코딩된 ID를 허용하며, 사업장 ID를 참조합니다.

매칭 절차

일괄 연결 후에는 게시 플랫폼의 등록 정보가 아직 사업장에 연결되지 않은 상태입니다. trigger_matches를 호출하여 매칭 작업을 대기열에 추가하고, requestMatchesStatus가 MATCH_COMPLETED이 될 때까지 details을 폴링한 다음, suggestions로 매칭 결과를 조회하고 confirm_matches로 원하는 항목을 확정합니다. trigger_matches를 건너뛰면 suggestions이 비어 있는 상태로 남습니다.

`connected_accounts.connect_google`

Google Business Profile 계정 전체에 대한 권한을 부여하는 URL을 생성합니다. 사용자를 이 URL로 이동시키면 사용자는 success_url 또는 error_url로 돌아옵니다. 링크는 24시간 동안 유효합니다.

Python

client.connected_accounts.connect_google(    success_url: str,    error_url: str,) -> APIObject

Python

link = client.connected_accounts.connect_google(  "https://app.example.com/onboarding/google/done",  "https://app.example.com/onboarding/google/retry",)print(link.url)

bulkConnectLinkForGoogle 객체를 반환합니다. url을 읽고 success와 errors을 확인합니다. 두 리디렉션 URL은 모두 절대 https URL이어야 합니다. Google 계정 연결을 참조합니다.

`connected_accounts.connect_facebook`

connect_google와 동일하며 Facebook Pages 계정에 사용합니다. 24시간 동안 유효합니다.

Python

client.connected_accounts.connect_facebook(    success_url: str,    error_url: str,) -> APIObject

Python

link = client.connected_accounts.connect_facebook(  "https://app.example.com/onboarding/facebook/done",  "https://app.example.com/onboarding/facebook/retry",)print(link.url)

동일한 url, success, errors 필드가 포함된 bulkConnectLinkForFacebook 객체를 반환합니다. Facebook 계정 연결을 참조합니다.

`connected_accounts.oauth_url`

게시 플랫폼 프로필 하나를 사업장 하나에 연결하는 URL을 생성합니다. 사용자가 연결할 사업장을 이미 알고 있어 매칭 단계가 필요하지 않을 때 사용합니다. 24시간 동안 유효합니다.

Python

client.connected_accounts.oauth_url(    location_id: str | int,    site: str,    success_url: str,    error_url: str,) -> APIObject

매개변수	유형	설명
`location_id`	`str \| int`	프로필을 연결할 사업장의 숫자 또는 base64 ID입니다.
`site`	`str`	`GOOGLE`, `FACEBOOK` 또는 `APPLE`입니다. SDK는 전송하기 전에 이 값을 대문자로 변환합니다.
`success_url`	`str`	성공 시 사용자가 돌아올 절대 https URL입니다.
`error_url`	`str`	실패 시 사용자가 돌아올 절대 https URL입니다.

Python

link = client.connected_accounts.oauth_url(  16808,  site="google",  success_url="https://app.example.com/locations/16808?connected=1",  error_url="https://app.example.com/locations/16808?connected=0",)print(link.url)

createConnectUrl 객체를 반환합니다. 리디렉션 URL이 상대 URL이거나 파싱할 수 없는 경우 null url이 포함된 success: true로 반환되므로, success만 확인하지 말고 url 자체를 확인합니다. 링크는 1회용이므로 시도할 때마다 새로 생성합니다. 사업장 하나의 OAuth 연결 URL 생성을 참조합니다.

`connected_accounts.list`

현재 계정에 연결된 Google 및 Facebook 계정 목록을 조회합니다. 이후 모든 호출에 필요한 connectedAccountId를 여기서 얻습니다.

Python

client.connected_accounts.list(    *,    publisher: str | None = None,    status: str | None = None,    page: int | None = None,    per_page: int | None = None,) -> APIObject

매개변수	유형	설명
`publisher`	`str`	게시 플랫폼 하나의 계정만 조회합니다.
`status`	`str`	`CONNECTED`와 같은 특정 연결 상태의 계정만 조회합니다.
`page`	`int`	1부터 시작하는 페이지 번호입니다.
`per_page`	`int`	페이지 크기입니다. `perPage`로 전송됩니다.

Python

accounts = client.connected_accounts.list(status="CONNECTED", per_page=50)for account in accounts.records:  print(account.connectedAccountId, account.email, account.connectedLocationsCount)print(accounts.pageInfo.totalRecords)

records과 함께 hasNextPage, totalPages, totalRecords가 포함된 pageInfo를 담은 connectedAccountsInfo 객체를 반환합니다. 정렬 순서는 계정 이메일 기준 오름차순으로 고정됩니다. 연결된 계정 목록 조회를 참조합니다.

`connected_accounts.details`

ID로 연결된 계정 하나를 조회합니다. trigger_matches 이후 이 메서드를 폴링하여 requestMatchesStatus이 MATCH_COMPLETED가 될 때까지 기다립니다.

Python

client.connected_accounts.details(connected_account_id: str) -> APIObject

Python

account = client.connected_accounts.details("4f712c17-4f95-42dd-90f4-97171a2e67b5")print(account.details.get("status"))print(account.details.get("requestMatchesStatus"))

connectedAccountDetails 객체를 반환합니다. details 아래에 status, connectedAccountType, connectedLocationsCount, connectivityIssue, requestMatchesStatus, lastFetchMatchesRequestedAt 필드가 있습니다. connectivityIssue이 null이 아니면 게시 플랫폼 토큰에 대한 권한을 다시 부여해야 한다는 의미입니다. 연결된 계정 세부 정보 조회를 참조합니다.

`connected_accounts.listings`

사업장과의 매칭 여부에 관계없이 연결된 계정이 접근할 수 있는 게시 플랫폼 등록 정보 목록을 조회합니다. 확보한 접근 권한의 범위를 사용자에게 보여줄 때 사용합니다.

Python

client.connected_accounts.listings(    connected_account_id: str,    *,    location_info: str | None = None,    page: int | None = None,    per_page: int | None = None,) -> APIObject

매개변수	유형	설명
`connected_account_id`	`str`	등록 정보를 조회할 연결된 계정입니다.
`location_info`	`str`	등록 정보의 이름과 주소에 적용하는 자유 텍스트 필터입니다.
`page`	`int`	1부터 시작하는 페이지 번호입니다.
`per_page`	`int`	페이지 크기입니다. `perPage`로 전송됩니다.

Python

page = client.connected_accounts.listings(  "4f712c17-4f95-42dd-90f4-97171a2e67b5",  location_info="Manhattan",  per_page=25,)for listing in page.records:  print(listing.locationName, listing.address, listing.accountTypeName)

이 엔드포인트는 POST를 사용하며 모든 인수를 쿼리 문자열이 아닌 요청 본문으로 받습니다. SDK가 해당 본문을 구성합니다. records와 pageInfo이 포함된 connectedAccountListings 객체를 반환합니다. 각 레코드에는 id, locationName, address, phone, accountTypeName, liveLink가 포함됩니다. 연결된 계정의 등록 정보 조회를 참조합니다.

`connected_accounts.trigger_matches`

지정된 계정이 접근할 수 있는 모든 프로필을 가져와 사업장과 매칭하는 작업을 대기열에 추가합니다. 일괄 연결 직후에 실행하고, 사업장을 추가한 후 다시 실행합니다.

Python

client.connected_accounts.trigger_matches(    connected_account_ids: list[str],) -> APIObject

Python

result = client.connected_accounts.trigger_matches(  ["4f712c17-4f95-42dd-90f4-97171a2e67b5"],)print(result.success, result.failedIds)

success과 failedIds가 포함된 connectedAccountsTriggerMatches 객체를 반환합니다. 작업은 비동기로 실행되므로 success: true은 완료가 아니라 대기열에 추가되었다는 의미입니다. 추천 항목을 조회하기 전에 requestMatchesStatus가 MATCH_COMPLETED이 될 때까지 details를 폴링합니다. 매칭 실행을 참조합니다.

`connected_accounts.suggestions`

매칭 작업이 찾은 계정의 등록 정보와 사업장 간의 매칭 결과를 조회합니다. 확정하기 전에 사용자가 검토할 수 있도록 결과를 표시합니다.

Python

client.connected_accounts.suggestions(    connected_account_id: str,    *,    page: int | None = None,    per_page: int | None = None,) -> APIObject

Python

page = client.connected_accounts.suggestions(  "4f712c17-4f95-42dd-90f4-97171a2e67b5",  per_page=50,)for match in page.records:  print(match.locationId, match.accountType, match.matchedDataDatabaseId)

records과 pageInfo가 포함된 connectionSuggestionsForAccount 객체를 반환합니다. 각 레코드에는 locationId, accountType, matchedDataDatabaseId, locationInfo, suggestedLocationInfo이 포함됩니다. totalRecords: 0와 함께 records이 비어 있으면 일반적으로 매칭 작업이 아직 실행되지 않았다는 의미입니다. 연결 추천 목록 조회를 참조합니다.

`connected_accounts.confirm_matches`

추천된 매칭을 확정합니다. 확정되면 게시 플랫폼의 등록 정보가 매칭된 사업장과 동기화되기 시작합니다.

Python

client.connected_accounts.confirm_matches(    match_record_ids: list[str],) -> APIObject

Python

result = client.connected_accounts.confirm_matches([  "R21iTG9jYXRpb25NYXRjaGVkRGF0YTowZDVlMzA2Zi0wZGEwLTQ2ZTMtOTI5Zi1mZDNjNjdjY2Q4Y2M=",])print(result.success, result.failedIds)

success과 failedIds가 포함된 confirmConnectMatches 객체를 반환합니다. 추천 레코드에는 자체 id가 없으므로 매칭 확정에 설명된 대로 레코드의 matchedDataDatabaseId와 accountType로 각 매칭 레코드 ID를 구성합니다.

`connected_accounts.folders`

연결된 Google 계정이 접근할 수 있는 폴더(Google에서는 계정 그룹이라고 합니다) 목록을 조회합니다. Google 등록 정보를 생성할 때 선택한 folderId를 전달하여 올바른 폴더에 생성되도록 합니다.

Python

client.connected_accounts.folders(    connected_account_id: str,    *,    folder_name: str | None = None,) -> list[APIObject]

Python

folders = client.connected_accounts.folders(  "4f712c17-4f95-42dd-90f4-97171a2e67b5",)for folder in folders:  print(folder.folderId, folder.folderName, folder.locationCount)

getFoldersUnderGoogleAccount 목록을 반환합니다. 각 항목에는 folderId(변경 없이 사용하는 accounts/{id} 문자열), folderName, locationCount가 포함되며, Google이 개수를 제공하지 않으면 마지막 필드의 값은 null입니다. Google 유형 계정에만 사용할 수 있습니다. 폴더 목록 조회 및 listings.create_gmb를 참조합니다.

`connected_accounts.disconnect_google`

Google 계정 전체의 연결을 해제합니다. 해당 계정을 통해 매칭된 모든 사업장의 Google 동기화가 중지됩니다.

Python

client.connected_accounts.disconnect_google(    connected_account_id: str,) -> APIObject

Python

result = client.connected_accounts.disconnect_google(  "4f712c17-4f95-42dd-90f4-97171a2e67b5",)print(result.success)

success이 포함된 gmbBulkDisconnect 객체를 반환합니다. Google 계정 연결 해제를 참조합니다.

`connected_accounts.disconnect_facebook`

Facebook Pages 계정 전체의 연결을 해제합니다.

Python

client.connected_accounts.disconnect_facebook(    connected_account_id: str,) -> APIObject

Python

result = client.connected_accounts.disconnect_facebook(  "9a41b8c0-7d2e-4c15-9f63-2b8e5ad71f04",)print(result.success)

success이 포함된 fbBulkDisconnect 객체를 반환합니다. Facebook 계정 연결 해제를 참조합니다.

`connected_accounts.oauth_disconnect`

사업장 하나와 게시 플랫폼 하나의 연결을 해제하고 계정의 나머지 연결은 유지합니다. 이는 oauth_url에 대응하는 연결 해제 작업입니다.

Python

client.connected_accounts.oauth_disconnect(    location_id: str | int,    site: str,) -> APIObject

site는 GOOGLE, FACEBOOK 또는 APPLE이며, SDK는 전송하기 전에 이 값을 대문자로 변환합니다.

Python

client.connected_accounts.oauth_disconnect(16808, site="google")

success과 errors가 포함된 disconnectConnectedAccountsLocations 객체를 반환합니다. 사업장 하나와 게시 플랫폼의 연결 해제를 참조합니다.