상품 API

카탈로그에서 상품을 생성, 조회, 수정, 삭제합니다.

엔드포인트

GET

/products

products:read

페이지네이션이 적용된 상품 목록을 조회합니다. 상태, 카테고리, 검색으로 필터링할 수 있습니다.

GET

/products/:id

products:read

ID로 단일 상품을 조회합니다.

POST

/products

products:write

카탈로그에 새 상품을 생성합니다.

PUT

/products/:id

products:write

기존 상품을 수정합니다. 부분 업데이트가 지원됩니다.

DELETE

/products/:id

products:write

상품을 소프트 삭제합니다. 30일 내에 복원할 수 있습니다.

필드 참조

필드	유형	필수	설명
id	string	아니오	고유 상품 식별자 (읽기 전용)
sku	string	예	재고 관리 단위
name	string	예	상품명
description	string	아니오	상품 설명 (HTML 허용)
barcode	string	아니오	기본 상품 바코드 (UPC/EAN)
brand	string	아니오	상품 브랜드명
categoryId	string	아니오	카테고리 식별자
unitPrice	integer	예	센트 단위 가격 (예: 1999 = $19.99)
normalPrice	integer	아니오	정상가/정가 (센트 단위, 할인 표시용)
purchasePrice	integer	아니오	매입가/원가 (센트 단위)
weight	string	아니오	무게 (그램)
isActive	boolean	아니오	상품 활성/게시 여부 (기본값: true)
stockTotal	integer	아니오	모든 창고의 총 가용 재고 (읽기 전용)
images	string[]	아니오	상품 이미지 URL
createdAt	datetime	아니오	ISO 8601 타임스탬프 (읽기 전용)
updatedAt	datetime	아니오	ISO 8601 타임스탬프 (읽기 전용)

쿼리 매개변수 (목록)

필드	유형	필수	설명
page	integer	아니오	페이지 번호 (기본값: 1)
limit	integer	아니오	페이지당 항목 수 (기본값: 20, 최대: 100)

예시

페이지네이션으로 상품 목록 조회

bash

curl "https://api.mercozy.com/api/v1/external/products?page=1&limit=10" \
  -H "X-API-Key: mk_live_your_key_here"

상품 생성

bash

curl -X POST "https://api.mercozy.com/api/v1/external/products" \
  -H "X-API-Key: mk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "WDG-001",
    "name": "Premium Widget",
    "unitPrice": 2999,
    "normalPrice": 3999,
    "brand": "Acme Corp",
    "isActive": true
  }'