상품 API

상품 API는 서버용 비공개 키가 필요합니다.

Authorization: Bearer {SERVER_PRIVATE_API_KEY}
Accept: application/json

상품 목록 조회

GET /api/public/v1/products

Query parameters

이름	필수	타입	설명
`page`	선택	integer	페이지 번호. 기본값 `1`
`limit`	선택	integer	페이지당 개수. 기본값 `20`, 최대 `100`
`status`	선택	string	`publish`, `pending`, `paused` 등 상태 필터
`category_id`	선택	integer	특정 카테고리의 상품만 조회
`category_ids`	선택	array 또는 comma string	여러 카테고리 중 하나에 속한 상품 조회
`tag_id`	선택	integer	특정 태그의 상품만 조회
`tag_ids`	선택	array 또는 comma string	여러 태그 중 하나가 붙은 상품 조회
`search`	선택	string	상품명 검색

curl -X GET "https://{site_host}/api/public/v1/products?page=1&limit=20" \
  -H "Authorization: Bearer {SERVER_PRIVATE_API_KEY}" \
  -H "Accept: application/json"

상품 상세 조회

GET /api/public/v1/products/{productId}

Query parameters

이름	필수	타입	설명
`language`	선택	string	`ko`, `en`, `ja`. 기본값은 사이트 언어

상품 생성

POST /api/public/v1/products

application/json 또는 multipart/form-data로 전송합니다.

필수 필드

이름	타입	설명
`title`	string	상품명
`category_id`	integer	상품 카테고리 ID
`featured_image`	file 또는 string	메인 이미지. 파일, URL, data URI 가능

주요 선택 필드

이름	타입	설명
`description_html`	string	상품 상세 HTML
`status`	string	`pending` 또는 `publish`. 기본값 `pending`
`base_price`	number	기본가. 기본값 `0`
`sale_price`	number	할인가
`is_on_sale`	boolean	할인 여부
`is_free`	boolean	무료 상품 여부
`requires_shipping`	boolean	배송 필요 여부
`is_shipping_free`	boolean	무료 배송 여부
`shipping_price`	number	배송비
`is_over_50000_free`	boolean	5만원 이상 무료배송 여부
`is_extra_shipping_fee`	boolean	추가 배송비 여부
`is_purchase_agency`	boolean	구매대행 여부
`tax_type`	string	과세 타입
`options`	array	옵션명 목록
`variants`	array	옵션 조합별 가격, 재고, SKU
`images`	array	추가 이미지 목록
`connected_membership_ids`	array	연결 멤버십 ID 목록
`related_product_ids`	array	관련 상품 ID 목록
`tag_ids`	array	상품 태그 ID 목록. 현재 상품당 1개까지 선택 가능

curl -X POST "https://{site_host}/api/public/v1/products" \
  -H "Authorization: Bearer {SERVER_PRIVATE_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "title": "개발자 후디",
    "category_id": 11,
    "featured_image": "https://example.com/main.jpg",
    "status": "publish",
    "base_price": 39000,
    "sale_price": 29000,
    "is_on_sale": true,
    "requires_shipping": true,
    "shipping_price": 3000,
    "tag_ids": [17],
    "options": ["색상", "사이즈"],
    "variants": [
      {
        "option1": "블랙",
        "option2": "M",
        "price": 29000,
        "stock": 10,
        "sku": "BLK-M"
      }
    ]
  }'

상품 수정

PUT /api/public/v1/products/{productId}

전달한 필드만 업데이트합니다. 전달하지 않은 필드는 기존 값을 유지합니다.

curl -X PUT "https://{site_host}/api/public/v1/products/1234" \
  -H "Authorization: Bearer {SERVER_PRIVATE_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "title": "개발자 후디 v2",
    "sale_price": 27000,
    "is_on_sale": true,
    "tag_ids": [17]
  }'

대표 응답 필드

필드	설명
`product_id`	상품 ID
`title`	상품명
`description_html`	상품 상세 HTML
`category_id`	상품 카테고리 ID
`status`	상품 상태
`language`	언어 코드
`base_price`	기본가
`sale_price`	할인가
`is_on_sale`	할인 여부
`is_free`	무료 상품 여부
`requires_shipping`	배송 필요 여부
`variants`	옵션 조합 목록
`featured_image`	대표 이미지
`images`	추가 이미지
`tag_ids`	연결된 상품 태그 ID
`connected_membership_ids`	연결 멤버십 ID
`related_product_ids`	관련 상품 ID
`created_at`	생성 일시
`updated_at`	수정 일시