Product API 응답 모델

response_format: "standard"(기본값)를 사용하면 상품 엔드포인트는 아래 타입을 반환합니다. 정식 TypeScript: packages/shared/src/products.ts.

엔드포인트: detail · search · image search · parse

응답 envelope {#envelope}

엔드포인트	형태
`detail`, `parse`	`{ product: StandardProductDetail, request_id }`
`search`, `search-by-image`	`StandardProductList & { request_id }`
`upload-image`	`{ channel, image_id, request_id }`

StandardProductDetail {#standard-product-detail}

상품 페이지와 체크아웃을 위한 전체 상품 스냅샷입니다. 주문으로 매핑: source_product_id → offer_id, variants[].sku_id → spec_id(Procurement orders).

식별자 및 채널

필드	타입	설명
`id`	string	HIOBuy 복합 키: `{channel}_{source_product_id}`
`channel`	string	`1688`, `taobao`, 또는 `weidian`
`source_product_id`	string	1688 = `offerId`; Taobao = `mi_id`(주문 API에 필요)
`source_url`	string	정식 상품 페이지 URL

현지화 텍스트(`title`, `description`)

필드	타입	설명
`original`	string	마켓플레이스 원문(보통 중국어)
`translated`	string \| null	요청한 `language`의 번역
`language`	string	`translated`의 로케일
`description`	object \| null	긴 상세 설명(대개 HTML)

가격(`price`, `price_tiers[]`)

모든 금액은 CNY yuan입니다(fen 아님). promotion_amount가 있으면 우선 사용하고, 없으면 display_amount를 사용하세요.

필드	타입	설명
`price.original_amount`	number	프로모션 전 정가
`price.display_amount`	number	구매자에게 표시되는 가격(CNY)
`price.promotion_amount`	number \| null	적용 가능한 경우 프로모션 단가
`price.original_currency` / `display_currency`	string	항상 `CNY`
`price_tiers[]`	array	1688 도매 구간 가격, Taobao에서는 비어 있음
`min_order_quantity`	number \| null	1688 MOQ
`distribution_min_quantity`	number \| null	1688 dropship 최소 수량

미디어(`images[]`, `videos`)

필드	타입	설명
`images[].url`	string	이미지 CDN URL
`images[].type`	enum	`main`, `gallery`, 또는 `variant`
`videos.main` / `videos.detail`	string \| null	1688 동영상, Taobao는 `null`

Attributes와 variants

SKU 선택과 주문 라인을 결정하는 것은 variants[]뿐입니다.

필드	역할
`attributes[]`	CPV 스펙 — 표시 전용이며 SKU 해석에 사용하지 않음
`variants[]`	가격, 재고, 스펙을 포함한 구매 가능한 SKU 매트릭스

Variant 객체(`variants[]`)

필드	타입	설명
`sku_id`	string	주문 생성 시 `spec_id`로 전달
`upstream_sku_id`	string \| null	1688 숫자형 `skuId`
`attributes[]`	array	스펙 차원(색상, 사이즈 등)
`price`	object	SKU 단위 위안 가격
`stock`	number	사용 가능 수량, `0` = 품절
`image`	string \| null	SKU 기본 이미지
`shipping`	object \| null	운임 계산용 1688 패키지 치수
`distribution`	object \| null	1688 dropship 가격

판매자, 배송 및 메타데이터

필드	타입	설명
`seller.id` / `seller.name`	string	상점 id와 표시명
`seller.shop_url`	string \| null	스토어프런트 링크
`shipping.shipping_from`	string \| null	중국 내 발송 지역
`shipping.domestic_shipping_fee`	object \| null	위안 단위 중국 내 예상 배송비
`metadata.raw_category`	string \| null	Upstream 카테고리
`metadata.brand`	string \| null	선언된 브랜드
`metadata.updated_at`	string	ISO 8601 마지막 동기화 시각
`trade_score`	string \| null	1688 품질 점수

예시(일부 생략)

{
  "product": {
    "id": "1688_554456348334",
    "channel": "1688",
    "source_product_id": "554456348334",
    "title": {
      "original": "...",
      "translated": "...",
      "language": "en"
    },
    "price": {
      "display_amount": 29.9,
      "promotion_amount": 24.9
    },
    "variants": [
      {
        "sku_id": "b266e0...",
        "stock": 100
      }
    ]
  },
  "request_id": "req_..."
}

채널별 필드 제공 여부

필드	1688	Taobao	Weidian
`videos`, `price_tiers`, `trade_score`	✓	—	Varies
`variants[].shipping`, `distribution`	✓	—	—
주문용 `source_product_id`	`offerId`	`mi_id`	Platform id

StandardProductList {#standard-product-list}

search와 image search에서 반환됩니다. 각 items[] 항목은 요약이며, SKU 매트릭스는 detail을 호출하세요.

필드	타입	설명
`channel`	string	조회한 마켓플레이스
`keyword`	string	키워드 echo(순수 이미지 검색이면 빈 값)
`page` / `page_size`	number	적용된 페이지네이션
`total`	number	Upstream 전체 수(근사치일 수 있음)
`items[]`	array	`StandardProductListItem` 객체
`pic_region_info`	object	이미지 검색: 감지된 크롭 영역

StandardProductListItem

필드	타입	설명
`id`, `channel`, `source_product_id`, `source_url`	string	detail 조회에는 `source_product_id` 사용
`title`	LocalizedTitle	목록 제목
`price`	ProductPrice	CNY yuan 단위 요약 가격
`image`	string	썸네일 URL
`seller.name`	string	상점명

Upload-image 응답 {#upload-image-response}

필드	타입	설명
`channel`	string	이미지를 저장한 마켓플레이스
`image_id`	string	image search에서 재사용

Variant 선택 {#variant-selection}

detail을 로드하고 product.variants를 읽습니다.
선택 UI 차원을 위해 attributes[].original_name별로 그룹화합니다.
각 사용자 선택에 따라 variants를 필터링하고 품절 옵션을 비활성화합니다.
일치하는 sku_id와 source_product_id를 order preview에 전달합니다.