ĐẶ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:

1. Tìm kiếm Từ khóa & Bộ lọc (Text Search):

   • Đường dẫn RESTful (Khuyến nghị sử dụng qua Gateway):
     POST /api/v2/{lang}/{storeId}/products/search
     (Thứ tự tham số: {lang} mã ngôn ngữ vi | en | ko, tiếp đến {storeId} mã chi nhánh vd nsg)
   • Đường dẫn Canonical (Chuẩn dịch vụ nội bộ):
     POST /v2/p/mart/es/{storeId}/{lang}/products/search
     (Thứ tự tham số: {storeId} trước, {lang} sau)

2. Tìm kiếm bằng Hình ảnh (Image Search):

   • Đường dẫn RESTful (Qua Gateway):
     POST /api/v2/{lang}/{storeId}/products/search-by-image
   • Đường dẫn Canonical (Dịch vụ nội bộ):
     POST /v2/p/mart/es/{storeId}/{lang}/products/search-by-image

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 nhóm bộ lọc khác nhau áp dụng toán tử AND.

Danh sách 8 Thuộc tính Động chuẩn hóa được hỗ trợ trong filters.attrs:

1. country_of_manufacture (string[]): Nơi sản xuất / Xuất xứ (vd: ["Việt Nam", "Hàn Quốc"]).
2. size (string[]): Kích thước / Dung tích (vd: ["1L", "180ml"]).
3. material (string[]): Chất liệu sản phẩm (vd: ["Cotton", "Inox"]).
4. unit (string[]): Đơn vị đóng gói (vd: ["Hộp", "Lốc", "Thùng"]).
5. brand_origin (string[]): Xuất xứ thương hiệu (vd: ["Việt Nam", "Nhật Bản"]).
6. sub_brand (string[]): Nhánh thương hiệu con (vd: ["Ông Thọ", "Ngôi Sao Phương Nam"]).
7. enable_gift_wraping (string[]): Có hỗ trợ gói quà không (["Yes"] hoặc ["No"] / ["true"] / ["false"] / ["1"] / ["0"]). (Chú ý: tên key có 1 chữ 'p' theo index).
8. is_installation (string[]): Có dịch vụ lắp đặt không (["Yes"] hoặc ["No"]).

CẢNH BÁO QUAN TRỌNG: Backend áp dụng cơ chế DisallowUnknownFields. Tuyệt đối không gửi các key thuộc tính ngoài danh sách 8 key trên (như pack_type, volume, flavor...) — server sẽ từ chối ngay lập tức bằng HTTP 400 Bad Request.

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 thẻ sản phẩm: Phải sử dụng đúng cú pháp products.<tên_trường> theo JSON tag của ProductCard:
  products.productId, products.sku, products.name, products.urlKey, products.brand, products.brandId, products.category, products.categoryIds, products.price, products.originalPrice, products.currency, products.inStock, products.stockQty, products.promotion, products.imageUrl, products.sponsored, products.pinned.
  (Lưu ý: Không dùng products.id vì backend không có trường này và sẽ bị bỏ qua).
• Quy tắc tối ưu băng thông:
  • Trang 1: Gửi fields: ["products", "facets", "suggestedFilters"] để render thẻ sản phẩm và toàn bộ thanh bộ lọc.
  • Trang 2 trở đi (Infinite scroll): Chỉ 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 thẻ 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:

LƯU Ý QUAN TRỌNG: Các trường như discountRate, rating, reviewCount, deliveryMethod, isNew, isBest, isPromotion, tags HOÀN TOÀN KHÔNG CÓ TRÊN THẺ SẢN PHẨM CỦA SEARCH API. Frontend không bind data theo các trường này để tránh bị lỗi undefined.

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

Đối tượng facets chứa số lượng đếm để render sidebar và các chip lọc:

Cấu trúc phần tử Bucket thông thường:

{
  "value": "Vinamilk",  // Giá trị định danh để gửi lên filters (CHÚ Ý: là "value", KHÔNG PHẢI "key"!)
  "label": "Vinamilk",  // Tên hiển thị thân thiện trên UI
  "count": 45           // Số lượng sản phẩm khớp
}

Cấu trúc phần tử PriceBucket (Khoảng giá):

{
  "from": 0,            // Giá bắt đầu
  "to": 50000,          // Mốc chặn trên (dùng hiển thị label: "0 – 50.000 đ")
  "max": 49999,         // Giá tối đa thực tế (gửi lên filters.priceMax)
  "count": 22           // Số lượng sản phẩm
}

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", "suggestedFilters"]
  }'

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"],
      "benefitFlags": ["free_gifts"],
      "attrs": {
        "country_of_manufacture": ["Việt Nam"]
      }
    },
    "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": "cur_eyJvIjoyMCwicCI6Mn0",
    "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",
  "page": 1,
  "pageSize": 20,
  "pageCeiling": 3,
  "hasMore": true,
  "nextCursor": "cur_eyJvIjoyMCwicCI6Mn0",
  "redirect": null,
  "suggestedFilters": ["Ít Đường", "Có Đường", "1L"],
  "resolvedMode": "hybrid",
  "corrected": false,
  "normalizedQuery": "sữa tươi",
  "products": [
    {
      "productId": "8934673123456",
      "sku": "8934673123456",
      "name": "Sữa Tươi Tiệt Trùng Vinamilk 100% Ít Đường 1L",
      "urlKey": "sua-tuoi-tiet-trung-vinamilk-100-it-duong-1l",
      "brand": "Vinamilk",
      "brandId": "Vinamilk",
      "category": "Sữa Tươi Tiệt Trùng",
      "categoryIds": ["110", "11001"],
      "price": 36500,
      "originalPrice": 41000,
      "currency": "VND",
      "inStock": true,
      "stockQty": 50,
      "promotion": "Giảm 11%",
      "labels": [],
      "imageUrl": "https://img.martonline.lotte.vn/p/8934673123456.jpg",
      "sponsored": false,
      "pinned": false
    }
  ],
  "facets": {
    "viTags": [
      { "value": "Sữa Tươi", "label": "Sữa Tươi", "count": 45 },
      { "value": "Ít Đường", "label": "Ít Đường", "count": 18 }
    ],
    "brands": [
      { "value": "Vinamilk", "label": "Vinamilk", "count": 45 }
    ],
    "priceRanges": [
      { "from": 0, "to": 50000, "max": 49999, "count": 30 },
      { "from": 50000, "to": 100000, "max": 99999, "count": 15 }
    ],
    "attrs": {
      "country_of_manufacture": [
        { "value": "Việt Nam", "label": "Việt Nam", "count": 45 }
      ]
    }
  }
}

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à pin thiết bị di động:

• 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ị kỹ thuật: Khóa tỷ lệ ảnh vuông 1:1 (~800×800px) trên UI crop ảnh của app để trích xuất vector AI chính xác nhất).
• 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",           // Bắt buộc gửi rõ "cursor" nếu muốn cuộn trang
    "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 xem 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": "cur_eyJvIjoyMCwicCI6Mn0",    // nextCursor từ trang trước (có tiền tố cur_)
  "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. Mã lỗi đặc thù của Image Search

• 404 Not Found (Mã lỗi IMAGE_SEARCH_DISABLED): Trả về khi tính năng tìm kiếm bằng ảnh bị tắt qua cấu hình hệ thống (feature.image_search). Frontend cần ẩn nút camera tìm kiếm ảnh hoặc thông báo tính năng đang bảo trì.

6.5. 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": "cur_eyJvIjoyMCwicCI6Mn0",
    "pageSize": 20,
    "fields": ["products"]
  }'