ĐẶC TẢ KỸ THUẬT API: SEARCH & FILTER (v2.6)

Dành cho: Frontend Engineering Team (Web, Mobile App)
Dịch vụ: AI Search Engine API — LOTTE Mart Vietnam
Phiên bản: 2.6.0 | Cập nhật: 11/10/2026 | Giao thức: JSON over HTTP/2

1. THÔNG TIN ENDPOINT & GATEWAY

• HTTP Method: POST
• Accept: application/json

1.1. Cấu trúc URL Endpoint (Đồng bộ tiền tố /api)

Hệ thống cung cấp 2 dịch vụ tìm kiếm qua API Gateway với định dạng URL đồng bộ:

1. Tìm kiếm Từ khóa & Bộ lọc (Text Search):
   • Canonical: POST /api/v2/{lang}/{storeId}/products/search
   • Alias: POST /api/v2/p/mart/es/{storeId}/{lang}/products/search
2. Tìm kiếm bằng Hình ảnh (Image Search):
   • Canonical: POST /api/v2/{lang}/{storeId}/products/search-by-image
   • Alias: POST /api/v2/p/mart/es/{storeId}/{lang}/products/search-by-image

Ghi chú tham số URL: {lang} là mã ngôn ngữ (vi | en | ko), {storeId} là mã siêu thị / kho (vd: nsg — LOTTE Mart Nam Sài Gòn).

1.2. Gateway Base URL (Môi trường DEV)

(Trong mạng nội bộ backend k8s / direct service: POST /api/v1/search)

2. REQUEST SPECIFICATION (THAM SỐ GỬI LÊN)

2.1. Cấu trúc JSON Request

2.2. Chi tiết các cách Filter (filters)

Tất cả các bộ lọc bắt buộc nằm trong đối tượng filters. Giữa các bộ lọc khác nhau áp dụng toán tử AND.

2.3. Chọn trường dữ liệu tối ưu (fields)

Frontend kiểm soát chính xác payload trả về bằng mảng fields:

• Khối cấp 1: "products", "facets", "suggestedFilters".
• Trường trong thẻ sản phẩm: products.<field> (vd: products.id, products.name, products.price, products.imageUrl, products.inStock...).
• Quy tắc tối ưu băng thông:
  • Trang 1: Gửi fields: ["products", "facets"] để lấy cả sản phẩm và cây bộ lọc.
  • Trang 2 trở đi (Infinite scroll): Gửi fields: ["products"] (bỏ qua tính toán facets, giảm 70% kích thước JSON).

3. RESPONSE SPECIFICATION (GIẢI THÍCH CHI TIẾT CÁC FIELD)

3.1. Các trường Siêu dữ liệu (Metadata)

Các trường này luôn luôn xuất hiện trong mọi response, không bị ảnh hưởng bởi tham số fields:

3.2. Danh sách sản phẩm (products[])

Mỗi phần tử trong mảng products đại diện cho một thẻ sản phẩm hoàn chỉnh:

3.3. Dữ liệu bộ lọc (facets)

Đối tượng facets chứa số lượng đếm (aggregation count) của các bộ lọc để render sidebar và chip lọc:

Mỗi phần tử FacetBucket có cấu trúc:

{
  "key": "Vinamilk",
  "count": 45,
  "label": "Vinamilk"
}

4. VÍ DỤ cURL VÀ RESPONSE THỰC TẾ

4.1. cURL: Tìm kiếm cơ bản (Trang đầu tiên)

curl -X POST "https://dev-gateway.martonline.lotte.vn/api/v2/vi/nsg/products/search" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "sữa tươi",
    "paginationMode": "cursor",
    "pageSize": 20,
    "fields": ["products", "facets"]
  }'

4.2. cURL: Tìm kiếm kết hợp đầy đủ Bộ lọc (Filters + Sort + Fields)

curl -X POST "https://dev-gateway.martonline.lotte.vn/api/v2/vi/nsg/products/search" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "sữa tươi",
    "paginationMode": "cursor",
    "pageSize": 20,
    "sort": "relevance",
    "filters": {
      "viTags": ["Sữa Tươi", "Ít Đường"],
      "brandId": "Vinamilk",
      "priceMin": 20000,
      "priceMax": 100000,
      "inStockOnly": true,
      "delivery": ["express"]
    },
    "fields": ["products", "facets"]
  }'

4.3. cURL: Cuộn trang tiếp theo (Infinite Scroll bằng Cursor)

curl -X POST "https://dev-gateway.martonline.lotte.vn/api/v2/vi/nsg/products/search" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "sữa tươi",
    "paginationMode": "cursor",
    "cursor": "ZXlKaGJHY2lPaUpTVXpVeE1pSXNJbXR...",
    "pageSize": 20,
    "fields": ["products"]
  }'

4.4. Response JSON mẫu thực tế (Trang 1):

HTTP/2 200 OK
Content-Type: application/json; charset=utf-8

{
  "queryId": "e3b0c442-98fc-1c14-9afe-432100000000",
  "totalHits": 45,
  "tookMs": 18,
  "paginationMode": "cursor",
  "pageSize": 20,
  "hasMore": true,
  "nextCursor": "ZXlKaGJHY2lPaUpTVXpVeE1pSXNJbXR...",
  "resolvedMode": "hybrid",
  "corrected": false,
  "normalizedQuery": "sữa tươi",
  "products": [
    {
      "id": "8934673123456",
      "name": "Sữa Tươi Tiệt Trùng Vinamilk 100% Ít Đường 1L",
      "price": 36500,
      "originalPrice": 41000,
      "discountRate": 11,
      "imageUrl": "https://img.martonline.lotte.vn/p/8934673123456.jpg",
      "brandId": "Vinamilk",
      "brandName": "Vinamilk",
      "categoryId": "11001",
      "categoryName": "Sữa Tươi Tiệt Trùng",
      "inStock": true,
      "rating": 4.8,
      "reviewCount": 124,
      "deliveryMethod": ["express", "standard"],
      "isPromotion": true,
      "tags": ["Sữa Tươi", "Ít Đường"]
    }
  ],
  "facets": {
    "viTags": [
      { "key": "Sữa Tươi", "count": 45, "label": "Sữa Tươi" },
      { "key": "Ít Đường", "count": 18, "label": "Ít Đường" }
    ],
    "brands": [
      { "key": "Vinamilk", "count": 45, "label": "Vinamilk" }
    ],
    "attrs": {
      "brand_origin": [
        { "key": "Vietnam", "count": 45, "label": "Việt Nam" }
      ]
    }
  }
}

5. MÃ LỖI HTTP & NGUYÊN NHÂN TỪ CHỐI (HTTP STATUS CODES)

6. ĐẶC TẢ TÌM KIẾM BẰNG HÌNH ẢNH (IMAGE SEARCH API)

6.1. Quy trình 2 pha (Two-phase Workflow)

Quy trình tìm kiếm ảnh được thiết kế tối ưu băng thông mạng và độ trễ theo 2 pha:

• Pha 1 (Trang đầu tiên): Client gửi request dạng multipart/form-data chứa file ảnh image và tham số lọc params (JSON). Response trả về danh sách sản phẩm cùng mã imageRef (vector cache key).
• Pha 2 (Trang 2+ Infinite Scroll): Client gửi request dạng application/json thông thường mang theo imageRef và cursor. Tuyệt đối không cần upload lại file ảnh, máy chủ tự động tra cứu vector đã tính toán trong bộ nhớ cache.

6.2. Cấu trúc Tham số Image Search

Pha 1: Upload ảnh (multipart/form-data)

• Part image (Bắt buộc): Binary dữ liệu ảnh (hỗ trợ image/jpeg, image/png, image/webp). Dung lượng tối đa 5MB (khuyến nghị Frontend / App resize cạnh dài về khoảng 800px trước khi upload).
• Part params (Tùy chọn): Chuỗi JSON định nghĩa các tiêu chí bổ trợ:
  JSON Payload Copy

  {
    "query": "loại không đường",          // (Tùy chọn) Text đi kèm để lọc hẹp trong kết quả ảnh
    "paginationMode": "cursor",           // Mặc định: "cursor"
    "pageSize": 20,                       // Số sản phẩm mỗi trang (mặc định 20, max 100)
    "filters": {                          // Bộ lọc (y hệt cấu trúc filters của Text Search)
      "inStockOnly": true,
      "brandId": "Vinamilk"
    },
    "fields": ["products", "facets"]      // Chọn trường cần nhận
  }
  

Pha 2: Phân trang tiếp theo (application/json)

Khi người dùng cuộn trang tiếp theo, gửi body JSON:

{
  "imageRef": "sha256:9f2a4c8e71b2d3...", // Token nhận từ response Pha 1 (BẮT BUỘC)
  "paginationMode": "cursor",
  "cursor": "ZXlKaGJHY2lPaUpTVXpVeE1pSXNJbXR...", // nextCursor từ trang trước
  "pageSize": 20,
  "fields": ["products"]                  // Tiết kiệm băng thông: chỉ lấy products
}

6.3. Các trường Response bổ sung cho Image Search

Response của Image Search kế thừa toàn bộ cấu trúc của Text Search (products[], facets, totalHits, tookMs, nextCursor, hasMore), kèm theo các trường đặc thù:

6.4. Ví dụ cURL Image Search Thực Tế

cURL Pha 1: Upload ảnh tìm kiếm lần đầu (Multipart)

curl -X POST "https://dev-gateway.martonline.lotte.vn/api/v2/vi/nsg/products/search-by-image" \
  -F "image=@san-pham.jpg;type=image/jpeg" \
  -F 'params={
    "paginationMode": "cursor",
    "pageSize": 20,
    "filters": {
      "inStockOnly": true
    },
    "fields": ["products", "facets"]
  }'

cURL Pha 2: Cuộn xem trang tiếp theo (JSON dùng imageRef)

curl -X POST "https://dev-gateway.martonline.lotte.vn/api/v2/vi/nsg/products/search-by-image" \
  -H "Content-Type: application/json" \
  -d '{
    "imageRef": "sha256:9f2a4c8e71b2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8",
    "paginationMode": "cursor",
    "cursor": "ZXlKaGJHY2lPaUpTVXpVeE1pSXNJbXR...",
    "pageSize": 20,
    "fields": ["products"]
  }'