Giới thiệu

🎯 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ừ việc thanh toán giỏ hàng đến xử lý thanh toán và hoàn tất đơn hàng - xử lý toàn bộ vòng đời đơn hàng thương mại điện tử.

Hãy coi nó như hệ thống quản lý đơn hàng của bạn - khách hàng thêm sản phẩm vào giỏ, đặt hàng, thực hiện thanh toán, và bạn theo dõi mọi thứ từ việc tạo đơn hàng đến giao hàng, tất cả trong OneEntry.

📖 Giải thích đơn giản

Mỗi ứng dụng thương mại điện tử đều cần quản lý đơn hàng:

🛒 Giỏ hàng - Người dùng thêm sản phẩm, tiến hành thanh toán
📋 Tạo đơn hàng - Chuyển giỏ hàng thành đơn hàng với thông tin khách hàng
💳 Xử lý thanh toán - Chấp nhận thanh toán (thẻ tín dụng, PayPal, v.v.)
📦 Theo dõi đơn hàng - Theo dõi trạng thái (đang chờ, đang xử lý, đã gửi, đã giao)
📊 Quản lý đơn hàng - Xem tất cả đơn hàng, lọc theo trạng thái, tìm kiếm
🧾 Chi tiết đơn hàng - Xem các mặt hàng, tổng số, thông tin khách hàng

Vấn đề:

🔒 Không tích hợp thanh toán - Theo dõi thanh toán thủ công
📊 Theo dõi kém - Khó tìm đơn hàng, lọc theo trạng thái
🔄 Không tự động hóa - Cập nhật trạng thái thủ công, không có thông báo
💸 Không tính thuế/giao hàng - Tính toán thủ công

Giải pháp Orders:

Lợi ích:

🔒 Thanh toán tích hợp - Stripe, PayPal, các cổng khác
📊 Theo dõi nâng cao - Lọc, tìm kiếm, xuất đơn hàng
🔄 Quy trình tự động - Cập nhật trạng thái, thông báo
💸 Tính toán tự động - Thuế, giao hàng, giảm giá

✨ 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 bao gồm:

Mặt hàng đơn hàng - Sản phẩm/dịch vụ được mua (số lượng, giá)
Thông tin khách hàng - Tên, email, điện thoại
Địa chỉ giao hàng - Địa điểm giao hàng
Địa chỉ thanh toán - Thông tin thanh toán
Chi tiết thanh toán - Phương thức thanh toán, ID giao dịch
Tổng đơn hàng - Tổng phụ, thuế, giao hàng, tổng cộng
Trạng thái đơn hàng - Tình trạng hiện tại (đang chờ, đang xử lý, đã hoàn thành)
Thời gian - Ngày tạo, cập nhật, hoàn thành

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

Mỗi đơn hàng có cấu trúc này:

{
  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' },
  products: [
    {
      id: 2957,
      title: 'Cosmo',
      sku: null,
      previewImage: null,
      price: 150,
      quantity: 2,
    },
  ],
  isCompleted: true,
}

Vòng đời đơn hàng

1. Customer adds items to cart
   ↓
2. Proceeds to checkout
   ↓
3. Enters shipping/billing info
   ↓
4. Selects payment method
   ↓
5. Order created (status: pending)
   ↓
6. Payment processed (status: processing)
   ↓
7. Order confirmed (status: confirmed)
   ↓
8. Items prepared (status: processing)
   ↓
9. Order shipped (status: shipped)
   ↓
10. Order delivered (status: completed)

Ví dụ về trạng thái đơn hàng

Trạng thái	Ý nghĩa	Khi nào sử dụng
đang chờ	Đơn hàng đã được tạo, đang chờ thanh toán	Vừa đặt, thanh toán chưa được xử lý
đang xử lý	Thanh toán đã được nhận, chuẩn bị hàng hóa	Thanh toán đã được xác nhận, đóng gói hàng hóa
đã xác nhận	Đơn hàng đã được xác nhận, sẵn sàng giao hàng	Thanh toán đã được xử lý, đơn hàng đã được xác minh
đã gửi	Đơn hàng đã được gửi đến khách hàng	Gói hàng đã được gửi qua đơn vị vận chuyển
đã giao	Đơn hàng đã được khách hàng nhận	Giao hàng đã được xác nhận
đã hoàn thành	Đơn hàng đã hoàn tất, không cần hành động gì	Giao dịch đã hoàn tất
đã hủy	Đơn hàng đã bị hủy	Khách hàng/admin đã hủy
đã hoàn tiền	Thanh toán đã được trả lại cho khách hàng	Hoàn tiền đã được xử lý
thất bại	Thanh toán hoặc xử lý đã thất bại	Thanh toán bị từ chối

Các thao tác đơn hàng phổ biến

Thao tác	Mô tả	Ví dụ sử dụng
Tạo đơn hàng	Chuyển giỏ hàng thành đơn hàng	Nhấn nút thanh toán
Lấy đơn hàng	Liệt kê tất cả đơn hàng (theo trang)	Bảng điều khiển admin
Lấy đơn hàng theo ID	Lấy đơn hàng cụ thể	Xem chi tiết đơn hàng
Cập nhật trạng thái	Thay đổi trạng thái đơn hàng	Đánh dấu là đã gửi
Tính toán tổng	Tính toán thuế, giao hàng, tổng	Tóm tắt thanh toán
Hủy đơn hàng	Hủy đơn hàng đang chờ	Khách hàng yêu cầu hủy
Hoàn tiền đơn hàng	Trả lại tiền cho khách hàng	Trả lại sản phẩm

Tại sao sử dụng mô-đun Orders?

Lợi ích	Mô tả
Quản lý đơn hàng tự động	Không cần theo dõi thủ công, mọi thứ đều tự động
Tích hợp thanh toán	Stripe, PayPal, các cổng khác tích hợp sẵn
Theo dõi trạng thái	Cập nhật trạng thái đơn hàng theo thời gian thực
Thông báo cho khách hàng	Tự động gửi xác nhận đơn hàng, cập nhật giao hàng
Quản lý hàng tồn kho	Tự động trừ hàng tồn kho khi có đơn hàng
Phân tích & Báo cáo	Báo cáo doanh số, theo dõi doanh thu
Bảo mật	Xử lý thanh toán tuân thủ PCI

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

Đơn hàng được tạo từ dữ liệu giỏ hàng

Bạn cần cung cấp:

Thông tin khách hàng - Tên, email, điện thoại
Mặt hàng đơn hàng - Sản phẩm, số lượng, giá
Địa chỉ giao hàng - Địa điểm giao hàng
Phương thức thanh toán - Cách khách hàng sẽ thanh toán

Quản lý trạng thái đơn hàng

Theo dõi tiến trình đơn hàng qua các trạng thái:

Các luồng trạng thái phổ biến:

Sản phẩm kỹ thuật số: đang chờ → đang xử lý → đã hoàn thành
Sản phẩm vật lý: đang chờ → đang xử lý → đã gửi → đã giao → đã hoàn thành
Đã hủy: bất kỳ trạng thái nào → đã hủy
Đã hoàn tiền: đã hoàn thành → đã hoàn tiền

Xử lý thanh toán

Đơn hàng tích hợp với các cổng thanh toán

💡 Lưu ý quan trọng

Đơn hàng được tạo trong OneEntry

Mô-đun Orders xử lý toàn bộ vòng đời đơn hàng:

✅ Tạo đơn hàng từ dữ liệu giỏ hàng
✅ Xử lý thanh toán
✅ Cập nhật trạng thái đơn hàng
✅ Theo dõi giao hàng
❌ Không xử lý giao diện giỏ hàng (bạn xây dựng điều đó)

Trách nhiệm của bạn:

Xây dựng giao diện giỏ hàng
Thu thập thông tin khách hàng
Hiển thị xác nhận đơn hàng

Xử lý thanh toán

Đơn hàng tích hợp với các cổng thanh toán:

Stripe (được khuyến nghị)
PayPal
Các cổng tùy chỉnh

Quan trọng:

Không bao giờ lưu trữ thông tin thẻ tín dụng trực tiếp
Sử dụng mã hóa (Stripe.js, PayPal SDK)
OneEntry xử lý thanh toán an toàn

Quản lý hàng tồn kho

Đơn hàng tự động:

✅ Trừ hàng tồn kho khi tạo đơn hàng
✅ Khôi phục hàng tồn kho khi hủy
✅ Theo dõi mức tồn kho

Thực hành tốt nhất: Kiểm tra hàng tồn kho trước khi tạo đơn hàng

Bảo mật

Đơn hàng chứa dữ liệu nhạy cảm:

Thông tin cá nhân của khách hàng
Chi tiết thanh toán
Địa chỉ giao hàng

Luôn luôn:

Sử dụng HTTPS cho các trang thanh toán
Xác thực dữ liệu trước khi tạo đơn hàng
Thực hiện xác thực đúng cách
Tuân thủ PCI DSS cho thanh toán

📊 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ả đơn hàng (theo trang)
getOrdersStorageByMarker()	Lấy một đối tượng lưu trữ đơn hàng theo dấu hiệ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 dấu hiệ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 dấu hiệu và ID từ đối tượng lưu trữ đơn hàng do người dùng tạo.

❓ 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 dữ liệu đơn hàng. Mỗi sản phẩm nên bao gồm id, số lượng, và giá. Tổng số sẽ được tính toán tự động dựa trên số lượng và giá của sản phẩm.

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, địa chỉ giao hàng, hoặc dữ liệu đơn hàng. Tuy nhiên, một khi thanh toán đã được xử lý, hãy cẩn thận khi sửa đổi các mặt hàng hoặc tổng số đơn hàng.

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

Sử dụng trường statusIdentifier để theo dõi trạng thái hiện tại của đơn hàng. Bạn cũng có thể thiết lập webhook hoặc sử dụng mô-đun Events để nhận thông báo khi trạng thái đơn hàng 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 (như đơn hàng từ một 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 mua thực tế trong lưu trữ đó. Sử dụng các dấu hiệu để xác định và tổ chức các lưu trữ đơn hàng khác nhau.

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 thành 'đã hủy' bằng cách sử dụng updateOrderByMarkerAndId(). Đối với hoàn tiền, sử dụng mô-đun Payments để xử lý giao dịch hoàn tiền, sau đó cập nhật trạng thái đơn hàng thành 'đã hoàn tiền'.

Tôi có thể lấy lịch sử đơn hàng của khách hàng không?

Có, sử dụng getAllOrdersByMarker() với các bộ lọc phù hợp để lấy tất cả đơn hàng cho một khách hàng cụ thể. Bạn có thể lọc theo ID người dùng, khoảng thời gian, hoặc các tiêu chí khác.

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

Xác thực giỏ hàng trước khi tạo đơn hàng - Kiểm tra tính khả dụng của hàng tồn kho
Tính toán tổng trên máy chủ - Không bao giờ tin tưởng vào các phép tính phía khách hàng
Gửi xác nhận đơn hàng - Gửi email cho khách hàng sau khi đặt hàng
Theo dõi trạng thái đơn hàng - Cập nhật trạng thái khi đơn hàng tiến triển
Xử lý các lỗi thanh toán - Logic thử lại, thông báo lỗi rõ ràng
Thực hiện tìm kiếm đơn hàng - Cho phép khách hàng dễ dàng tìm thấy đơn hàng của họ
Lưu trữ lịch sử đơn hàng - Giữ hồ sơ cho dịch vụ khách hàng
Sử dụng phân trang - Không tải tất cả đơn hàng cùng một lúc

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

Định nghĩa của mô-đun Orders


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

🔗 Tài liệu liên quan

Mô-đun Products - Quản lý sản phẩm có sẵn để mua
Mô-đun Users - Quản lý khách hàng đặt hàng
Mô-đun IntegrationCollections - Tích hợp cổng thanh toán
Mô-đun Events - Thông báo trạng thái đơn hàng

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

📖 Giải thích đơn giản​

✨ Khái niệm chính​

Đơn hàng là gì?​

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

Vòng đời đơn hàng​

Ví dụ về trạng thái đơn hàng​

Các thao tác đơn hàng phổ biến​

Tại sao sử dụng mô-đun Orders?​

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

Đơn hàng được tạo từ dữ liệu giỏ hàng​

Quản lý trạng thái đơn hàng​

Xử lý thanh toán​

💡 Lưu ý quan trọng​

Đơn hàng được tạo trong OneEntry​

Xử lý thanh toán​

Quản lý hàng tồn kho​

Bảo mật​

📊 Bảng tham khảo nhanh​

❓ 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?​

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

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

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àm thế nào để tôi xử lý việc hủy đơn hàng và hoàn tiền?​

Tôi có thể lấy lịch sử đơn hàng của khách hàng không?​

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

Định nghĩa của mô-đun Orders​

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

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

📖 Giải thích đơn giản

✨ Khái niệm chính

Đơn hàng là gì?

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

Vòng đời đơn hàng

Ví dụ về trạng thái đơn hàng

Các thao tác đơn hàng phổ biến

Tại sao sử dụng mô-đun Orders?

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

Đơn hàng được tạo từ dữ liệu giỏ hàng

Quản lý trạng thái đơn hàng

Xử lý thanh toán

💡 Lưu ý quan trọng

Đơn hàng được tạo trong OneEntry

Xử lý thanh toán

Quản lý hàng tồn kho

Bảo mật

📊 Bảng tham khảo nhanh

❓ 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?

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

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

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àm thế nào để tôi xử lý việc hủy đơn hàng và hoàn tiền?

Tôi có thể lấy lịch sử đơn hàng của khách hàng không?

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

Định nghĩa của mô-đun Orders

🔗 Tài liệu liên quan