Giới thiệu

Name: OneEntry SDK
Author: OneEntry

Quản lý sản phẩm thương mại điện tử với các danh mục động, bộ lọc và tìm kiếm.

Thông tin thêm về Danh mục trong bảng điều khiển quản trị OneEntry: https://doc.oneentry.cloud/docs/category/catalog

🎯 Mô-đun này làm gì?

Mô-đun Products (Danh mục) cho phép bạn lấy, lọc, tìm kiếm và sắp xếp sản phẩm trong cửa hàng trực tuyến hoặc bộ sưu tập đa phương tiện của bạn. Bạn quản lý danh mục trong bảng điều khiển quản trị OneEntry (Danh mục > Sản phẩm); ứng dụng của bạn lấy sản phẩm một cách động, vì vậy việc thay đổi giá hoặc thuộc tính trong quản trị sẽ có hiệu lực ngay mà không cần triển khai lại.

Ngoài thương mại điện tử, Danh mục cũng phù hợp với các phòng trưng bày đa phương tiện, danh mục đầu tư, thư viện tài liệu và các bộ sưu tập nội dung khác.

🚀 Khởi động nhanh

Khởi tạo mô-đun từ defineOneEntry:


const { Products } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Lấy một trang sản phẩm và đọc các trường của chúng:

// Fetch the first 20 products (empty body = no filters).
const { items, total } = await Products.getProducts([], "en_US", { limit: 20 });

console.log(`Loaded ${items.length} of ${total} products`);

items.forEach((product) => {
  console.log(product.id, product.localizeInfos.title, product.price);
});

Hầu hết các phương thức liệt kê đều có cùng hình dạng: một bộ lọc tùy chọn body, một langCode, và một userQuery tùy chọn (phân trang/sắp xếp). Xem Tham số bên dưới để biết đầy đủ.

✨ Khái niệm chính

Sản phẩm là gì?

Một sản phẩm là một thực thể danh mục (IProductsEntity) bao gồm:

Thông tin cơ bản - localizeInfos (tiêu đề, v.v.), sku, giá
Hình ảnh - ảnh sản phẩm / bộ sưu tập (được lưu trữ dưới dạng thuộc tính)
Thuộc tính tùy chỉnh - bất kỳ trường nào bạn định nghĩa (attributeValues): thương hiệu, chất liệu, kích thước, màu sắc, biến thể, tồn kho, …
Địa phương hóa - nội dung theo ngôn ngữ

Không có loại sản phẩm cố định trong SDK — bất kỳ cấu trúc nào (biến thể, tùy chọn, tải xuống, gói) đều được mô hình hóa với các thuộc tính tùy chỉnh mà bạn cấu hình cho danh mục.

Tổ chức sản phẩm

Sản phẩm được tổ chức thông qua một số tính năng của danh mục:

Danh mục - các phần của danh mục (các trang loại Danh mục, được tạo trong Mô-đun Trang)
Trạng thái sản phẩm - các điều kiện lọc bổ sung ngoài các bộ lọc thuộc tính (ví dụ: "còn hàng", "giảm giá")
Liên kết sản phẩm - kết nối các sản phẩm theo tiêu chí thuộc tính (ví dụ: tất cả điện thoại màu đen cùng nhau)
Bộ lọc sản phẩm - tìm kiếm nhanh theo tiêu chí bộ lọc đã chỉ định
Thuộc tính tùy chỉnh - thương hiệu, kích thước, màu sắc, chất liệu, …

Ví dụ về cấu trúc:

📁 Electronics
  ├─ 📱 Smartphones
  │   ├─ iPhone 15 Pro
  │   └─ Samsung Galaxy S24
  └─ 💻 Laptops
      ├─ MacBook Pro
      └─ Dell XPS

📁 Clothing
  ├─ 👕 T-Shirts
  └─ 👖 Jeans

📋 Những điều bạn cần biết

Kiến trúc danh mục

Các danh mục trong danh mục là các trang loại Danh mục được tạo thông qua Mô-đun Trang — tạo chúng trước khi thêm sản phẩm:

Mở Mô-đun Trang trong bảng điều khiển quản trị.
Tạo các trang với loại Danh mục — những trang này trở thành danh mục sản phẩm của bạn.
Thêm sản phẩm vào các danh mục đó qua Danh mục > Sản phẩm.

Danh mục quản trị cũng cung cấp Tải lên Danh mục hàng loạt, Bộ lọc Sản phẩm, Liên kết Sản phẩm, Trạng thái Sản phẩm, và Cài đặt theo danh mục.

Phân trang

Đừng tải tất cả cùng một lúc — phân trang qua kết quả với limit và offset:

Công thức Offset: offset = (pageNumber - 1) * limit

Giới hạn mặc định: bạn có thể lấy 10 đối tượng theo mặc định. Để phân trang qua nhiều hơn, cấu hình Quyền mô-đun theo nhu cầu của bạn.

Sắp xếp

Truyền sortKey và sortOrder trong userQuery:

sortKey	Chức năng	Ví dụ sử dụng
price	Sắp xếp theo giá	Hiển thị sản phẩm rẻ nhất trước
date	Sắp xếp theo ngày tạo	Hiển thị sản phẩm mới nhất
title	Sắp xếp theo thứ tự chữ cái	Danh sách sản phẩm A-Z
position	Thứ tự tùy chỉnh (mặc định)	Thứ tự được chọn từ quản trị
id	Sắp xếp theo ID	Sắp xếp kỹ thuật

Thứ tự sắp xếp: ASC (tăng dần) hoặc DESC (giảm dần, mặc định).

Lọc

Lọc được thực hiện thông qua body yêu cầu (một mảng IFilterParams), không phải userQuery. Mỗi điều kiện kết hợp một attributeMarker, một conditionMarker (eq, neq, in, nin, mth, lth, exs, nexs), và một conditionValue. Kết hợp nhiều điều kiện trong mảng để lọc theo nhiều tiêu chí cùng một lúc. Tham khảo đầy đủ điều kiện trong Tham số bên dưới.

📊 Bảng tham khảo nhanh - Các phương thức phổ biến

Phương thức	Mô tả	Trường hợp sử dụng
getProducts()	Lấy tất cả sản phẩm với bộ lọc/sắp xếp	Trang danh mục chính
getProductById()	Lấy sản phẩm đơn lẻ theo ID	Trang chi tiết sản phẩm
getProductsByPageId()	Lấy sản phẩm từ danh mục theo ID trang	Trang danh mục
getProductsByPageUrl()	Lấy sản phẩm từ danh mục theo URL trang	Trang danh mục theo URL
getRelatedProductsById()	Lấy sản phẩm liên quan/tương tự	Phần "Bạn cũng có thể thích"
searchProduct()	Tìm kiếm sản phẩm theo truy vấn	Chức năng tìm kiếm
getProductsCount()	Lấy tổng số sản phẩm	Thông tin phân trang
getProductsCountByPageId()	Lấy số lượng sản phẩm theo ID danh mục	Phân trang danh mục
getProductsCountByPageUrl()	Lấy số lượng sản phẩm theo URL danh mục	Phân trang danh mục
getProductBlockById()	Lấy khối sản phẩm theo ID	Các khối nội dung sản phẩm
getProductsEmptyPage()	Lấy cấu trúc trang sản phẩm trống	Xử lý trạng thái trống
getProductsPriceByPageUrl()	Lấy giá sản phẩm theo URL trang	Lọc theo giá
getProductsByIds()	Lấy sản phẩm theo danh sách ID	Giỏ hàng, danh sách yêu thích, so sánh
getProductsByVectorSearch()	Tìm kiếm ngữ nghĩa (vector) cho sản phẩm	Tìm kiếm sử dụng AI

Tham số

Mô-đun này chấp nhận một tập hợp các tham số người dùng gọi là userQuery. Nếu một tham số không được truyền, giá trị mặc định của nó sẽ được áp dụng. Một số phương thức cũng chấp nhận một body để lọc — truyền một mảng rỗng (hoặc không gì cả) khi bạn không cần bộ lọc.


const userQuery = {
    offset: 0,
    limit: 30,
    sortOrder: 'DESC',
    sortKey: 'id',
    signPrice: 'orders',
}

Lưu ý: hình dạng của userQuery phụ thuộc vào phương thức. Các trường ở trên là cơ sở chung (IProductsQueryBase), được sử dụng bởi getProducts, getProductsByPageId, getProductsByPageUrl và getProductsEmptyPage. Các phương thức khác khác nhau: getRelatedProductsById cũng chấp nhận statusMarker và templateMarker; getProductsPriceByPageUrl cũng chấp nhận statusMarker (không có sortKey); getProductsByIds chỉ chấp nhận signPrice. Lọc (attributeMarker / conditionMarker / conditionValue) được thực hiện thông qua body yêu cầu, không phải userQuery — xem bên dưới.

Schema

offset: số
Tham số phân trang. Mặc định 0
ví dụ: 0

limit: số
tham số phân trang. Mặc định 30
ví dụ: 30

sortKey: chuỗi
Trường để sắp xếp (mặc định không đặt - sắp xếp theo vị trí, các giá trị có thể: id, title, date, price, position)
Các giá trị có sẵn: id, position, title, date, price

sortOrder: chuỗi
thứ tự sắp xếp DESC | ASC (mặc định DESC)
ví dụ: "DESC"

signPrice: chuỗi
Dấu hiệu lưu trữ đơn hàng để cố định giá. Nếu tham số được đặt, giá sẽ được cố định trong một khoảng thời gian nhất định (xem phần Cố định giá bên dưới).
ví dụ: "orders"

Các trường cụ thể cho phương thức: statusMarker (getRelatedProductsById, getProductsPriceByPageUrl) và templateMarker (getRelatedProductsById) — chuỗi | null, mặc định null.

Sử dụng các điều kiện để tìm dữ liệu sản phẩm cụ thể:

attributeMarker: Định danh văn bản của thuộc tính đã được lập chỉ mục mà theo đó các giá trị được lọc. conditionMarker: Loại điều kiện áp dụng cho giá trị thuộc tính.

Marker	Ý nghĩa	Ví dụ
eq	Bằng	statusId = 1 (chỉ hoạt động)
neq	Không bằng	category ≠ "archived"
in	Chứa (một trong số)	category in ["electronics", "books"]
nin	Không chứa	brand not in ["fake_brand"]
mth	Lớn hơn	price > 100
lth	Nhỏ hơn	stock < 10
exs	Tồn tại (có giá trị)	Có mô tả
nexs	Không tồn tại	Không có hình ảnh

conditionValue: Giá trị để so sánh.

Cố định giá (signPrice)

Khi bạn lấy sản phẩm, bạn có thể truyền một tham số signPrice tùy chọn bên trong userQuery (nó cũng là một đối số trong các phương thức gợi ý của Mô-đun Blocks). Nó chấp nhận dấu hiệu của một lưu trữ đơn hàng và yêu cầu máy chủ khóa giá đã trả về trong một khoảng thời gian giới hạn.

signPrice — loại chuỗi

Dấu hiệu lưu trữ đơn hàng để cố định giá. Nếu tham số được đặt, giá sẽ được cố định trong một khoảng thời gian nhất định.

Tại sao sử dụng nó. Giá có thể thay đổi trong khi khách hàng đang mua sắm — một chương trình giảm giá bắt đầu, hoặc một quản trị viên chỉnh sửa giá. signPrice đảm bảo rằng giá hiển thị trong danh mục hoặc giỏ hàng chính xác là giá được tính khi thanh toán, vì vậy nó không thể thay đổi giữa việc duyệt và đặt hàng.

Cách hoạt động:

Lấy sản phẩm với signPrice được đặt thành dấu hiệu lưu trữ đơn hàng của bạn (ví dụ "orders").
Mỗi sản phẩm trả về bây giờ mang một trường signedPrice — một mã token đã ký mã hóa giá đã khóa.
Gửi mã token signedPrice đó lại khi bạn tạo đơn hàng, để máy chủ tôn trọng giá cố định.


const { items } = await Products.getProducts([], "en_US", {
  signPrice: "orders"
});

const signedPrice = items[0].signedPrice;

➡️ Mã token trả về được sử dụng bởi createOrder(). Xem nơi lấy nó và cách truyền nó trong phần Giá sản phẩm cố định (signedPrice) của Mô-đun Đơn hàng.

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

Tôi có thể lọc theo nhiều tiêu chí cùng một lúc không?

Có — truyền nhiều điều kiện trong mảng body; chúng sẽ được kết hợp lại:

const { items } = await Products.getProducts(
  [
    { attributeMarker: "price", conditionMarker: "mth", conditionValue: 100 },
    { attributeMarker: "brand", conditionMarker: "in", conditionValue: ["apple", "samsung"] },
  ],
  "en_US",
);

Tôi xử lý các biến thể sản phẩm (kích thước, màu sắc) như thế nào?

Các biến thể được lưu trữ trong attributeValues của sản phẩm — đọc chúng từ đối tượng sản phẩm đã lấy. Cấu trúc là bất kỳ bộ thuộc tính nào bạn đã cấu hình cho danh mục.

Tôi thực hiện nút "Tải thêm" như thế nào?

Tăng offset theo limit mỗi khi nhấp và thêm các items mới vào danh sách của bạn (sử dụng total để biết khi nào dừng lại).

Tôi có thể hiển thị sản phẩm từ nhiều danh mục không?

Có — lọc với thuộc tính category và dấu hiệu điều kiện in, truyền danh sách các giá trị danh mục.

Tôi thực hiện phần "Sản phẩm mới" như thế nào?

Sắp xếp theo ngày tạo: userQuery: { sortKey: "date", sortOrder: "DESC" }.

🎓 Thực hành tốt nhất

Luôn phân trang (limit + offset) — không bao giờ lấy toàn bộ danh mục cùng một lúc.
Lưu trữ danh sách sản phẩm cho các danh mục thường xuyên truy cập để giảm số lần gọi API.
Sử dụng signPrice khi giá được đưa vào giỏ hàng/thanh toán để giá không thể thay đổi.
Xử lý kết quả trống (total === 0) và các trường thiếu (price, hình ảnh) một cách hợp lý.

🔗 Tài liệu liên quan

Bảng điều khiển quản trị OneEntry - Danh mục - Tài liệu chính thức của bảng điều khiển quản trị
Mô-đun Trang - Tạo các danh mục danh mục (các trang loại Danh mục)
Mô-đun AttributesSets - Các trường và thuộc tính sản phẩm tùy chỉnh
Mô-đun Templates - Các mẫu hiển thị sản phẩm
Mô-đun Blocks - Các khối nội dung sản phẩm có thể tái sử dụng
Mô-đun Đơn hàng - Xử lý đơn hàng sản phẩm

🎯 Mô-đun này làm gì?​

🚀 Khởi động nhanh​

✨ Khái niệm chính​

Sản phẩm là gì?​

Tổ chức sản phẩm​

📋 Những điều bạn cần biết​

Kiến trúc danh mục​

Phân trang​

Sắp xếp​

Lọc​

📊 Bảng tham khảo nhanh - Các phương thức phổ biến​

Tham số​

Cố định giá (signPrice)​

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

Tôi có thể lọc theo nhiều tiêu chí cùng một lúc không?​

Tôi xử lý các biến thể sản phẩm (kích thước, màu sắc) như thế nào?​

Tôi thực hiện nút "Tải thêm" như thế nào?​

Tôi có thể hiển thị sản phẩm từ nhiều danh mục không?​

Tôi thực hiện phần "Sản phẩm mới" như thế nào?​

🎓 Thực hành tốt nhất​

🔗 Tài liệu liên quan​