Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

요청 파라미터 설명

요청 데이터를 설명합니다. 자세한 API 요청 방식은 상품 수집 API 를 참고해 주세요. 상품 수집 API 관련 요청 파라미터 설명입니다. Google Merchant API 는 Google 공식 문서를 참고해 주세요.

공통 데이터 구조

다국어 텍스트 필드

상품명, 브랜드명, 카테고리명 등의 텍스트 필드는 3가지 형식을 지원합니다.

형식 1. 단순 문자열

"name": "클래식 티셔츠"

형식 2. 언어 지정 객체

"name": {
  "@value": "클래식 티셔츠",
  "@language": "ko"
}

형식 3. 다국어 배열

지원 언어 코드（ISO 639-1）：ko、en、ja

"name": [
  { "@value": "클래식 티셔츠", "@language": "ko" },
  { "@value": "Classic T-Shirt", "@language": "en" },
  { "@value": "クラシックTシャツ", "@language": "ja" }
]

언어 지정 객체(형식 2, 3)를 사용하는 경우, @value와 @language는 모두 필수입니다. @language를 생략하면 400 에러가 반환됩니다. 모든 언어를 반드시 제공할 필요는 없으며, 필요한 언어만 전송할 수 있습니다.

데이터 입력 규칙

  • 필수 필드와 null：필드 사양표에서 필수(O)로 표기된 필드에는 반드시 유효한 값을 포함해야 합니다. API 사양서에 기재된 모든 필드는 null을 허용하지 않습니다. 선택(X) 필드는 생략할 수 있지만, null은 전송하지 마세요.

  • 빈 문자열：필수 필드에 빈 문자열("")을 전송하면 400 에러가 반환됩니다.

  • 문자열(string)：시스템상의 고정 maxLength 제약은 없지만, 운영상의 권장 길이에 맞춰 전송해 주세요.

  • 숫자(number)：통화·수량·중량 등 용도에 맞는 일반적인 소수점 정밀도를 사용해 주세요.

  • enum：허용되는 값이 지정된 필드는 Enum 값 레퍼런스 섹션에 정리되어 있습니다. 명시된 값 이외를 전송하면 400 에러가 반환됩니다.

  • 필드 간 의존 관계：특정 필드의 값에 따라 다른 필드의 필수 여부가 변경되는 조건부 필수 규칙은 적용되지 않습니다. 필드 사양표의 필수 여부만을 기준으로 데이터를 구성합니다.

  • @graph 배열에는 최소 1건, 최대 1,000건의 상품을 포함할 수 있습니다.

  • API 명세서에 기재된 모든 필드는 null을 허용하지 않습니다.

문자열·숫자의 권장 제약값: 당사 시스템에서는 아래 제약으로 수신·저장됩니다. 설계 시 참고하세요.

이 값은 권장값이며 실제 값에 제한은 없습니다.

필드
타입
제약

sku

string

최대 64자, 반각 영숫자·하이픈·언더스코어

name

string

최대 200자

description.text

string

최대 5,000자

brand.name

string

최대 100자

category.name

string

최대 100자

url / mobileUrl

string

최대 2,048자, http(s) 스킴만 허용

price

number

소수점 이하 4자리까지(JPY/KRW는 정수 권장)

inventoryLevel.value

number

0 이상의 정수

shippingDetails.weight.value

number

소수점 이하 3자리까지

gtin

string

GTIN-8 / 12 / 13 / 14(숫자만)

priceCurrency

string

ISO 4217(예: JPY, KRW, USD)

availabilityStarts / Ends

string

ISO 8601 UTC(끝에 "Z" 필수)

Starts와 Ends를 모두 지정하는 경우, Starts < Ends여야 합니다.

권장 maxLength

아래는 운영상의 권장값입니다. 시스템상의 고정 상한은 아니지만, 검색·표시·매칭 품질을 안정시키기 위해 가능한 한 이 범위 내로 전송해 주세요.

대상 필드
권장 maxLength
비고

sku、offers.sku

100

상품·옵션을 고유하게 식별할 수 있는 안정적인 코드

gtin

14

GTIN-8, GTIN-12, GTIN-13, GTIN-14 대응

mpn

100

제조사 품번

name、brand.name、category.name

200

표시명으로 읽기 쉬운 길이

description.text

5000

HTML이 아닌 설명 본문 권장

url、mobileUrl、image.contentUrl

2048

https:// URL 권장

color、size、material

100

옵션·소재명

additionalProperty.propertyID

100

속성을 식별하는 키

권장 숫자 정밀도

대상 필드
권장 정밀도
비고

price、priceSpecification.price

통화 기준

JPY·KRW는 정수, USD는 소수점 이하 2자리 권장

inventoryLevel.value

정수

재고 수량

shippingDetails.weight.value

소수점 이하 3자리까지

kg·g 등의 중량 표현

additionalProperty.platform_rate

소수점 이하 4자리까지

예: 0.15

unit.unit_quantity

소수점 이하 3자리까지

포장 수량

unit.weight_quantity

소수점 이하 3자리까지

중량·용량 값. 숫자 타입으로 전송

운영상의 기대 포맷

대상 필드
기대 포맷
비고

sku、offers.sku

영숫자, 하이픈, 언더스코어 권장

예: PROD-001-WH-M. 등록 후 동일 상품의 식별자로 계속 사용해 주세요.

gtin

숫자만, 8~14자리

UPC(12자리), EAN(13자리), JAN(8·13자리), ISBN(13자리), ITF-14(14자리) 지원. 예: 4901234567894

mpn

제조사가 관리하는 품번 문자열

최대 70자 영숫자. GTIN이 없는 제품의 경우 전송 권장. 예: GO12345OOGLE

availabilityStarts、availabilityEnds

UTC ISO 8601, 끝에 Z

예: 2026-01-01T00:00:00Z

url、mobileUrl

접근 가능한 상품 페이지 URL

https:// URL 권장

image.contentUrl

외부에서 접근 가능한 이미지 URL

https:// URL 권장. 인증·만료 URL은 피해 주세요.

image.width.value、image.height.value

픽셀 값

양수를 전송해 주세요.

priceCurrency

ISO 4217, 3자리 대문자

예: JPY, KRW, USD

필드 상세 사양

이벤트 객체(CollectorProductsEvent)

필드
타입
필수
설명

@context

string

X

스키마 context. 고정값: "https://schema.org"

specversion

string

X

스펙 버전. 고정값: "1.0"

id

string

X

이벤트 고유 식별자. 등록: "EVT-CREATE-PRODUCT", 수정: "EVT-UPDATE-PRODUCT"

type

string

X

이벤트 타입. 등록: "create_product", 수정: "update_product"

agent

object

O

요청 주체 정보

@graph

array

O

상품 데이터 배열(1~1,000건)

agent 객체

필드
타입
필수
설명

@type

string

X

타입. 고정값: "Organization"

name

string

O

요청 기업명

상품 객체(@graph)

@graph 배열의 각 항목은 하나의 상품을 나타냅니다.

필드
타입
필수
설명

@type

string

X

타입. 고정값: "Product"

sku

string

O

상품 코드(고유 식별자)

name

string | object | array

O

상품명. 다국어 지원

description

object | array

O

상품 설명

brand

object

O

브랜드 정보

category

object | array

O

카테고리 정보

positiveNotes

string | object | array

X

주요 특징·장점 요약. 다국어 지원

url

string | object | array

O

상품 페이지 URL. 다국어 지원

mobileUrl

string | object | array

X

모바일 상품 페이지 URL. 다국어 지원

itemCondition

string

X

상품 상태. enum 참조

hasAdultConsideration

string

X

성인용 상품 구분. enum 참조

countryOfOrigin

object

X

제조국 정보

material

string | object | array

X

소재 정보. 다국어 지원

additionalProperty

array

X

추가 속성

offers

object | array

O

SKU별 가격·재고 정보

countryOfOrigin 객체

필드
타입
필수
설명

@type

string

X

타입. 고정값: "Country"

address

string

O

제조국 코드(ISO 3166-1 alpha-2, 예: "JP", "KR", "US")

브랜드(brand)

필드
타입
필수
설명

@type

string

X

타입. 고정값: "Brand"

@id

string

O

브랜드 식별자

name

string | object | array

O

브랜드명. 다국어 지원

logo

array<string>

X

브랜드 로고 URL 목록

카테고리(category)

단일 객체 또는 배열로 전송합니다. 배열을 사용하는 경우, position 값으로 카테고리 계층 레벨을 표현합니다.

필드
타입
필수
설명

@type

string

X

타입. 고정값: "CategoryCode"

codeValue

string

O

카테고리 코드

name

object | array

O

카테고리명. 다국어 지원

position

integer

O

카테고리 계층(1 = 대분류, 2 = 중분류, ...)

상품 설명(description)

필드
타입
필수
설명

@type

string

X

타입. 고정값: "TextObject"

text

string

O

설명 텍스트

inLanguage

string

O

언어 코드(ISO 639-1): ko, en, ja

image

object | array

X

설명에 포함된 이미지 정보

additionalProperty

array

X

추가 속성

description 내 이미지 객체

필드
타입
필수
설명

@type

string

X

타입. 고정값: "ImageObject"

contentUrl

string

X

이미지 URL

inLanguage

string

X

언어 코드

가격·재고 정보(offers)

단일 객체 또는 배열로 전송합니다. 컬러·사이즈 등의 옵션별로 개별 offer를 구성합니다.

필드
타입
필수
설명

@type

string

X

타입. 고정값: "Offer"

sku

string

O

옵션별 상품 코드

gtin

string

X

국제 표준 바코드(GTIN). UPC(12자리), EAN(13자리), JAN(8·13자리), ISBN(13자리), ITF-14(14자리) 지원 예: 8801234567890

mpn

string

O

제조사 품번(MPN). GTIN이 없는 제품의 경우 전송 권장. 최대 70자 영숫자. 예: GO12345OOGLE

price

number

O

가격

priceCurrency

string

O

통화 코드(ISO 4217, 예: "JPY", "KRW", "USD")

priceSpecification

object | array

X

가격 타입 상세

color

string

O

컬러

size

string

O

사이즈

availability

string

O

재고 상태. enum 참조

availabilityStarts

string

O

판매 시작 일시(UTC ISO 8601)

availabilityEnds

string

O

판매 종료 일시(UTC ISO 8601)

inventoryLevel

object

X

재고 수량 정보

shippingDetails

object

X

배송 정보

image

object | array

O

상품 이미지

additionalProperty

array

X

추가 속성

inventoryLevel 객체

필드
타입
필수
설명

@type

string

X

타입. 고정값: "QuantitativeValue"

value

number

O

재고 수량

shippingDetails 객체

필드
타입
필수
설명

@type

string

X

타입. 고정값: "OfferShippingDetails"

weight

object

O

배송 중량

shippingDetails.weight 객체

필드
타입
필수
설명

@type

string

X

타입. 고정값: "QuantitativeValue"

value

number

O

중량 값

unitCode

string

O

단위 코드(예: "KGM", "GRM")

가격 타입(priceSpecification)

정가, 판매가, 제조사 권장 소비자 가격 등 다양한 가격 타입을 표현합니다.

필드
타입
필수
설명

@type

string

X

타입. 고정값: "UnitPriceSpecification"

priceType

string

O

가격 구분. enum 참조

price

number

O

가격

priceCurrency

string

O

통화 코드(ISO 4217)

unitCode

string

O

단위 코드

이미지(image)

필드
타입
필수
설명

@type

string

X

타입. 고정값: "ImageObject"

representativeOfPage

boolean

X

대표 이미지 여부(true = 대표 이미지)

contentUrl

string

O

이미지 URL

contentSize

string

X

파일 크기

width

object

X

너비({ "@type": "QuantitativeValue", "value": 800 })

height

object

X

높이({ "@type": "QuantitativeValue", "value": 600 })

이미지 사양

항목
사양

지원 포맷

jpg, jpeg, png, webp

최대 파일 크기

10 MB

권장 해상도

800×800 이상

width / height 단위

픽셀(px)

contentSize 단위

바이트(byte)

추가 속성(additionalProperty)

표준 필드로 표현할 수 없는 추가 정보를 저장하기 위한 확장 필드입니다.

상품 객체(@graph[]), 상품 설명(description), 가격 정보(offers) 내에서 사용할 수 있습니다.

필드
타입
필수
설명

@type

string

X

타입. 고정값: "PropertyValue"

propertyID

string

X

속성 ID(속성을 구분하는 키)

value

any

X

값(string, number, boolean, array 등 모든 타입 사용 가능)

상품 객체(@graph[]) 내에 값을 전송하는 것을 권장합니다.

propertyID 확장 정책

  • 위의 권장 propertyID 목록은 당사가 표준 분석에 활용하는 기존 속성입니다.

  • 그 외의 propertyID를 임의로 추가할 수 있습니다. 다만, 표준 분석 대상에서 제외되며 원문 그대로 보관됩니다.

  • 네이밍 규칙: 영소문자·숫자·언더스코어(snake_case) 권장. 최대 64자.

  • value 최대 크기: JSON 직렬화 후 8 KB 이내.

속성 레퍼런스

아래는 additionalProperty에서 사용할 수 있는 권장 속성 목록입니다. 허용 값 예시를 참고하여 값의 포맷을 맞춰 전송해 주세요.

propertyID
value 타입
설명
허용 값 / 예시

gender

string

성별

Enum 값 레퍼런스의 gender 참조

season

string[]

계절

Enum 값 레퍼런스의 season 참조

temperature

string

보관 방법

자유 값. 예: "Refrigerate"

platform_rate

number

플랫폼 수수료

0.15

unit

object

포장·중량 정보

서브 필드: unit, unit_quantity, weight_unit, weight_quantity

seller

object

판매자 정보

서브 필드: prefecture, seller_name

unit 객체 구조

서브 필드
타입
설명
예시

unit

string

포장 단위. 자유 값

"box", "pack", "ea"

unit_quantity

number

포장 수량

500

weight_unit

string

중량 단위

"g", "ml"

weight_quantity

number

중량 값

500

seller 객체 구조

서브 필드
타입
설명
예시

prefecture

string

산지·지역

"秋田県", "제주도" 등

seller_name

string

판매자명

"きのこ農園", "유스파머" 등

사용 예시

unit 속성의 weight_unit은 g 또는 ml로 통일하여 전송합니다. 원본 데이터가 kg인 경우 g으로, L인 경우 ml로 변환해 주세요.

Enum 값 레퍼런스

itemCondition

상품의 물리적 상태를 나타냅니다.

값
설명

NewCondition

새 상품

RefurbishedCondition

리퍼비시 상품

UsedCondition

중고 상품

DamagedCondition

손상 상품

hasAdultConsideration

성인용 상품 여부를 구분합니다.

값
설명

AlcoholConsideration

주류

DangerousGoodConsideration

위험물

HealthcareConsideration

의약품·의료기기

NarcoticConsideration

마약류

ReducedRelevanceForChildrenConsideration

아동 부적합

SexualContentConsideration

성인 콘텐츠

TobaccoNicotineConsideration

담배·니코틴

UnclassifiedAdultConsideration

기타 성인용

ViolenceConsideration

폭력성

WeaponConsideration

무기류

availability

SKU의 재고·판매 상태를 나타냅니다.

값
설명

BackOrder

입고 예정(주문 가능)

Discontinued

판매 종료

InStock

재고 있음

InStoreOnly

오프라인 매장 전용

LimitedAvailability

수량 한정

MadeToOrder

주문 제작

OnlineOnly

온라인 한정

OutOfStock

재고 없음

PreOrder

예약 주문

PreSale

선행 판매

Reserved

예약 완료

SoldOut

품절

priceType

가격의 성격을 구분합니다.

값
설명

InvoicePrice

청구 가격

ListPrice

정가

MSRP

제조사 권장 소비자 가격

MinimumAdvertisedPrice

최저 광고 가격

RegularPrice

일반 판매가

SRP

권장 소매가

SalePrice

세일 가격

StrikethroughPrice

취소선 가격(원래 가격 표시용)

gender

additionalProperty의 propertyID가 gender인 경우 사용합니다.

값
설명

M

Men

W

Women

U

Unisex

season

additionalProperty의 propertyID가 season인 경우 사용합니다. 복수 지정 시 문자열 배열로 전송해 주세요.

값
설명

Spring

봄

Summer

여름

Fall

가을

Winter

겨울

weight_unit

additionalProperty의 propertyID가 unit인 경우, value.weight_unit에서 사용합니다.

값
설명

g

그램

ml

밀리리터

에러 응답 레퍼런스

주요 400 에러 발생 조건

조건
발생 필드 예시

필수 필드가 null 또는 누락

sku, name, offers.price 등

enum 이외의 값

availability, priceType, itemCondition

ISO 형식 위반

priceCurrency, countryOfOrigin.address, availabilityStarts

@value 또는 @language 누락

다국어 객체 전반

문자 수·숫자 범위 초과

위의 「권장 제약값」 참조

@graph가 0건 또는 1,000건 초과

@graph 배열

참고: JSON 스키마 예시

상품 등록
상품 수정
상품 삭제
이전상품 데이터 수집 API다음상품 데이터 수집 API

마지막 업데이트