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}

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

식별자 및 채널

필드	타입	설명
`id`	string	Taobao = `mi_id`(주문 `lines[].id`; 주기적으로 바뀌므로 장기 캐시하지 마세요). 1688 = `offerId`. Weidian은 현재 `prod_weidian_{source_product_id}`
`channel`	string	`1688`, `taobao`, 또는 `weidian`
`source_product_id`	string	1688 = `offerId` (same as `id`); Taobao = original `item_id`
`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 도매 구간(신규 상품 첫 구간 ≥2); 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	스펙 차원(색상, 사이즈 등)
`attributes[].name` / `value`	string	표시용 라벨(`language` 설정 시 번역됨)
`attributes[].original_name` / `original_value`	string	그룹화/매칭용 안정적인 중국어 키
`attributes[].prop_id`	string \| null	업스트림 속성 ID(문자열; Taobao `prop_id`; 1688 `attributeId`). 있으면 이름보다 우선
`attributes[].value_id`	string \| null	업스트림 값 ID(문자열; Taobao `value_id`). 1688에 valueId 없으면 `null`
`attributes[].image`	string \| null	옵션/스펙 이미지
`price`	object	SKU 단위 위안 가격
`stock`	number	사용 가능 수량, `0` = 품절
`image`	string \| null	SKU 기본 이미지
`shipping`	object \| null	1688 SKU 패키지 치수(아래 표); 타오바오는 `null`
`min_order_quantity`	number \| null	1688 MOQ(상품 단위 값을 각 SKU에 부여)
`distribution`	object \| null	1688 dropship 가격

SKU 패키지 치수 (`variants[].shipping`)

1688 업스트림 productShippingInfo.skuShippingDetails(SkuShippingDetail)에서 매핑됩니다. 타오바오에는 해당 데이터가 없어 항상 null입니다. 비어 있거나 0인 치수/무게는 null로 정규화되며, SKU에 치수 데이터가 없으면 shipping 자체가 null입니다.

필드	타입	설명
`width_cm`	number \| null	너비, cm(판매자 기입)
`length_cm`	number \| null	길이, cm
`height_cm`	number \| null	높이, cm
`weight_kg`	number \| null	무게, kg
`official_width_cm`	number \| null	공식 측정 너비, cm
`official_length_cm`	number \| null	공식 측정 길이, cm
`official_height_cm`	number \| null	공식 측정 높이, cm
`official_weight_kg`	number \| null	공식 측정 무게, kg
`ai_weight_kg`	number \| null	AI 예측 무게, kg
`ai_weight_accuracy`	string \| null	해당 리프 카테고리의 AI 무게 정확도(예: `80%`)
`source`	string \| null	치수 출처(예: `商家自填`)

운임 추정 시 official_*를 우선하고, 다음으로 판매자 기입 치수/무게, 그다음 ai_weight_kg(ai_weight_accuracy를 신뢰도 힌트로)를 사용하세요.

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

필드	타입	설명
`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": "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...",
        "upstream_sku_id": "12123313",
        "stock": 100,
        "shipping": {
          "width_cm": 10,
          "length_cm": 10,
          "height_cm": 10,
          "weight_kg": 1.2,
          "official_width_cm": 5,
          "official_length_cm": 12,
          "official_height_cm": 14,
          "official_weight_kg": 0.001,
          "ai_weight_kg": 0.001,
          "ai_weight_accuracy": "80%",
          "source": "商家自填"
        }
      }
    ]
  },
  "request_id": "req_..."
}

채널별 필드 제공 여부

필드	1688	Taobao	Weidian
`videos`, `price_tiers`, `trade_score`	✓	—	Varies
`variants[].shipping`, `distribution`	✓	—	—
`variants[].attributes[].prop_id`	✓ (`attributeId`)	✓ (`prop_id`)	—
`variants[].attributes[].value_id`	— (`null`)	✓ (`value_id`)	—
주문용 `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별로 그룹화합니다(prop_id가 있으면 ID로도 가능).
각 사용자 선택에 따라 variants를 필터링하고 품절 옵션을 비활성화합니다.
일치하는 sku_id와 source_product_id를 order preview에 전달합니다.

매칭 키: Taobao에서 prop_id + value_id가 있으면 ID를 우선 사용하세요(안정적인 CPV 식별자로, 여러 SKU가 같은 속성명을 공유할 때 혼동을 방지). UI 그룹화는 original_name + original_value로 폴백. name / value는 표시 전용. 라벨로 의미 유형을 추론하지 마세요.

{
  "prop_id": "1627207",
  "value_id": "43553464153",
  "name": "Color Classification",
  "value": "[Special for Bicycle Maintenance] Professional 46-Piece Set",
  "original_name": "颜色分类",
  "original_value": "【自行车维修专用】专业46件套",
  "image": "https://img.alicdn.com/..."
}

1688도 동일 구조이며 prop_id는 attributeId, value_id는 null입니다(업스트림 SkuAttribute에 valueId 없음).

Get Support

Need integration help? Contact Developer Support at support@hiobuy.com · Response within 1–2 business days

Email support