Taobao/1688 제품 검색 방법

이 가이드를 사용하는 경우

Taobao/1688에서 제품 데이터가 필요할 때 사용합니다: 키워드 또는 이미지로 제품을 검색하고, 필터를 적용하고, 단일 제품 상세를 가져옵니다.

이 가이드는 제품 API v2(현재 버전)를 사용합니다. v1을 사용 중이라면 제품 API v1 (Legacy)를 참조하세요.

모든 파라미터와 값에 대한 전체 참조: 제품 API

사전 조건

• API 인증 정보(JWT 또는 API 키) — API 요청 인증 참조
• Base URL: https://openapi.elim.asia

키워드 검색

1단계 — 검색 엔드포인트 호출

POST /v2/products/search

{
  "platform": "taobao",
  "q": "áo thun cotton",
  "page": 1,
  "size": 20,
  "lang": "vi"
}

platform 파라미터(taobao 또는 alibaba)는 API v2에서 필수입니다.

2단계 — 결과 언어 번역

lang 파라미터(vi/en/ru/ko/ja)를 사용하여 번역된 제목을 받으세요. 번역 데이터는 title_en 키에 있으며, title 키는 원래 중국어로 유지됩니다.

3단계 — 결과 정렬

sort 파라미터를 사용합니다:

4단계 — 결과 필터링(선택)

filter 파라미터를 다음 기준과 함께 사용합니다(대부분 1688에만 적용):

• filter.priceRange — 가격 범위(CNY): { "min": 0, "max": 100 } — ✅ Taobao ✅ 1688
• filter.shopId — 같은 판매자의 제품 — ✅ Taobao ✅ 1688
• filter.sellerLevel (L1–L4) — 판매자 등급
• filter.isFactory — 슈퍼 팩토리 상품만
• filter.ffmOutbound (FFMO1–FFMO6) — 빠른 출고율
• filter.ffmDelivery (FFMD0–FFMD2) — 배송 속도
• filter.allowDropship, filter.freeshipForDropship — 드롭쉬핑 지원
• filter.newArrival (7DAY/30DAY) — 최근 업데이트된 신상품
• filter.platformPick, filter.globalPick, filter.dropshipPick — 플랫폼 선별 상품 소스

각 필터의 전체 값 목록: 제품 API

이미지 검색

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

POST /v2/products/search-by-image

두 가지 방법이 있습니다:

방법 1 — 이미지 URL 사용(*.alicdn.com 링크만):

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

방법 2 — 업로드된 이미지 사용:

1. POST /v2/products/upload-image API로 이미지를 업로드하여 imageId를 받으세요.
2. imgUrl 대신 imgId로 search-by-image를 호출하세요:

{
  "platform": "alibaba",
  "imgId": "image-123",
  "lang": "vi"
}

단일 제품 상세 조회

1단계 — 단축 링크 처리(있는 경우)

https://e.tb.cn/h.hPY04k4RPfAco8F?tk=0CCI430IUqd 형태의 단축 링크는 먼저 확장해야 합니다. Unshorten link API를 사용하여 원본 링크와 제품 ID를 얻으세요.

2단계 — 상세 엔드포인트 호출

POST /v2/products/find

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

응답에는 가격, 재고, 변형(색상/사이즈), 이미지 앨범, 설명, 배송 정책이 포함됩니다. 더 완전한 1688 데이터가 필요하면 동일한 요청 구조로 POST /v2/products/detail을 사용하세요.

3단계 — 가격 올바르게 표시

• Taobao: promotion_price 우선; 없으면 price 사용.
• 1688: 가격 로직은 quote_type(direct/by_sku/by_volume)에 따라 달라집니다.

[!WARNING] API 가격은 복잡한 프로모션을 적용할 수 없기 때문에 Taobao/1688 웹사이트의 가격보다 높을 수 있습니다. 확장 프로그램/웹/앱에서 가격을 표시한다면 고객에게 경고를 표시하세요.

결과 확인

• 요청이 title, price, img_url을 포함한 제품 배열과 함께 HTTP 200을 반환합니다.
• 이미지 검색 결과가 원본 이미지의 상품과 유사한 제품을 반환합니다.

관련 링크

• 참조: 제품 API — 전체 파라미터, 필터 값, 가격 로직
• Legacy: 제품 API v1 (Legacy)
• 도구: Elim CLI — 터미널에서 제품 검색
• 다음: 주문 생성 및 관리