Shopee: Tìm Kiếm Hình Ảnh

API cho phép tìm kiếm các sản phẩm tương đồng đang được bán trên sàn Shopee dựa trên hình ảnh đầu vào.

---

Thông Tin Endpoint

• Phương thức: POST
• Đường dẫn: /v1/shopee/search
• Định dạng dữ liệu: Content-Type: application/json
• Xác thực: Header X-API-Key (Yêu cầu quyền truy cập sàn shopee)

---

1. Hướng Dẫn Chuẩn Bị Cookie Shopee

Shopee yêu cầu xác thực phiên đăng nhập (Cookie) để thực hiện tính năng tìm kiếm bằng hình ảnh.

Cách lấy Cookie Shopee đơn giản:

1. Mở trình duyệt và truy cập https://shopee.vn (đã đăng nhập tài khoản bất kỳ).
2. Nhấn phím F12 (hoặc chuột phải chọn Kiểm tra / Inspect) -> Chuyển sang tab Network (Mạng).
3. Tìm kiếm một sản phẩm bất kỳ hoặc bấm vào một trang danh mục.
4. Chọn một request bất kỳ gửi tới shopee.vn, tìm mục Request Headers -> Tìm dòng cookie:.
5. Copy toàn bộ chuỗi cookie đó (chứa các token như SPC_EC=...; SPC_F=...) và gán vào trường cookie trong request của bạn.

---

2. Các Tham Số Request Body (JSON)

Tên trường	Kiểu dữ liệu	Bắt buộc	Mặc định	Ý nghĩa & Mô tả
cookie	string	Bắt buộc	-	Chuỗi Cookie Shopee hợp lệ (chứa session xác thực tìm kiếm)
image_key	string	Tùy chọn*	null	Mã hash ảnh đã có sẵn trên CDN Shopee (ví dụ: vn-11134207-7ras8-m427e1f48y0hbf)
image_url	string	Tùy chọn*	null	Đường dẫn URL công khai tới tệp ảnh cần tìm
image_base64	string	Tùy chọn*	null	Chuỗi mã hóa Base64 thuần của ảnh
country	string	Tùy chọn	VN	Thị trường cần tìm: VN, TH, MY, PH, SG, ID. Nếu bỏ trống, hệ thống sẽ tự suy đoán theo tiền tố ảnh
page	integer	Tùy chọn	1	Số trang kết quả cần lấy (phân trang)
proxy	string	Tùy chọn	null	Cấu hình HTTP Proxy dạng http://user:pass@host:port nếu muốn định tuyến IP riêng
bounding_box	object	Tùy chọn	null	Tọa độ khung cắt vật thể trong ảnh: {"x": 0.1, "y": 0.1, "width": 0.8, "height": 0.8}

IMPORTANT

Quy tắc về ảnh: Bạn phải cung cấp ít nhất 1 trong 3 trường: image_key, image_url, hoặc image_base64.

• Ưu tiên dùng image_key nếu bạn đang tìm kiếm dựa trên ảnh đã tồn tại sẵn trên Shopee (tốc độ xử lý nhanh nhất).
• Dùng image_url nếu ảnh nằm trên máy chủ/hosting bên ngoài.
• Dùng image_base64 nếu người dùng tải ảnh trực tiếp từ thiết bị của họ lên.

---

3. Ví Dụ Request

cURL (Dùng image_url)

curl -X POST "https://api.yourdomain.com/v1/shopee/search" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "cookie": "SPC_EC=your_cookie_here; SPC_F=your_spc_f_here...",
    "image_url": "https://example.com/sample-product.jpg",
    "country": "VN",
    "page": 1
  }'

cURL (Dùng image_key)

curl -X POST "https://api.yourdomain.com/v1/shopee/search" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "cookie": "SPC_EC=your_cookie_here...",
    "image_key": "vn-11134207-7ras8-m427e1f48y0hbf",
    "country": "VN",
    "page": 1
  }'

cURL (Dùng image_base64)

curl -X POST "https://api.yourdomain.com/v1/shopee/search" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "cookie": "SPC_EC=your_cookie_here...",
    "image_base64": "/9j/4AAQSkZJRgABAQEASABIAAD/2wBDAP...",
    "country": "VN",
    "page": 1
  }'

---

4. Cấu Trúc Response Trả Về

Phản hồi thành công (200 OK) trả về danh sách các sản phẩm tìm thấy:

{
  "code": 200,
  "message": "success",
  "data": {
    "items": [
      {
        "itemid": 23812984123,
        "shopid": 9871234,
        "name": "Áo Thun Cotton Form Rộng Unisex Phong Cách Hàn Quốc",
        "image": "vn-11134207-7ras8-m427e1f48y0hbf",
        "price": 149000,
        "price_min": 149000,
        "price_max": 189000,
        "historical_sold": 1542,
        "rating_star": 4.87,
        "shop_location": "Hà Nội"
      }
    ],
    "page": 1,
    "has_more": true
  }
}

Ý nghĩa các trường dữ liệu quan trọng:

• itemid: ID định danh duy nhất của sản phẩm trên Shopee.
• shopid: ID gian hàng người bán.
• name: Tiêu đề sản phẩm.
• image: Mã ảnh đại diện sản phẩm trên CDN Shopee.
• price: Giá bán hiện tại (đơn vị VNĐ).
• historical_sold: Số lượng sản phẩm đã bán thành công trong lịch sử.
• rating_star: Điểm đánh giá trung bình của sản phẩm (thang điểm 5).
• has_more: true nếu còn trang kết quả tiếp theo.

---

5. Cách Tạo Link Sản Phẩm & Link Ảnh Shopee

Từ dữ liệu trả về trong response, bạn có thể dễ dàng ghép thành đường dẫn trực tiếp:

🔗 Công thức Link Sản Phẩm:

https://shopee.vn/product/{shopid}/{itemid}

Ví dụ: Với shopid = 9871234 và itemid = 23812984123: 👉 https://shopee.vn/product/9871234/23812984123

🖼️ Công thức Link Ảnh Sản Phẩm (CDN Shopee):

https://down-vn.img.susercontent.com/file/{image}

Ví dụ: Với image = vn-11134207-7ras8-m427e1f48y0hbf: 👉 https://down-vn.img.susercontent.com/file/vn-11134207-7ras8-m427e1f48y0hbf