Listings APIListings API
로그인

등록 정보 오류 찾기 및 수정

사업장의 등록 정보에서 주의가 필요한 행만 필터링하고, 게시 플랫폼이 제공한 사유를 확인한 뒤, 해당하는 수정 조치를 적용하고, 안전하게 다시 폴링하고, 계정 전체를 점검합니다.

대부분의 등록 정보는 별도의 조치 없이 동기화됩니다. 동기화되지 않는 등록 정보는 displayStatus와 syncIssue에 그 이유가 표시되며, 거의 모든 원인에 5가지 수정 방법 중 하나를 적용할 수 있습니다. 이 가이드에서는 원본 등록 정보 행을 확인하는 단계부터 차단된 항목과 필요한 조치를 정리한 계정별 보고서를 작성하는 단계까지 설명합니다.

1. 등록 정보를 가져와 문제가 있는 행만 남기기

프리미엄 등록 정보를 가져와 정상인 행을 모두 제외합니다. actionRequired가 true이거나 syncStatus가 FAILED, CANNOT_SUBMIT 또는 REQUIRING_ACTION인 행은 주의가 필요합니다. IN_PROGRESS와 PENDING_APPROVAL은 오류가 아니라 게시 플랫폼의 대기열에 있음을 나타냅니다.

Problem rows
curl -s https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '[.data.listingsForLocation[]       | select(.actionRequired                or (.syncStatus | IN("FAILED", "CANNOT_SUBMIT", "REQUIRING_ACTION")))]'
JSON
{  "data": {    "listingsForLocation": [      {        "site": { "name": "Google Maps", "url": "maps.google.com" },        "syncStatus": "REQUIRING_ACTION",        "displayStatus": "Connect your account to sync the listing",        "actionRequired": true,        "syncIssue": null      },      {        "site": { "name": "Local Mint", "url": "localmint.com" },        "syncStatus": "FAILED",        "displayStatus": "Partner experiencing issues; awaiting response",        "actionRequired": false,        "syncIssue": "Publisher requires website URL"      }    ]  }}

2. 사유 확인

2개의 필드가 문제가 있는 행을 설명합니다. displayStatus는 플랫폼이 해당 행의 현재 상태를 요약한 내용입니다. syncIssue는 게시 플랫폼이 사유를 제공한 경우 표시되는 해당 게시 플랫폼의 사유입니다. 둘 다 확인합니다. 위 예시에서 Local Mint의 displayStatus는 파트너에게 문제가 있다고 설명하지만, syncIssue는 웹사이트 누락이라는 실제 원인을 알려 줍니다.

필드예시용도
displayStatusConnect your account to sync the listing사람에게 보여 줄 설명입니다.
syncIssuePublisher requires website URL수정 방법을 선택하는 데 사용합니다. 게시 플랫폼이 사유를 제공하지 않았으면 null입니다.
actionRequiredtrue분류에 사용합니다. true는 조치를 취하기 전까지 아무것도 진행되지 않음을 의미합니다.

모든 사업장 조회에서 읽을 때마다 사업장 자체에도 createErrors 배열이 포함됩니다. 이 배열에는 레코드를 생성할 때 발견된 유효성 검사 문제가 들어 있으며, syncIssue 없이 행이 실패할 때 추가로 확인할 수 있는 곳입니다.

3. 원인에 맞는 수정 방법 찾기

거의 모든 차단된 행은 몇 가지 원인에서 비롯됩니다.

원인표시 방식수정 방법
계정이 연결되지 않음Google Maps 또는 Facebook이 REQUIRING_ACTION 상태이며 Connect your account to sync the listing이 표시됩니다.해당 게시 플랫폼의 계정을 연결합니다. Google 연결 및 사업장 가져오기 또는 Facebook 페이지 연결을 참고합니다. Apple Maps는 연결이 필요하지 않습니다. Apple Business Connect 연결을 참고합니다.
웹사이트 누락FAILED 상태이며 syncIssue: Publisher requires website URL이 표시됩니다.사업장에 bizUrl을 설정합니다. 사업장 업데이트를 참고합니다.
게시 플랫폼에서 지원하지 않는 국가CANNOT_SUBMIT 상태이며 syncIssue는 없습니다.사업장의 countryIso를 요금제 사이트 목록 조회에서 가져온 해당 사이트의 supportedCountries와 비교합니다. 수정할 사항은 없습니다. 해당 게시 플랫폼은 이 등록 정보를 받지 않습니다.
주소 숨김을 지원하지 않음hideAddress: true가 설정된 서비스 지역 비즈니스에 CANNOT_SUBMIT 또는 FAILED가 표시됩니다.사이트의 hideAddressSupportedCountries를 확인합니다. 주소를 표시하거나 해당 게시 플랫폼이 제외되는 것을 수용합니다.
Facebook 페이지에 영업시간이 없음Facebook이 IN_PROGRESS 상태이며 syncIssue: Temporary status is not applicable for this listing because it has no hours or opening information이 표시됩니다.Facebook에서 페이지에 영업시간을 추가한 다음 사업장 업데이트를 전송합니다. 사업장 업데이트를 참고합니다.
설명 또는 카테고리가 거부됨FAILED 상태이며 syncIssue에 해당 필드가 명시됩니다.사업장의 설명 또는 subCategoryId를 업데이트한 다음 다시 폴링합니다.

국가 및 주소 숨김 규칙을 확인하려면 요금제 사이트 목록을 한 번 가져와 캐시합니다. 이 목록은 페이지로 나뉘지 않으며 거의 변경되지 않습니다.

Plan sites
curl -s https://listingsapi.com/api/v4/plan-sites \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.planSites[] | select(.name == "Yelp")      | {name, supportedCountries, hideAddressSupportedCountries}'
JSON
{  "name": "Yelp",  "supportedCountries": ["US", "CA", "GB", "DE", "FR"],  "hideAddressSupportedCountries": ["US", "CA", "AU", "GB"]}

사업장의 countryIso가 supportedCountries에 없으면 해당 게시 플랫폼의 행은 CANNOT_SUBMIT 상태에서 절대 벗어나지 않습니다. 재시도하는 대신 등록 범위 수치에서 제외합니다.

4. 수정 후 다시 폴링

사업장을 업데이트하면 영향을 받는 게시 플랫폼에 새로 제출됩니다. 행은 FAILED 또는 REQUIRING_ACTION에서 다시 IN_PROGRESS로 이동한 다음, 게시 플랫폼이 수락하면 SYNCED로 이동합니다. 게시 플랫폼의 처리에는 몇 분에서 몇 주까지 걸리므로, 초 단위가 아닌 시간 단위의 일정으로 폴링합니다.

모든 폴링은 요청 빈도 제한에 산입됩니다. 429가 발생하면 Retry-After를 읽고 해당 초 수만큼 기다립니다. SDK는 동일한 값을 포함한 RateLimitError를 발생시킵니다.

Re-poll
# -D - prints response headers so you can see Retry-After on a 429curl -s -D - https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY" \| grep -i -E "^HTTP|^Retry-After"

lastUpdate가 더 최신 값으로 갱신되는 것은 syncStatus가 변경되기 전이라도 게시 플랫폼이 새 제출을 처리했다는 신호입니다. 웹훅을 사용한다면 listing.submission 이벤트가 이 반복 처리를 대체합니다.

5. 계정 전체 점검 실행

계정 전체에서 차단된 모든 행을 찾으려면 GET /locations(커서 기반 커넥션: first, after, edges[].node)의 페이지를 순회하고 사업장마다 프리미엄 엔드포인트를 1번 호출합니다. 문제가 있는 행을 사업장을 키로 하는 하나의 보고서로 모읍니다. Python SDK는 auto_paging_iter()로 커서를 따라가며, Node SDK는 fetchAll: true로 같은 작업을 수행합니다. 예제에서는 4단계의 백오프 헬퍼를 재사용합니다.

Account sweep
# One page of locations, then one listings call per location.# Repeat with &after=<pageInfo.endCursor> while hasNextPage is true.curl -s "https://listingsapi.com/api/v4/locations?first=50" \-H "Authorization: API $LISTINGSAPI_KEY" \| jq -r '.data.allLocations.edges[].node.id' \| while read -r id; do    curl -s "https://listingsapi.com/api/v4/locations/$id/listings/premium" \      -H "Authorization: API $LISTINGSAPI_KEY" \      | jq --arg id "$id" '[.data.listingsForLocation[]           | select(.syncStatus != "SYNCED" and .syncStatus != "COMPLETED")           | {location: $id, site: .site.name, status: .syncStatus, issue: .syncIssue}]'    sleep 6   # stay under 10 requests a minute on Launch  done

이 보고서는 아직 처리 중인 행과 실제로 차단된 행을 함께 묶습니다. 다른 사람에게 전달하기 전에 3단계의 표에 따라 분류합니다. IN_PROGRESS와 PENDING_APPROVAL은 기다려야 하고, REQUIRING_ACTION은 연결이 필요하며, FAILED는 사업장에 필드가 필요합니다.

다음 단계