Qnector
로그인

품목 API

판매자 품목 목록·상세 조회 및 생성·수정 API입니다.

엔드포인트

구분설명

GET /products

품목 목록 (products:read)

GET /products/{prod_code}

품목 상세 (products:read)

POST /products

품목 생성 (products:write)

PUT /products/{prod_code}

품목 수정 (products:write)

목록 조회

쿼리: q(검색, 최대 100자), page, limit(1~100, 기본 20), category_ids

bash
curl "https://qnector.kr/api/v1/seller/products?q=사과&page=1&limit=20" \
  -H "Authorization: Bearer qnc_live_YOUR_API_KEY"

엔드포인트 예시

GET /products

품목 목록 (products:read)

응답 예시 (200)

json
{
  "data": [
    {
      "prod_code": "SKU-001",
      "prod_name": "사과 5kg",
      "price": 15000,
      "tax_status": "taxed",
      "product_status": "discontinued",
      "is_active": true,
      "visibility_type": "all",
      "is_visible_to_all_buyers": true,
      "quantity": 120,
      "category": "과일",
      "created_at": "2026-06-01T09:00:00Z",
      "updated_at": "2026-06-20T14:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 150
  },
  "errors": []
}

상세 조회

경로의 prod_code로 단일 품목을 조회합니다.

bash
curl "https://qnector.kr/api/v1/seller/products/SKU-001" \
  -H "Authorization: Bearer qnc_live_YOUR_API_KEY"

엔드포인트 예시

GET /products/{prod_code}

품목 상세 (products:read)

응답 예시 (200)

json
{
  "data": {
    "prod_code": "SKU-001",
    "prod_name": "사과 5kg",
    "price": 15000,
    "description": "품목 설명",
    "barcode": "8801234567890",
    "tax_status": "taxed",
    "product_status": "discontinued",
    "visibility_type": "all",
    "is_visible_to_all_buyers": true,
    "category": "과일",
    "created_at": "2026-06-01T09:00:00Z",
    "updated_at": "2026-06-20T14:30:00Z"
  },
  "meta": {},
  "errors": []
}

품목 생성

POST /products — 요청당 1품목만 지원합니다. 배열 bulk 요청은 400 bulk_not_supported입니다.

생성 성공 시 재고는 0으로 초기화됩니다.

json
{
  "prod_code": "SKU-001",
  "prod_name": "샘플 품목",
  "price": 15000,
  "description": "품목 설명",
  "barcode": "8801234567890",
  "tax_status": "taxed",
  "product_status": "discontinued",
  "visibility_type": "all"
}

요청 필드

아래 필드는 POST /products 본문(JSON)에 사용합니다. PUT 수정 시에도 대부분 동일 필드를 사용합니다.

품목코드(prod_code)는 생성 시에만 지정할 수 있으며, 이후 변경할 수 없습니다.

필드필수여부자릿수/형식설명
prod_code필수string · 최대 50자품목코드. seller 내 유일, 공백 trim. 생성 후 변경 불가
prod_name필수string · 최대 200자품목명
price필수number · 0 이상 정수(원)판매가
description선택string품목 설명
size_description선택string규격·사이즈
barcode선택string바코드
remarks선택string비고
search_keywords선택string검색 키워드(쉼표 등 자유 형식)
image_url선택string · URL대표 이미지 URL
image_urls선택string[]추가 이미지 URL 목록
is_visible_to_all_buyers선택boolean · 기본 true전체 구매자 노출 여부
visibility_type선택string · all | specific_include | specific_exclude · 기본 all노출 범위
selected_buyer_ids선택string[] · 최대 500건visibility_type이 all이 아닐 때 노출·제외할 구매자 목록
ecount_code선택string · 기본 ""이카운트 ERP 품목코드(연동용)
category선택string자체 카테고리
tax_status선택string · taxed | tax_exempt · 기본 taxed과세 여부
product_status선택string · out_of_stock | discontinued | made_to_order · 기본 discontinued품목 상태
is_active선택boolean판매 활성 여부. PUT /products/{prod_code} 수정 시에만 사용

엔드포인트 예시

POST /products

품목 생성 (products:write)

요청 예시

json
{
  "prod_code": "SKU-001",
  "prod_name": "샘플 품목",
  "price": 15000,
  "tax_status": "taxed",
  "product_status": "discontinued",
  "visibility_type": "all"
}

응답 예시 (200)

json
{
  "data": {
    "prod_code": "SKU-001",
    "prod_name": "샘플 품목",
    "price": 15000,
    "tax_status": "taxed",
    "product_status": "discontinued",
    "is_active": true,
    "visibility_type": "all",
    "is_visible_to_all_buyers": true,
    "created_at": "2026-06-26T12:00:00Z",
    "updated_at": "2026-06-26T12:00:00Z"
  },
  "meta": {},
  "errors": []
}

품목 수정

PUT /products/{prod_code} — URL 경로의 prod_code로 수정 대상을 지정합니다.

요청 본문의 prod_code는 URL과 동일한 값이어야 하며, 품목코드 자체는 변경할 수 없습니다.

bash
curl -X PUT "https://qnector.kr/api/v1/seller/products/SKU-001" \
  -H "Authorization: Bearer qnc_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prod_code": "SKU-001",
    "prod_name": "수정된 품목명",
    "price": 18000,
    "tax_status": "taxed",
    "product_status": "discontinued"
  }'

엔드포인트 예시

PUT /products/{prod_code}

품목 수정 (products:write)

요청 예시

json
{
  "prod_code": "SKU-001",
  "prod_name": "수정된 품목명",
  "price": 18000,
  "tax_status": "taxed",
  "product_status": "discontinued"
}

응답 예시 (200)

json
{
  "data": {
    "success": true
  },
  "meta": {},
  "errors": []
}

응답 필드

목록(GET /products) 응답의 각 품목에 quantity(현재 재고 수량)가 포함됩니다. 상세(GET /products/{prod_code}) 응답에는 quantity가 없습니다.

재고는 창고별이 아니라 품목당 하나의 통합 수량으로 관리됩니다. 재고만 조회·수정하려면 GET/PUT /inventory를 사용하세요.

구분설명

prod_code

품목코드

prod_name

품목명

price

판매가(원)

description

품목 설명

size_description

규격·사이즈

barcode

바코드

remarks

비고

search_keywords

검색 키워드

image_url

대표 이미지 URL

image_urls

이미지 URL 배열

is_visible_to_all_buyers

전체 구매자 노출 여부

visibility_type

all | specific_include | specific_exclude

ecount_code

이카운트 품목코드

category

자체 카테고리

tax_status

taxed | tax_exempt

product_status

out_of_stock | discontinued | made_to_order

is_active

판매 활성 여부

quantity

목록 조회 시만 · 품목의 현재 재고 수량(통합)

created_at

등록 일시(ISO 8601)

updated_at

수정 일시(ISO 8601)

제한 사항

  • prod_code: seller 내 유일, 최대 50자. 생성 후 변경 불가
  • prod_name: 최대 200자
  • price: 0 이상 정수(원)
  • selected_buyer_ids: 최대 500건
  • 플랜별 품목 수 한도 초과 시 403 plan_limit_exceeded
  • 품목 삭제 API는 제공하지 않습니다