사업장의 새 Google Business Profile

연결된 Google 계정 아래의 사업장에 새 Google Business Profile 생성 요청을 제출한 다음, 해당 사업장, 등록 정보, 웹훅을 통해 인증 진행 상황을 확인합니다.

일치 항목 찾기와 연결은 Google 등록 정보가 이미 있을 때만 가능합니다. 새 매장에는 Google 등록 정보가 없으므로 연결된 Google 계정 아래에 등록 정보를 생성하도록 API에 요청합니다. 생성은 비동기적으로 진행되고 Google은 자체 일정에 따라 프로필을 인증하므로, 이 가이드에서는 주로 결과를 확인하는 방법을 다룹니다.

1. 사업장에 Google 등록 정보가 없는지 확인하기

사업장의 프리미엄 등록 정보를 조회하고 site.name이 Google Maps인 행을 찾습니다. Google에 등록되지 않은 사업장은 connectedAccountId가 null이고 REQUIRING_ACTION으로 표시됩니다.

Google row

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

JSON

{  "site": { "name": "Google Maps", "url": "maps.google.com" },  "syncStatus": "REQUIRING_ACTION",  "displayStatus": "Connect your account to sync the listing",  "listingUrl": null,  "connectedAccountId": null,  "verified": false}

행이 이미 SYNCED이거나 connectedAccountId가 설정되어 있다면, 해당 사업장에는 Google 등록 정보가 있으므로 이 가이드는 적용되지 않습니다. 대신 기존 등록 정보를 연결하거나 업데이트합니다.

2. 폴더 선택하기(선택 사항)

Google은 계정 내 등록 정보를 계정 그룹이라고도 하는 폴더로 정리합니다. 소유자가 새 프로필을 특정 그룹에 넣으려는 경우, 연결된 계정의 폴더 목록을 조회하고 그중 하나를 folderId로 전달합니다. 계정 루트에 생성하려면 이 단계를 건너뜁니다.

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일 수 있습니다. 이 엔드포인트는 GoogleAccount 연결에만 유효합니다.

3. 등록 정보 생성하기

사업장의 base64 id와 계정을 보내고, 폴더를 선택했다면 함께 보냅니다. 응답은 요청이 접수되었다는 사실만 나타냅니다.

Create 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 등록 정보가 있거나, 사업장이 보관 처리되었거나, 연결된 계정이 더 이상 활성 상태가 아닌 경우입니다.

4. 사업장의 인증 상태 확인하기

사업장을 조회할 때마다 status와 message가 포함된 googleVerificationStatus가 반환됩니다. 사업장을 다시 조회하여 Google의 처리가 어느 단계에 있는지 확인합니다.

Verification status

curl -G https://listingsapi.com/api/v4/locations-by-ids \--data-urlencode 'ids=["TG9jYXRpb246MTgwMDI4OQ=="]' \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "id": "TG9jYXRpb246MTgwMDI4OQ==",  "databaseId": 1800289,  "googleVerificationStatus": { "status": "PENDING_VERIFICATION", "message": null }}

`status`	의미	종료 상태 여부
`NOT_CONNECTED`	아직 Google 등록 정보가 연결되지 않았습니다. 3단계가 반영되기 전에는 이 상태가 표시될 수 있습니다.	아니요
`NOT_VERIFIED`	등록 정보가 존재하며, 인증은 아직 시작되지 않았습니다.	아니요
`PENDING_VERIFICATION`	Google이 프로필을 인증하고 있습니다.	아니요
`UNDER_REVIEW`	Google이 프로필을 검토하고 있습니다.	아니요
`VERIFIED`	프로필이 게시되었습니다.	예
`SUSPENDED`	Google이 프로필을 정지했습니다.	예
`DUPLICATE`	Google이 기존 프로필과 중복된다고 판단했습니다.	예
`ERROR_WHILE_FETCHING`	Google에서 상태를 읽을 수 없었습니다. 나중에 다시 시도합니다.	예

며칠이 걸리는 과정이므로 하루에 1번 조회하면 충분합니다. 여러 사업장을 한꺼번에 확인하다가 429가 반환되면 Retry-After를 따릅니다.

5. 등록 정보에서 Google 행 확인하기

1단계의 프리미엄 등록 정보 행은 등록 정보 측에서 동일한 진행 상황을 추적합니다. 1단계의 호출을 다시 실행하고 syncStatus, verified, listingUrl을 확인합니다.

`syncStatus`	의미
`REQUIRING_ACTION`	아직 아무것도 생성되지 않았거나 계정에 조치가 필요합니다. `displayStatus`를 확인합니다.
`IN_PROGRESS`	Google에 제출되었으며 응답을 기다리고 있습니다.
`PENDING_APPROVAL`	Google의 승인을 기다리고 있습니다.
`SYNCED`	게시되었습니다. `listingUrl`에 값이 채워지고 `connectedAccountId`로 해당 계정을 확인할 수 있습니다.
`FAILED`	Google이 제출을 거부했습니다. `syncIssue`에 그 이유가 표시됩니다.

6. 인증 웹훅 수신하기

대시보드에 웹훅 URL이 설정되어 있으면 최종 상태는 2개의 이벤트로 전달되므로 폴링할 필요가 없습니다. 두 이벤트 모두 location_id가 있으며, 항상 data.connected_account_id: null이 들어 있습니다.

이벤트	발생 조건	`data` 필드
`connection.google_verification_verified`	프로필이 `VERIFIED` 상태에 도달하면 발생합니다.	`platform: "google"`
`connection.google_verification_failed`	프로필이 `SUSPENDED`, `DUPLICATE`(`failure_type: "rejected"`) 또는 `ERROR_WHILE_FETCHING`(`failure_type: "transient"`) 상태에 도달하면 발생합니다.	`platform`, `failure_type`, `reason`

JSON

{  "event": "connection.google_verification_failed",  "timestamp": "2026-08-25T14:52:31Z",  "account_id": 11073,  "location_id": "279381",  "data": { "platform": "google", "connected_account_id": null, "failure_type": "rejected", "reason": "This profile is suspended." }}

transient 실패만 재시도할 가치가 있습니다. 진행 중인 상태에서는 이벤트가 전혀 발생하지 않으므로 이벤트가 없다는 것만으로는 상태를 판단할 수 없습니다. 인증이 진행 중일 때는 4단계에서와 같이 googleVerificationStatus를 조회합니다.

다음 단계

Google 연결 및 사업장 가져오기: 이 가이드의 전제 조건인 계정을 연결합니다.
등록 정보 상태 및 라이브 링크 확인: 모든 게시 플랫폼 행을 더 폭넓게 살펴봅니다.
웹훅으로 이벤트에 대응하기: 폴링하는 대신 인증 이벤트를 수신합니다.
참고: 사업장의 GMB 등록 정보 생성, GMB 폴더 목록 조회, 프리미엄 등록 정보 조회, 사업장 목록 조회.