Checkout giỏ hàng

EndpointCopy Anchor Link

PUT /site/customercarts/{uuid}/checkout

HeadersCopy Anchor Link

Workflow & LogicCopy Anchor Link

API này dùng để checkout cart và tạo Order dựa trên quote hiện tại của giỏ hàng.
Luồng xử lý bao gồm: xác định khách hàng, đồng bộ thông tin checkout vào cart, tính lại quote (nếu cần), build payload order và gọi API tạo đơn.

Quy trình xử lýCopy Anchor Link

1. Lấy & kiểm tra giỏ hàng theo uuid

   • Hệ thống tìm cart theo uuid trong shop hiện tại (SiteTenantId).
   • Nếu cart đã gắn với một khách hàng, khách hàng khác đang đăng nhập không dùng được cart này. Khách chưa đăng nhập vẫn dùng được cart bằng uuid.
   • Nếu không tồn tại → trả lỗi error_cart_not_found.

2. Xác định customer_id cho Order

   • Nếu request đi kèm token hợp lệ của shop này (khách đã đăng nhập): dùng customer_id từ phiên đăng nhập.

   • Nếu guest:

     • Đọc setting website_checkout_create_new_customer.
     • Nếu setting cho phép và create_customer = 1 trong request → hệ thống tạo mới khách hàng từ thông tin đơn hàng.
     • Ngược lại → dùng website_order_default_customer_id làm khách mặc định.

3. Gán store xử lý mặc định

   • Luôn dùng website_order_default_store từ setting làm store_id (giá trị store_id trong request bị bỏ qua).
   • Đảm bảo đơn hàng luôn được gán vào một store xử lý cụ thể.

4. Sync thông tin checkout & tính lại quote

   • Ghi đè các field checkout từ request vào cart (shipping/billing, payment_method, coupon_code, redeem_points, tax_*, ...).

   • Tính lại quote giống Lấy báo giá giỏ hàng:

     • Enrich lại details[], tính price_sell, price_shipping, price_discount_*, price_final.
     • Áp dụng promotion engine (bundle + cart) và loyalty nếu có.

   • Kết quả là một quotedCart đồng bộ với những gì user thấy ở màn hình checkout.

   • Nếu có dòng hàng mà giá theo ngữ cảnh (flash sale, khung giờ đặt hàng) không còn hiệu lực → trả lỗi error_checkout_blocked_<lý do> (VD: error_checkout_blocked_pricing_context_expired) và không tạo đơn.

5. Build payload tạo order từ quoted cart

   • Gộp quotedCart + meta bổ sung (customer_id, aff_click_token, tax_phone, ...) thành dữ liệu đơn hàng.
   • Tính lại price_final, weight, quantity, map details[] sang format [Order Detail] với đầy đủ thông tin SKU/UOM/giá/khuyến mãi/gift.
   • Ghi đè date_created của order về thời điểm hiện tại để tránh lệch thời gian so với lúc tạo cart.

6. Tạo Order

   • Tạo đơn hàng từ dữ liệu ở trên.
   • Nếu tạo đơn lỗi hoặc không trả về id hợp lệ → thêm lỗi error_create_order hoặc error_create_order_empty_order_data (kèm các mã lỗi chi tiết từ bước tạo đơn).

7. Finalize cart sau khi tạo order thành công

   • Cập nhật cart:

     • status = 5 (Finish).
     • sale_order_id = ID order vừa tạo.
     • Nếu cart trước đó là guest nhưng user hiện đã đăng nhập, gán thêm customer_id vào cart.

   • Lưu lại để phục vụ các luồng thống kê/đối soát sau này.

Request BodyCopy Anchor Link

Body là JSON checkout, tối thiểu bao gồm các field phục vụ quote (giống getQuote), và có thể kèm:

• create_customer: 1 để tạo tài khoản khách hàng mới cho khách chưa đăng nhập (chỉ có tác dụng khi shop bật website_checkout_create_new_customer).
• aff_click_token: mã click tiếp thị liên kết (affiliate) để ghi nhận hoa hồng.
• tax_phone: số điện thoại trên hóa đơn VAT.

{
  "create_customer": 0,
  "aff_click_token": "",
  "tax_phone": "",
  "store_id": 1,
  "pickup_store_id": 0,
  "shipping_type": "delivery",
  "shipping_address_id": 0,
  "shipping_full_name": "Nguyễn Văn A",
  "shipping_phone": "0900000000",
  "shipping_email": "[email protected]",
  "shipping_address": "12 Nguyễn Huệ, P. Bến Nghé",
  "shipping_region_id": 1,
  "shipping_sub_region_id": 0,
  "shipping_sub_sub_region_id": 0,
  "shipping_profile_rate_id": 0,
  "billing_full_name": "Nguyễn Văn A",
  "billing_phone": "0900000000",
  "billing_email": "[email protected]",
  "billing_address": "12 Nguyễn Huệ, P. Bến Nghé",
  "billing_region_id": 1,
  "billing_sub_region_id": 0,
  "billing_sub_sub_region_id": 0,
  "payment_method": 0,
  "coupon_code": "",
  "redeem_points": 0
}

Response SchemaCopy Anchor Link

HTTP 200 - Thành côngCopy Anchor Link

Trả về object Order vừa được tạo thành công.

Ví dụ ResponseCopy Anchor Link

{
  "id": 10002414,
  "uuid": "3b733736-2278-42d1-8c2f-31d5cef7cd81",
  "customer_id": 101,
  "store_id": 32,
  "shipping_full_name": "Nguyễn Văn A",
  "shipping_phone": "0900000000",
  "shipping_address": "12 Nguyễn Huệ, P. Bến Nghé, Quận 1, TP.HCM",
  "payment_method": 1,
  "payment_status": 1,
  "status": 1,
  "price_sell": 150000,
  "price_shipping": 20000,
  "price_discount": 10000,
  "price_tax": 0,
  "price_final": 160000,
  "date_created": 1738057367
}

HTTP 422 - Lỗi dữ liệu / logicCopy Anchor Link

Ngoài ra có thể trả về các lỗi của bước quote (xem getQuote).