Giới thiệu

Tạo và theo dõi đơn hàng của khách hàng trong toàn bộ quy trình thanh toán, thanh toán và thực hiện.

Thông tin thêm về giao diện người dùng của mô-đun https://doc.oneentry.cloud/docs/category/orders

---

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

Mô-đun Orders cho phép bạn tạo, quản lý và theo dõi đơn hàng của khách hàng — từ thanh toán đến thanh toán đến thực hiện. Bạn xây dựng giao diện giỏ hàng; mô-đun này biến giỏ hàng thành một đơn hàng, xem trước tổng số (giảm giá, phiếu giảm giá, tiền thưởng), theo dõi trạng thái và xử lý yêu cầu hoàn tiền.

Đơn hàng sống bên trong lưu trữ đơn hàng (các container bạn cấu hình trong bảng điều khiển quản trị) và được tham chiếu bởi một đánh dấu lưu trữ. Thanh toán được ủy quyền cho cổng thanh toán được cấu hình cho tài khoản thanh toán đã chọn — xem mô-đun Payments.

🚀 Bắt đầu nhanh

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

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

Tạo một đơn hàng trong một lưu trữ và đọc lại kết quả (cần xác thực):

// Create an order in the "order_storage_1" storage.
const order = await Orders.createOrder("order_storage_1", {
  formIdentifier: "orderForm",
  paymentAccountIdentifier: "cash",
  formData: [],
  products: [{ productId: 2957, quantity: 2 }],
});

console.log(order.id, order.totalSum, order.statusIdentifier);
// 179 "300.00" "inProgress"

✨ Khái niệm chính

Đơn hàng là gì?

Một Đơn hàng là một giao dịch mua hàng của khách hàng. Mỗi đối tượng đơn hàng mang theo:

• id — định danh đơn hàng
• storageId — lưu trữ đơn hàng mà nó thuộc về
• formIdentifier / formData — biểu mẫu đơn hàng và dữ liệu mà khách hàng đã gửi
• products — các mục hàng (productId, quantity, price, …)
• totalSum / currency — tổng đơn hàng và tiền tệ
• paymentAccountIdentifier — tài khoản thanh toán đã chọn
• paymentUrl — liên kết thanh toán cổng (hoặc null)
• statusIdentifier / isCompleted — trạng thái hiện tại
• createdDate — dấu thời gian

Cấu trúc đơn hàng

{
  id: 179,
  storageId: 1,
  createdDate: '2025-07-03T00:43:02.908Z',
  statusIdentifier: 'inProgress',
  formIdentifier: 'orderForm',
  formData: [
    { marker: 'order_name', type: 'string', value: 'Ivan' }
  ],
  attributeSetIdentifier: 'order_form',
  totalSum: '300.00',
  currency: 'USD',
  paymentAccountIdentifier: 'cash',
  paymentAccountLocalizeInfos: { title: 'Cash' },
  paymentUrl: null,
  products: [
    {
      id: 2957,
      title: 'Cosmo',
      sku: null,
      previewImage: null,
      price: 150,
      quantity: 2,
      isGift: false,
    },
  ],
  isCompleted: true,
}

Lưu trữ đơn hàng so với các đơn hàng cá nhân

Một lưu trữ đơn hàng là một container nhóm các đơn hàng liên quan (ví dụ: đơn hàng từ một biểu mẫu hoặc kênh bán hàng cụ thể). Các đơn hàng cá nhân là các giao dịch thực tế bên trong một lưu trữ. Bạn truy cập một lưu trữ bằng đánh dấu của nó và một đơn hàng bên trong nó bằng đánh dấu + id.

Trạng thái đơn hàng

Mỗi lưu trữ xác định bộ trạng thái riêng của nó; trạng thái hiện tại của một đơn hàng nằm trong statusIdentifier. Lấy các trạng thái có sẵn cho một lưu trữ với getAllStatusesByStorageMarker(), và cập nhật trạng thái của một đơn hàng với updateOrderByMarkerAndId().

---

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

Đơn hàng được xây dựng từ dữ liệu giỏ hàng

Bạn cung cấp dữ liệu biểu mẫu đơn hàng và các mục hàng; OneEntry tính toán tổng số. Để tạo một đơn hàng, bạn truyền:

1. formIdentifier — biểu mẫu đơn hàng
2. formData — các trường biểu mẫu mà khách hàng đã gửi
3. products — các mục hàng (productId, quantity, tùy chọn signedPrice)
4. paymentAccountIdentifier — cách mà khách hàng sẽ thanh toán

Những gì mô-đun làm và không làm

• ✅ Tạo đơn hàng từ dữ liệu giỏ hàng, xem trước tổng số, cập nhật trạng thái, quản lý yêu cầu hoàn tiền
• ✅ Ủy quyền thanh toán cho cổng thông qua phiên thanh toán / paymentUrl
• ❌ Không cung cấp giao diện giỏ hàng — bạn xây dựng điều đó
• ❌ Không lưu trữ dữ liệu thẻ thô — thanh toán được xử lý bởi cổng

Hoàn tiền

Xử lý hoàn tiền sống trong mô-đun Orders: yêu cầu hoàn tiền với createRefundRequest(), liệt kê các yêu cầu hoàn tiền của một đơn hàng với getRefunds(), và hủy một yêu cầu với cancelRefundRequest().

---

📊 Bảng tham khảo nhanh

Phương thức	Mô tả
createOrder() 🔐	Tạo đơn hàng mới
getAllOrdersByMarker() 🔐	Lấy tất cả các đơn hàng cho một lưu trữ (phân trang)
getOrdersStorageByMarker() 🔐	Lấy một đối tượng lưu trữ đơn hàng theo đánh dấu.
getAllOrdersStorage() 🔐	Lấy tất cả các đối tượng lưu trữ đơn hàng.
getOrderByMarkerAndId() 🔐	Lấy một đơn hàng theo đánh dấu và id từ đối tượng lưu trữ đơn hàng do người dùng tạo.
updateOrderByMarkerAndId() 🔐	Cập nhật một đơn hàng theo đánh dấu và id từ đối tượng lưu trữ đơn hàng do người dùng tạo.
previewOrder() 🔐	Xem trước tổng số đơn hàng, giảm giá và phiếu giảm giá trước khi tạo.
getAllStatusesByStorageMarker()	Lấy tất cả các trạng thái đơn hàng cho một đánh dấu lưu trữ.
getRefunds()	Lấy tất cả các yêu cầu hoàn tiền cho một đơn hàng.
createRefundRequest()	Tạo một yêu cầu hoàn tiền cho một đơn hàng.
cancelRefundRequest()	Hủy một yêu cầu hoàn tiền cho một đơn hàng.

🔐 = Cần xác thực

---

Giá sản phẩm cố định (signedPrice)

signedPrice là một token đã ký khóa giá của sản phẩm. Khi nó có mặt trên một dòng đơn hàng, máy chủ sẽ tính phí theo giá cố định đó thay vì tìm kiếm giá một lần nữa — vì vậy số tiền mà khách hàng thấy trong danh mục hoặc giỏ hàng là số tiền họ phải trả.

signedPrice — loại string

Giá đã ký của sản phẩm được lấy cùng với dữ liệu sản phẩm khi signPrice được thiết lập.

Nơi lấy nó

Bạn không tự tạo signedPrice — nó đến bên trong dữ liệu sản phẩm, nhưng chỉ khi bạn yêu cầu các sản phẩm với tham số signPrice được thiết lập cho đánh dấu lưu trữ đơn hàng của bạn:

• Mô-đun Products — truyền signPrice trong userQuery (getProducts, getProductsByPageUrl, …).
• Mô-đun Blocks — truyền signPrice như một đối số phương pháp gợi ý (getCartSimilar, getRecentlyViewed, …).

Mỗi sản phẩm trả về sau đó chứa một chuỗi signedPrice. Đọc thêm trong phần Khóa giá (signPrice) của Mô-đun Products.

Cách sử dụng nó

Truyền token trở lại trong mỗi sản phẩm của thân createOrder(). Đơn hàng sau đó giữ giá cố định:

const { items } = await Products.getProducts([], "en_US", {
  signPrice: "my-order"
});
const body = {
  formIdentifier: "orderForm",
  paymentAccountIdentifier: "cash",
  formData: [],
  products: [
    {
      productId: items[0].id,
      quantity: 2,
      signedPrice: items[0].signedPrice
    }
  ]
};
const order = await Orders.createOrder("my-order", body);

Nếu bạn bỏ qua signedPrice, đơn hàng sẽ được tạo với giá hiện tại của sản phẩm tại thời điểm thanh toán.

---

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

Làm thế nào để tôi tạo một đơn hàng với nhiều sản phẩm?

Truyền một mảng các đối tượng sản phẩm trong trường products của thân đơn hàng. Mỗi mục cần productId và quantity (và tùy chọn signedPrice). Tổng số được tính toán tự động.

---

Tôi có thể cập nhật một đơn hàng sau khi nó đã được tạo không?

Có — sử dụng updateOrderByMarkerAndId() để sửa đổi chi tiết đơn hàng như trạng thái, dữ liệu biểu mẫu hoặc sản phẩm. Hãy cẩn thận khi thay đổi các mục hoặc tổng số khi thanh toán đang được tiến hành.

---

Làm thế nào để tôi theo dõi sự thay đổi trạng thái đơn hàng?

Đọc trường statusIdentifier để biết trạng thái hiện tại, và lấy các trạng thái có sẵn của lưu trữ với getAllStatusesByStorageMarker(). Bạn cũng có thể sử dụng Mô-đun Events để phản ứng với các thay đổi.

---

Sự khác biệt giữa lưu trữ đơn hàng và các đơn hàng cá nhân là gì?

Lưu trữ đơn hàng là một container nhóm các đơn hàng liên quan (ví dụ: đơn hàng từ một biểu mẫu hoặc kênh bán hàng cụ thể). Các đơn hàng cá nhân là các giao dịch bên trong lưu trữ đó. Sử dụng các đánh dấu để xác định và tổ chức các lưu trữ.

---

Làm thế nào để tôi xử lý việc hủy đơn hàng và hoàn tiền?

Cập nhật trạng thái đơn hàng với updateOrderByMarkerAndId(). Đối với hoàn tiền, sử dụng các phương thức hoàn tiền của Orders: createRefundRequest() để yêu cầu một, getRefunds() để liệt kê các yêu cầu của một đơn hàng, và cancelRefundRequest() để hủy một yêu cầu.

---

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

• Xem trước trước khi tạo — gọi previewOrder() để hiển thị giảm giá, phiếu giảm giá và tiền thưởng trong tóm tắt thanh toán.
• Sử dụng signedPrice khi các sản phẩm được đưa vào thanh toán để giá không bị thay đổi giữa việc duyệt và đặt hàng.
• Xác thực trước — các phương thức tạo/đọc/cập nhật đơn hàng yêu cầu người dùng đã được xác thực (xem AuthProvider).
• Phân trang danh sách đơn hàng (offset + limit) — không tải tất cả các đơn hàng cùng một lúc.
• Tham chiếu các lưu trữ và biểu mẫu bằng đánh dấu, không phải bằng tên hiển thị — các đánh dấu là ổn định.

---

🔗 Tài liệu liên quan

• Mô-đun Products - Quản lý các sản phẩm có sẵn để mua
• Mô-đun Payments - Tạo các phiên thanh toán cho các đơn hàng
• Mô-đun Users - Quản lý khách hàng đặt hàng
• Mô-đun AuthProvider - Cần thiết để xác thực các phương thức đơn hàng
• Mô-đun Events - Thông báo trạng thái đơn hàng

---