구글 판매자 센터 API 제품 상태·이슈·리포트 쉽고 빠른 쇼핑 데이터 자동화

Google Merchant Center API 활용법: 제품 입력, 품질 관리, 이슈 진단, MCQL 분석 모니터링까지 통합하여 한 번에 끝낼 수 있습니다. 아래 내용은 Google Merchant API(v1)를 이용해 “제품 등록”, “처리 결과/상태 조회”, “계정/제품 이슈 진단”, “리포트(MCQL) 조회”까지 운영 가능한 흐름으로 정리합니다. 각 단계별 실행 예시(cURL/요청 본문)와 보안/운영 체크리스트도 함께 제공합니다.

참고: Merchant API는 Content API for Shopping의 공식 후속이며, v1이 GA입니다. 신규/개편 기능은 Merchant API 기준으로 확인하세요. (Google for Developers)

큰 그림 — 무엇이 어떻게 바뀌었나?

제품 등록/수정 경로
- Data sources(API형) 를 먼저 만들고 → productInputs:insert 로 “원천 입력(입력값)”을 올립니다.
- Google이 규칙/보조 데이터 소스를 적용해 처리된 제품(accounts.products) 을 생성합니다. 처리된 제품은 쇼핑광고/무료등록 등 실제 노출 기준이 됩니다.
상태/이슈 조회의 분리
- 제품 단건/목록 상태: accounts.products.list (처리 완료된 제품, 목적지별 승인/거절·품질 이슈 확인)
- 집계 현황(요약): accounts.aggregateProductStatuses.list (국가/목적지별 승인/경고/거절 집계)
- 계정 차원의 이슈: accounts.issues.list (예: 전화번호 미인증, 랜딩페이지 오류 등 운영을 막는 중대 이슈)
리포트/분석(MCQL)
- Reports API + MCQL 로 성과/시장/경쟁 분석 쿼리(SELECT…FROM…WHERE…) 수행. (예: 상품 성과, 트래픽/전환 등)

사전 준비 (계정, 권한, 인증)

API 접근 검증(빠른 확인)
- API Explorer에서 accounts.products.list 를 실행해 200 OK 확인(신규 계정은 빈 리스트일 수 있음).
인증 방식
- 사내(자계정)만 접근: Service Account 사용 → 서비스 계정을 Merchant Center 사용자로 추가(권한: Admin 권장). 액세스 토큰은 1시간 유효.
- 대행사/3rd-party 앱: OAuth 2.0 승인 + 검증 (앱 검증 3~5영업일, scope는 https://www.googleapis.com/auth/content)
쿼터·업데이트 정책(중요)
- 제품 업데이트: 1일 최대 2회, 하위계정 업데이트: 1일 1회 정책 준수.
- quotas.list로 현재 사용량/상한 확인. 과다 호출 시 quota/request_rate_too_high, quota/daily_limit_exceeded 오류.

데이터 소스 만들기 (API형)

제품 입력을 받는 기반 구조입니다. 최소 1개의 API 타입의 기본(Primary) 제품 데이터 소스가 필요합니다. (UI로도 가능)

1. API로 Primary 데이터 소스 생성 (개념)

엔드포인트: accounts.dataSources.create
핵심 개념
- contentLanguage(예: ko), feedLabel(예: KR) 조합으로 피드 라우팅
- Primary/ Supplemental 제품 데이터 소스를 구분
참고: 상세 필드/스키마는 DataSource 레퍼런스 확인.

300x250

2. (예시) cURL 스켈레톤

# 액세스 토큰 준비 후 실행 (OAuth2 or SA)
ACCOUNT_ID="1234567890"
curl -sS -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "https://merchantapi.googleapis.com/datasources/v1/accounts/$ACCOUNT_ID/dataSources" \
  -d '{
    "displayName": "API Primary – KR",
    "productContentType": "PRIMARY",
    "dataSourceType": "API",
    "contentLanguage": "ko",
    "feedLabel": "KR"
  }'

⚠️ 위 본문은 필드 이름의 개념 예시입니다. 실제 요청은 DataSource 스키마에 맞춰 보내세요. (공식 레퍼런스 및 “API 데이터 소스 관리” 가이드 참고)

제품 등록 (productInputs:insert)

입력(product input) 을 올리면 Google이 규칙/보조 소스를 적용해 처리된 제품을 만듭니다. 등록·수정 후 완전 반영까지 수 분 걸릴 수 있습니다.

1. 요청 포인트

엔드포인트

POST https://merchantapi.googleapis.com/products/v1/accounts/{ACCOUNT_ID}/productInputs:insert?dataSource=accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}

주요 필드(요지)
- offerId: 내부 SKU(업서트 키로 사용)
- channel: "ONLINE"
- contentLanguage: "ko"
- feedLabel: "KR"
- attributes: title, description, link, imageLink, availability, price, brand, condition, gtins 등(제품 데이터 사양에 맞춤)
  (※ 정확한 속성은 제품 데이터 사양/레퍼런스에 따릅니다.)

2. (예시) cURL

ACCOUNT_ID="1234567890"
DATASOURCE_ID="api-primary-kr"

curl -sS -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "https://merchantapi.googleapis.com/products/v1/accounts/$ACCOUNT_ID/productInputs:insert?dataSource=accounts/$ACCOUNT_ID/dataSources/$DATASOURCE_ID" \
  -d '{
    "offerId": "SKU-12345",
    "channel": "ONLINE",
    "contentLanguage": "ko",
    "feedLabel": "KR",
    "attributes": {
      "title": "테스트 상품",
      "description": "설명...",
      "link": "https://shop.example.com/products/sku-12345",
      "imageLink": "https://cdn.example.com/images/sku-12345.jpg",
      "availability": "in_stock",
      "price": {"amount": "19900", "currency": "KRW"},
      "brand": "Pages in Korea",
      "condition": "new",
      "gtins": ["8801234567890"]
    }
  }'

팁: 업데이트 정책(1일 2회) 준수를 위해, 대량 변경은 배치 윈도우를 잡아 한 번에 처리하세요.

처리된 제품 & 품질 이슈 조회 (Products)

1. 처리된 제품 나열

엔드포인트: accounts.products.list
응답에는 목적지별 승인/제한 상태(예: Shopping Ads, 무료 노출) 및 item-level issues가 포함됩니다.

ACCOUNT_ID="1234567890"
curl -sS -X GET \
  -H "Authorization: Bearer $TOKEN" \
  "https://merchantapi.googleapis.com/products/v1beta/accounts/$ACCOUNT_ID/products?pageSize=100"

2. “제품 데이터 & 제품 문제” 가이드 (권장 흐름)

Products + Reports를 조합해 승인 가능성, 품질 이슈를 체계적으로 수집/진단합니다.

제품 상태 요약(집계) — 대시보드용 핵심 KPI

목표: 국가·목적지별 승인/경고/거절 집계 수치로 재고/승인 건강도를 한눈에 모니터링
엔드포인트: accounts.aggregateProductStatuses.list (issueresolution API)

ACCOUNT_ID="1234567890"
curl -sS -X GET \
  -H "Authorization: Bearer $TOKEN" \
  "https://merchantapi.googleapis.com/issueresolution/v1/accounts/$ACCOUNT_ID/aggregateProductStatuses?pageSize=100"
# 필요 시 보고 컨텍스트/국가 필터 쿼리 파라미터 사용 (문서 예시 참조)

계정 이슈 조회 — 운영 차단 요인 조기 탐지

엔드포인트: accounts.issues.list
응답: title, severity, impactedDestinations, detail, documentationUri 등 포함(현지화 가능: language_code, time_zone.id)

ACCOUNT_ID="1234567890"
curl -sS -X GET \
  -H "Authorization: Bearer $TOKEN" \
  "https://merchantapi.googleapis.com/accounts/v1/accounts/$ACCOUNT_ID/issues?language_code=ko-KR&time_zone.id=Asia/Seoul&page_size=100"

리포트 & MCQL(고급 분석)

Reports API 에 MCQL(SQL 유사 문법)로 성과/시장/경쟁 데이터를 질의합니다.
- 예시 문법
```
SELECT offer_id, impressions, clicks
FROM product_performance_view
WHERE date DURING LAST_30_DAYS
ORDER BY clicks DESC
LIMIT 100
```
- 문법/연산자/기간지정(THIS_MONTH, LAST_7_DAYS 등) 규칙은 MCQL 가이드 참고.
시작 가이드 및 사용 패턴은 Reports “Get started” 참고. (요청은 reports.search 로 MCQL 쿼리 제출)

운영 아키텍처 예시 (실무형)

업로드 파이프라인
- ERP/PIM → (정합성 검사) → productInputs:insert(증분 업서트) → 처리 지연 감안하여 N분 후 상태 조회
상태/이슈 모니터링
- accounts.aggregateProductStatuses.list 로 매일 오전 집계 추이 (국가/목적지별 승인률)
- accounts.issues.list 로 CRITICAL 이슈 슬랙 알림 (문서 링크로 즉시 조치)
성과 분석
- MCQL 로 주간 Top/Bottom 상품, 브랜드별 성과, 유입 채널 분석 리포트 자동 배포
쿼터/정책 준수
- 대량 변경은 하루 1~2회 배치로 묶고, 실패 시 지수백오프 재시도 + quotas.list 주기 점검

보안 점검 포인트

인증/권한
- 사내용은 Service Account + Merchant Center Admin 권한(UI의 People and access)만 부여. 키는 KMS/HSM으로 보호, 로테이션 정책 수립.
- 대행사용/고객계정 접근은 OAuth 2.0 + 앱 검증(3~5일), 범위 최소화(https://www.googleapis.com/auth/content). 토큰 저장소는 암호화/권한분리.
API 사용 정책/감사
- 업데이트 정책(제품 1일 2회, 서브계정 1일 1회) 준수 모니터링. 초과 시 원인/재발방지 기록. quota/* 에러 수집·경보 설정.
데이터 품질/무결성
- offerId 불변 원칙(업서트 키)과 contentLanguage/feedLabel 분리로 스테이징/프로덕션 혼선 방지.
- 제품 속성(가격/통화/가용성/링크/이미지) 정합성 검사 → 오류는 item-level issue로 측정/개선 루프 운용.
개인정보/규정 준수
- 제품 피드에 PII/민감정보 금지, 랜딩 URL은 TLS, 가이드된 쇼핑 정책 준수(거절 대응 프로세스 문서화).
비상대응
- CRITICAL 계정 이슈 발생 시 즉시 차단 임계치(알림 → 담당자 호출)와 롤백 시나리오(직전 정상 버전 재적용) 준비.

오류/트러블슈팅 포인트

429/quota/request_rate_too_high: 호출 속도 초과 → 지수 백오프 + 배치 간격 조정.
quota/daily_limit_exceeded: 일일 한도 초과 → 호출 계획 조정, 필요 시 상향 요청(계정/방법/사유 제출).
승인 거절/품질 이슈: accounts.products.list 의 item-level issues 및 accounts.aggregateProductStatuses.list 의 요약치 교차 확인 → 문서 링크(documentationUri) 따라 조치.
계정 이슈: accounts.issues.list 로 상세 원인/영향 목적지/해결 가이드 확보(로케일/타임존 지정 가능).

빠른 스타트 예시 모음

(A) 연결 확인 (API Explorer 또는 로컬 토큰으로)

ACCOUNT_ID="1234567890"
curl -sS -H "Authorization: Bearer $TOKEN" \
  "https://merchantapi.googleapis.com/products/v1beta/accounts/$ACCOUNT_ID/products?pageSize=1"
# 200 OK이면 연결 정상 (신규 계정은 빈 결과일 수 있음)

(B) 제품 입력 등록(업서트)

# 4-2 예시 참고: productInputs:insert로 신규/갱신

(C) 처리된 제품/품질 이슈 목록

curl -sS -H "Authorization: Bearer $TOKEN" \
  "https://merchantapi.googleapis.com/products/v1beta/accounts/$ACCOUNT_ID/products?pageSize=100"

(D) 집계 상태(국가/목적지별 요약)

curl -sS -H "Authorization: Bearer $TOKEN" \
  "https://merchantapi.googleapis.com/issueresolution/v1/accounts/$ACCOUNT_ID/aggregateProductStatuses?pageSize=100"

(E) 계정 이슈

curl -sS -H "Authorization: Bearer $TOKEN" \
  "https://merchantapi.googleapis.com/accounts/v1/accounts/$ACCOUNT_ID/issues?language_code=ko-KR&time_zone.id=Asia/Seoul"

(F) 성과 리포트(MCQL)

-- Reports API의 reports.search에 제출할 MCQL 예시
SELECT offer_id, impressions, clicks
FROM product_performance_view
WHERE date DURING LAST_30_DAYS
ORDER BY clicks DESC
LIMIT 100

참고 문서

Quickstart: 전체 흐름 훑기(계정/데이터소스/제품입력/조회) (Google for Developers)
Products 개요/추가/관리/목록/이슈: 처리된 제품과 품질 이슈 흐름 이해 (Google for Developers)
집계 상태(요약): 전체 승인지표/이슈 집계 조회 (Google for Developers)
계정 이슈: 계정 단위 운영 문제/제재 대응 (Google for Developers)
인증/권한: Service Account(사내용), OAuth(대행사용) (Google for Developers)
연결 검증: API Explorer로 빠른 200 OK 확인 (Google for Developers)
쿼터/정책: 업데이트 1일 2회/1회 규정, 에러 코드, 상향 요청 (Google for Developers)
MCQL 문법: SELECT/FROM/WHERE/LIMIT, 기간 지정(DURING) (Google for Developers)

위 순서대로 구성하면 데이터 소스 → 제품 입력(업서트) → 처리 결과/이슈 수집 → 집계 KPI → MCQL 성과 리포트까지 운영 자동화가 가능합니다.

728x90

그리드형(광고전용)

저작자표시 비영리 동일조건 (새창열림)

pages.kr 날으는물고기 <º)))><

구글 판매자 센터 API 제품 상태·이슈·리포트 쉽고 빠른 쇼핑 데이터 자동화

구글 판매자 센터 API 제품 상태·이슈·리포트 쉽고 빠른 쇼핑 데이터 자동화

큰 그림 — 무엇이 어떻게 바뀌었나?

사전 준비 (계정, 권한, 인증)

데이터 소스 만들기 (API형)

1. API로 Primary 데이터 소스 생성 (개념)

2. (예시) cURL 스켈레톤

제품 등록 (productInputs:insert)

1. 요청 포인트

2. (예시) cURL

처리된 제품 & 품질 이슈 조회 (Products)

1. 처리된 제품 나열

2. “제품 데이터 & 제품 문제” 가이드 (권장 흐름)

제품 상태 요약(집계) — 대시보드용 핵심 KPI

계정 이슈 조회 — 운영 차단 요인 조기 탐지

리포트 & MCQL(고급 분석)

운영 아키텍처 예시 (실무형)

보안 점검 포인트

오류/트러블슈팅 포인트

빠른 스타트 예시 모음

(A) 연결 확인 (API Explorer 또는 로컬 토큰으로)

(B) 제품 입력 등록(업서트)

(C) 처리된 제품/품질 이슈 목록

(D) 집계 상태(국가/목적지별 요약)

(E) 계정 이슈

(F) 성과 리포트(MCQL)

참고 문서

댓글

티스토리툴바

구글 판매자 센터 API 제품 상태·이슈·리포트 쉽고 빠른 쇼핑 데이터 자동화

구글 판매자 센터 API 제품 상태·이슈·리포트 쉽고 빠른 쇼핑 데이터 자동화

큰 그림 — 무엇이 어떻게 바뀌었나?

사전 준비 (계정, 권한, 인증)

데이터 소스 만들기 (API형)

1. API로 Primary 데이터 소스 생성 (개념)

2. (예시) cURL 스켈레톤

제품 등록 (productInputs:insert)

1. 요청 포인트

2. (예시) cURL

처리된 제품 & 품질 이슈 조회 (Products)

1. 처리된 제품 나열

2. “제품 데이터 & 제품 문제” 가이드 (권장 흐름)

제품 상태 요약(집계) — 대시보드용 핵심 KPI

계정 이슈 조회 — 운영 차단 요인 조기 탐지

리포트 & MCQL(고급 분석)

운영 아키텍처 예시 (실무형)

보안 점검 포인트

오류/트러블슈팅 포인트

빠른 스타트 예시 모음

(A) 연결 확인 (API Explorer 또는 로컬 토큰으로)

(B) 제품 입력 등록(업서트)

(C) 처리된 제품/품질 이슈 목록

(D) 집계 상태(국가/목적지별 요약)

(E) 계정 이슈

(F) 성과 리포트(MCQL)

참고 문서

관련글

댓글

티스토리툴바