제품 API 참조 (v2)

요약

이 페이지는 제품 API v2(현재 버전, 새 통합에 권장)의 엔드포인트, 매개변수 및 응답 구조를 완전히 정리한 것입니다: 키워드 검색, 이미지 검색, 제품 상세 조회, 이미지 업로드, Taobao와 1688에서의 배송비 계산.

v1을 사용 중이라면 제품 API v1 (Legacy)를 참조하세요. 단계별로 따라 하려면 제품 검색 가이드를 참조하세요.

모든 엔드포인트는 POST이며, 인증 헤더(JWT 또는 API 키)가 필요하고, taobao 또는 alibaba 값을 가진 platform 매개변수가 필요합니다.

키워드로 제품 검색

POST /v2/products/search

요청 예시:

{
  "platform": "taobao",
  "q": "áo thun cotton",
  "lang": "vi",
  "sort": "SALE_QTY_DESC",
  "page": 1,
  "size": 20,
  "filter": {
    "priceRange": { "min": 0, "max": 100 }
  }
}

매개변수

결과 정렬 (sort)

결과 필터 (filter)

ffmOutbound 값

ffmDelivery 값

newArrival 값

sellerLevel 값

이미지로 제품 검색

참고: 이 기능은 무료 요금제에는 적용되지 않습니다.

POST /v2/products/search-by-image

이미지 검색에는 2가지 방법이 있으며, 두 매개변수 중 하나를 반드시 전달해야 합니다:

1. 이미지 URL로 검색 — imgUrl 매개변수 사용

Alibaba 링크(*.alicdn.com)만 사용할 수 있습니다.

{
  "platform": "taobao",
  "imgUrl": "https://img.alicdn.com/bao/uploaded/i3/694223667/O1CN01zSjKgp1cxXRQZsDLA_!!694223667.jpg",
  "lang": "vi",
  "page": 1,
  "size": 20
}

2. 업로드한 이미지로 검색 — imgId 매개변수 사용

먼저 POST /v2/products/upload-image API로 이미지를 업로드하여 imageId를 받은 후 imgId에 전달합니다:

{
  "platform": "alibaba",
  "imgId": "image-123",
  "lang": "vi",
  "page": 1,
  "size": 20
}

매개변수

* imgUrl 또는 imgId 중 하나를 반드시 전달해야 합니다.

제품 상세 정보 조회

POST /v2/products/find
POST /v2/products/detail

두 엔드포인트는 동일한 요청 구조를 사용하며 제품 상세 정보를 반환합니다. detail은 더 완전한 상세를 반환하며 1688 데이터가 필요할 때 적합합니다.

{
  "platform": "taobao",
  "id": "734467086498",
  "lang": "vi"
}

매개변수

https://e.tb.cn/h.hPY04k4RPfAco8F?tk=0CCI430IUqd 형식의 단축 링크를 만나면 먼저 링크를 처리하여 원본 링크를 얻어야 합니다 — 링크 원복 API를 사용하여 원본 링크와 제품 ID를 가져오세요.

제품 가격 유형

경고: 확장 프로그램/웹/앱에서 고객에게 가격을 표시한다면 가격이 Taobao/1688에서 직접 보는 것보다 높을 수 있다는 경고를 추가하세요. API 가격이 더 높게 발견되면 고객 서비스에 연락하여 주문 생성 시 가격 조정 지원을 받으세요.

Taobao: 프로모션 가격을 우선 표시·적용하고, 없으면 일반 가격을 사용합니다.

1688: 가격 적용 로직은 quote_type 필드에 따라 다릅니다:

1688 판매자 등급

등급은 seller_type 필드로 확인되는 1688 판매자 신뢰도를 결정하는 데 사용됩니다:

extra_info 필드 설명

배송비 계산

Taobao에만 적용됩니다.

POST /v2/products/shipping-fee

{
  "platform": "taobao",
  "id": "734467086498",
  "addressInfo": {
    "country": "VN",
    "state": "Hà Nội",
    "city": "Hà Nội",
    "district": "Hoàn Kiếm"
  }
}

매개변수

응답에는 post_fee(배송비, 단위 CNY), currency, item_id, mi_id, item_resource가 포함됩니다.

이미지 업로드

이미지 검색(매개변수 imgId)에 사용할 imageId를 얻기 위해 사용합니다.

POST /v2/products/upload-image

요청은 multipart/form-data 형식입니다:

응답: { "imageId": "image-123" }.

응답 구조

응답의 필드 이름은 snake_case 형식입니다. 각 플랫폼은 자체 제품 구조를 반환합니다:

• find / detail → 제품 객체 하나 (Product)
• search / search-by-image → { "paginate": { "total", "current", "size" }, "items": [...] } (페이지네이션 정보가 없으면 paginate 항목이 없을 수 있음)

공통 필드 (두 플랫폼 모두에 있음)

1688 전용 필드

공통 필드 외에도 1688 응답에는 다음 필드가 추가됩니다 (주제별로 그룹):

• 가격: price_range, channel_price, promotion_model, fenxiao_sale_info, is_jxhy
• 미디어: video_urls, white_image, translated_img_urls, translated_white_image
• 언어 번역: description_en, unit_en
• 판매량 / 리뷰: sold, review, level
• 배송: shipping_info
• 카테고리: top_category_id, second_category_id, third_category_id
• 식별자 및 링크: mp_id, item_type, batch_number, product_cargo_number, original_product_url, seller_shop_url, promotion_url
• 메타데이터: selling_point, offer_identities, create_date, is_select, certificate_list, seller_mix_setting
• 기타: extra_info, sku_price_ranges

참고: 응답에서 완전히 없는 필드는 호출 중인 플랫폼에 속하지 않는 필드입니다. 값이 null인 필드는 이 요청에서 해당 필드에 대한 데이터가 없음을 의미합니다.

전체 필드 목록 및 상세 설명: Swagger API.

자주 묻는 질문 (FAQ)

API로 가져온 제품 가격이 Taobao/1688 웹사이트에서 보는 가격과 다른 이유는?

1. 당사 API는 Alibaba의 국경 간 물류 시스템에 속하며 가격이 독립적으로 결정됩니다 — 웹사이트에 표시되는 가격과 별개입니다.
2. API와 달리 웹사이트는 신규 고객과 기존 고객을 구분하여 사용자 그룹별 프로모션 또는 쿠폰을 적용할 수 있습니다 — API가 지원하지 않는 기능입니다.

테스트 환경이 있나요?

없습니다. 기본 계정에는 테스트 통합을 위한 무료 요청 200회가 추가되어 있습니다.

데이터가 실시간인가요?

네, 데이터는 Taobao와 1688에서 직접 가져옵니다.

이미지 검색을 지원하나요?

네, 이미지 링크 및 업로드 이미지 검색을 지원합니다.

관련 링크

• 따라 하기: 제품 검색 가이드
• Legacy: 제품 API v1 (Legacy)
• 도구: Elim CLI — 터미널에서 제품 검색
• 전체 API Reference: openapi.elim.asia/api