Tham chiếu API sản phẩm (v2)

Tóm tắt

Trang này liệt kê đầy đủ endpoint, tham số và cấu trúc response của API sản phẩm v2 (phiên bản hiện tại, khuyên dùng cho tích hợp mới): tìm kiếm theo từ khóa, tìm kiếm bằng ảnh, lấy chi tiết sản phẩm, upload ảnh và tính phí vận chuyển trên Taobao và 1688.

Nếu bạn đang dùng phiên bản v1, xem API Sản phẩm v1 (Legacy). Để làm theo từng bước, xem Hướng dẫn tìm kiếm sản phẩm.

Tất cả endpoint đều là POST, yêu cầu header xác thực (JWT hoặc API Key), và yêu cầu tham số platform với giá trị taobao hoặc alibaba.

Tìm kiếm sản phẩm bằng từ khóa

POST /v2/products/search

Ví dụ request:

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

Tham số

Sắp xếp kết quả (sort)

Lọc kết quả (filter)

Giá trị ffmOutbound

Giá trị ffmDelivery

Giá trị newArrival

Giá trị sellerLevel

Tìm kiếm sản phẩm bằng ảnh

Lưu ý: Tính năng này không áp dụng với gói Miễn phí.

POST /v2/products/search-by-image

Có 2 cách tìm kiếm bằng ảnh, bắt buộc truyền 1 trong 2 tham số:

1. Tìm kiếm bằng URL ảnh — dùng tham số imgUrl

Chỉ có thể dùng link ảnh từ Alibaba: *.alicdn.com.

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

2. Tìm kiếm bằng ảnh upload — dùng tham số imgId

Upload ảnh trước qua API POST /v2/products/upload-image để nhận imageId, sau đó truyền vào imgId:

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

Tham số

* Bắt buộc truyền ít nhất một trong hai tham số imgUrl hoặc imgId.

Lấy thông tin chi tiết sản phẩm

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

Cả hai endpoint dùng chung cấu trúc request và trả về thông tin chi tiết sản phẩm. detail trả về chi tiết đầy đủ hơn, phù hợp khi cần dữ liệu 1688.

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

Tham số

Nếu gặp link rút gọn dạng https://e.tb.cn/h.hPY04k4RPfAco8F?tk=0CCI430IUqd, phải xử lý link trước để lấy link gốc — dùng API Unshorten link để lấy link gốc và ID sản phẩm.

Các loại giá sản phẩm

Cảnh báo: Nếu bạn hiển thị giá cho khách hàng trên extension/web/app, hãy bổ sung cảnh báo rằng giá có thể cao hơn giá xem trực tiếp trên Taobao/1688. Nếu phát hiện giá trên API cao hơn, liên hệ CSKH để được hỗ trợ điều chỉnh giá khi tạo đơn mua hàng.

Taobao: ưu tiên hiển thị và áp dụng giá khuyến mãi; nếu không có, dùng giá thông thường.

1688: logic áp dụng giá phụ thuộc vào trường quote_type:

Các cấp độ người bán trên 1688

Cấp độ dùng để xác định uy tín người bán trên 1688, xác định qua trường seller_type:

Giải thích các trường trong extra_info

Tính phí vận chuyển

Chỉ áp dụng cho 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"
  }
}

Tham số

Response chứa post_fee (phí vận chuyển, đơn vị CNY), currency, item_id, mi_id, item_resource.

Upload ảnh

Dùng để lấy imageId phục vụ tìm kiếm bằng ảnh (tham số imgId).

POST /v2/products/upload-image

Request dạng multipart/form-data:

Response: { "imageId": "image-123" }.

Cấu trúc response

Tên field trong response dùng dạng snake_case. Mỗi platform trả về một cấu trúc sản phẩm riêng:

• find / detail → một object sản phẩm (Product)
• search / search-by-image → { "paginate": { "total", "current", "size" }, "items": [...] } (mục paginate có thể vắng mặt khi không có thông tin phân trang)

Các field chung (có trên cả hai platform)

Các field riêng của 1688

Ngoài các field chung, response 1688 bổ sung thêm các field sau (nhóm theo chủ đề):

• Giá: price_range, channel_price, promotion_model, fenxiao_sale_info, is_jxhy
• Media: video_urls, white_image, translated_img_urls, translated_white_image
• Dịch ngôn ngữ: description_en, unit_en
• Lượt mua / đánh giá: sold, review, level
• Vận chuyển: shipping_info
• Danh mục: top_category_id, second_category_id, third_category_id
• Định danh & link: mp_id, item_type, batch_number, product_cargo_number, original_product_url, seller_shop_url, promotion_url
• Metadata: selling_point, offer_identities, create_date, is_select, certificate_list, seller_mix_setting
• Khác: extra_info, sku_price_ranges

Lưu ý: Một field vắng mặt hoàn toàn trong response nghĩa là field đó không thuộc platform bạn đang gọi. Một field có giá trị null nghĩa là không có dữ liệu cho field đó trong request này.

Danh sách field đầy đủ và mô tả chi tiết: Swagger API.

Câu hỏi thường gặp (FAQ)

Tại sao giá sản phẩm lấy qua API khác với giá khi xem trên website Taobao/1688?

1. API chúng tôi sử dụng thuộc hệ thống logistics xuyên biên giới của Alibaba, giá được xác định độc lập — tách biệt với giá hiển thị trên website.
2. Khác với API, website phân biệt được khách mới và khách cũ, do đó có thể áp dụng khuyến mãi hoặc voucher theo nhóm người dùng — khả năng mà API không hỗ trợ.

Có môi trường thử nghiệm không?

Không. Tài khoản mặc định đã được thêm 200 requests miễn phí để tích hợp thử nghiệm.

Dữ liệu có realtime không?

Có, dữ liệu được lấy trực tiếp từ Taobao và 1688.

Có hỗ trợ tìm kiếm bằng hình ảnh không?

Có, hỗ trợ tìm kiếm bằng link ảnh và ảnh upload.

Liên kết liên quan

• Làm theo: Hướng dẫn tìm kiếm sản phẩm
• Legacy: API Sản phẩm v1 (Legacy)
• Công cụ: Elim CLI — tìm kiếm sản phẩm từ terminal
• API Reference đầy đủ: openapi.elim.asia/api