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

Copy of 요청 파라미터 설명

요청 데이터를 설명합니다. 자세한 API 요청 방식은 상품 수집 API 를 참고해 주세요.

공통 데이터 구조

다국어 텍스트 필드

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

형식 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) 로 표기된 필드는 반드시 유효한 값을 포함해야 합니다. 필수 필드에 null을 전송하면 400 에러가 반환됩니다. 선택(X) 필드는 생략하거나 null로 전송할 수 있습니다.

  • 문자열(string): 별도의 maxLength 제약 없이 적절한 길이로 전송하는 것을 권장합니다.

  • 숫자(number): 별도의 소수점 정밀도 규약 없이 통화에 맞는 일반적인 자릿수를 사용합니다 (예: KRW는 정수, USD는 소수점 이하 2자리).

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

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

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

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

필드 상세 명세

이벤트 객체 (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, 예: "KR", "JP", "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

O

국제 표준 바코드

mpn

string

O

제조사 부품 번호

price

number

O

가격

priceCurrency

string

O

통화 코드 (ISO 4217, 예: "KRW", "JPY", "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 })

추가 속성 (additionalProperty)

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

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

필드
타입
필수
설명

@type

string

X

유형. 고정값: "PropertyValue"

propertyID

string

X

속성 아이디 (속성을 구분하는 키)

value

any

X

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

상품 객체(@graph[]) 내로 값을 전달하기를 권장합니다.

속성 레퍼런스

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

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

gender

string

성별

"M" (Men), "W" (Women), "U" (Unisex), null (미지정)

season

string[]

계절

"Spring", "Summer", "Fall", "Winter" 중 선택

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

string

무게 값

"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

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

참고: JSON 스키마 예시

상품 등록
상품 수정
상품 삭제

마지막 업데이트