Lấy báo giá giỏ hàng (Quote)

Đồng bộ thông tin checkout vào cart và tính lại giá (khuyến mãi, phí ship, điểm/loyalty).

Endpoint

PUT /site/customercarts/{uuid}/getquote

Headers

Key	Value	Bắt buộc	Mô tả
`SiteTenantId`	`{tenant_id}`	Có	ID của công ty/tenant.
`SiteAuthorization`	`{jwt_token}`	Không	Token khách hàng (nếu đã đăng nhập).

Workflow & Logic

API này dùng để tính quote cho giỏ hàng trước khi checkout. Request sẽ đồng bộ các thông tin giao hàng/thanh toán vào cart, sau đó tính lại:

Giá bán theo chính sách giá (website/customer type).
Phí vận chuyển (khi shipping_type = delivery và đủ dữ liệu).
Khuyến mãi (bundle evaluate + cart evaluate).
Quy đổi điểm tích lũy (loyalty redeem evaluate) nếu có redeem_points.

Quy trình xử lý

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.
Ghi đè thông tin checkout từ request vào cart
- Ghi các field billing/shipping (billing_full_name, shipping_address, shipping_region_id, ...).
- Ghi store_id, pickup_store_id, shipping_type, shipping_profile_rate_id.
- Ghi payment_method, coupon_code, redeem_points, thông tin hóa đơn (tax_*).
- Lưu ý: các field không gửi lên sẽ bị ghi đè thành rỗng/0, nên Frontend cần gửi đầy đủ trạng thái checkout mỗi lần gọi.
- Toàn bộ thao tác này không tạo order, chỉ sync trạng thái checkout vào cart.
Enrich cart data & tính tổng tiền hàng
- Hệ thống:
  - Chuẩn hóa danh sách item (details[]) từ data trong cart.
  - Áp dụng chính sách giá đang active (active_price_policy_id).
  - Tính price_sell, total_weight, total_item, loại bỏ item không hợp lệ.
Tính phí vận chuyển tạm thời
- Nếu shipping_type = delivery và có đủ shipping_address, shipping_region_id > 0 và shipping_profile_rate_id > 0:
  - Tính phí theo cấu hình vận chuyển của shop (giá trị đơn, khối lượng, khu vực) và lấy phí của rate có id = shipping_profile_rate_id, gán price_shipping, price_shipping_original.
  - Danh sách rate hợp lệ để khách chọn lấy qua Tính phí vận chuyển.
- Nếu thiếu thông tin bắt buộc → phí ship = 0, nhưng cart vẫn được quote.
Chạy promotion engine
- Bước 1 – Bundle evaluate:
  - Áp dụng khuyến mãi theo bundle, cập nhật lại đơn giá từng dòng bundle.
  - Bổ sung bundles_map để track các bundle đang áp dụng.
- Bước 2 – Cart evaluate:
  - Áp dụng khuyến mãi cấp cart (order / shipping / coupon) dựa trên payload cuối cùng.
  - Cập nhật promotionengine và các trường price_discount_order, price_discount_shipping, price_discount_coupon, price_discount.
Đánh giá loyalty (nếu có điểm redeem)
- Đánh giá số điểm redeem_points theo chương trình tích điểm của shop.
- Nếu approved, hệ thống tính price_discount_loyalty và cộng vào tổng giảm giá, trừ vào price_final.
Gắn thông tin quote & trả về kết quả
- Build price_quote gồm payload, payload_hash, payload_length, date_expired (60 giây sau thời điểm quote) để đảm bảo tính toàn vẹn khi checkout.
- Trả về toàn bộ cart đã quote (cart object + details + promotionengine + loyalty + price_quote).

Request Body

Body là JSON chứa thông tin checkout để hệ thống sync vào cart và tính quote.

{
  "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": "khachhang@example.com",
  "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_legacy_province_name": "",
  "shipping_legacy_district_name": "",
  "shipping_legacy_ward_name": "",
  "shipping_profile_rate_id": 0,
  "billing_full_name": "Nguyễn Văn A",
  "billing_phone": "0900000000",
  "billing_email": "khachhang@example.com",
  "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,
  "birthday": "",
  "gender": 0,
  "payment_method": 0,
  "note": "",
  "coupon_code": "",
  "tax_name": "",
  "tax_address": "",
  "tax_email": "",
  "tax_code": "",
  "tax_is_company": 0,
  "redeem_points": 0,
  "gift_selections": []
}

shipping_type: delivery (giao hàng), pickup (nhận tại cửa hàng), instore.
payment_method: xem bảng payment_method.
gift_selections: (không bắt buộc) lựa chọn quà tặng khi chương trình khuyến mãi cho phép khách chọn quà.

Response Schema

HTTP 200 - Thành công

Trả về Customer Cart đã quote. Xem thêm Customer Cart Object Schema.

Các field chính

Field	Kiểu	Mô tả
`id`	`integer`	ID cart.
`uuid`	`string`	UUID cart.
`company_id`	`integer`	Tenant/company id.
`customer_id`	`integer`	ID khách hàng (0 nếu guest).
`source`	`integer`	Nguồn tạo cart.
`store_id`	`integer`	Store xử lý đơn hàng.
`pickup_store_id`	`integer`	Store pickup.
`shipping_type`	`string`	`delivery` / `pickup` / `instore`.
`payment_method`	`integer`	Phương thức thanh toán.
`payment_status`	`integer`	Trạng thái thanh toán.
`note`	`string`	Ghi chú đơn hàng.
`coupon_code`	`string`	Mã coupon.
`redeem_points`	`integer`	Điểm redeem yêu cầu.

Thông tin tổng tiền

Field	Kiểu	Mô tả
`price_sell`	`integer`	Tổng tiền hàng (đã sync đơn giá theo policy/promotion).
`price_shipping`	`integer`	Phí ship hiện tại (có thể = 0 nếu thiếu dữ liệu ship).
`price_shipping_original`	`integer`	Phí ship gốc trước khuyến mãi.
`price_discount_order`	`integer`	Giảm giá cấp đơn hàng.
`price_discount_shipping`	`integer`	Giảm giá phí ship.
`price_discount_coupon`	`integer`	Giảm giá từ coupon.
`price_discount_loyalty`	`integer`	Giảm giá từ loyalty (nếu áp dụng).
`price_discount`	`integer`	Tổng giảm giá.
`price_final`	`integer`	Tổng thanh toán cuối cùng.

Line items & enrich data

Field	Kiểu	Mô tả
`details`	`array`	Danh sách item đã enrich (tên/ảnh/option/giá/promotionengine).
`total_item`	`integer`	Tổng số item (tính từ `details`).
`total_weight`	`integer`	Tổng khối lượng (gram) hoặc tổng cân nặng quy đổi.
`active_price_policy_id`	`integer`	Policy giá đang áp dụng để tính `details`/giá.
`website_price_policy_id`	`integer`	Policy giá mặc định website (đối chiếu).
`invalid_items`	`array`	Item không hợp lệ bị loại khỏi quote.
`invalid_items_explain`	`object`	Giải thích invalid item (danh sách id/identifier).
`bundles_map`	`object`	Map bundle identifier → snapshot/metadata bundle promotion.
`gift_item_product_info`	`array`	(Storefront) Danh sách product info của các gift item để UI hiển thị.

details[]

(chi tiết từng item)

Mỗi phần tử trong details[] là 1 line item đã enrich từ data trong cart, có thể là standalone item hoặc bundle item.

Field	Kiểu	Mô tả
`id`	`integer`	Index của item trong cart.
`row_identifier`	`string`	Khóa định danh dòng để promotion engine map kết quả.
`product_id`	`integer`	ID sản phẩm.
`product_name`	`string`	Tên sản phẩm.
`product_variant_id`	`integer`	ID biến thể.
`is_base_uom`	`boolean`	`true` nếu đang ở UOM base/default.
`uom_id`	`integer`	ID đơn vị tính.
`uom_name`	`string`	Tên đơn vị tính.
`uom_quantity`	`integer`	Số lượng theo UOM.
`uom_unit_price`	`integer`	Đơn giá sau khi áp dụng policy/promotion.
`uom_unit_price_original`	`integer`	Đơn giá gốc (đối chiếu), thường theo website price policy.
`uom_unit_weight`	`integer`	Trọng lượng 1 UOM (gram) sau quy đổi.
`selected_options`	`array`	Danh sách option đã chọn của variant.
`product_options`	`array`	Metadata option (Color/Size...) tương ứng `selected_options`.
`image`	`string`	URL ảnh đại diện (variant ưu tiên, fallback product).
`customize_required`	`integer`	1 nếu item yêu cầu tùy biến/ghi chú.
`customize_description`	`string`	Nội dung tùy biến (nếu có).
`file_id_list`	`array`	Danh sách file đính kèm (nếu có).
`weight_sale_mode`	`integer`	Chế độ bán theo cân (mapping theo Product).
`weight_preset_id`	`string`	ID preset cân nặng (nếu dùng).
`weight_preset_name`	`string`	Tên preset cân nặng.
`weight_preset_factor`	`integer`	Hệ số quy đổi preset.
`pricing_type`	`integer`	Kiểu tính giá (nếu có).
`bundle_identifier`	`string`	Bundle identifier (rỗng nếu không phải bundle).
`bundle_promotion_id`	`integer`	ID bundle promotion (0 nếu không phải bundle).
`bundle_promotion_product_id`	`integer`	ID promotion product trong bundle (nếu có).
`bundle_promotion_multiplier`	`integer`	Hệ số số lượng bundle.
`bundle_index`	`integer`	Index item trong bundle (sau evaluate bundle).
`bundle_allocation_rule`	`string`	Rule phân bổ giảm giá của bundle (nếu có).
`bundle_discount_allocated`	`integer`	Giảm giá được phân bổ cho dòng bundle (nếu có).
`promotionengine`	`object`	Kết quả promotion engine ở cấp line item (đặc biệt cho standalone item).

invalid_items[]

invalid_items[] là danh sách item bị loại trong bước enrich (do variant/product không tồn tại/không active, hoặc bundle identifier không hợp lệ...).

Ghi chú: đây là item “thô” theo cấu trúc trong cart.data, nên field có thể khác details[] và có thể thiếu một số metadata (tên/ảnh/đơn giá...).

Field	Kiểu	Mô tả
`product_variant_id`	`integer`	ID biến thể.
`product_id`	`integer`	ID sản phẩm (thường có ở item bundle).
`uom_id`	`integer`	ID UOM.
`uom_name`	`string`	Tên UOM.
`uom_quantity`	`integer`	Số lượng theo UOM.
`selected_options`	`array`	Option đã chọn.
`weight_sale_mode`	`integer`	Chế độ bán theo cân.
`weight_preset_id`	`string`	ID preset cân nặng.
`weight_preset_name`	`string`	Tên preset cân nặng.
`weight_preset_factor`	`integer`	Hệ số preset.
`pricing_type`	`integer`	Kiểu tính giá (nếu có).
`bundle_identifier`	`string`	Bundle identifier (nếu là bundle item).
`bundle_promotion_id`	`integer`	ID bundle promotion (nếu là bundle item).
`bundle_promotion_product_id`	`integer`	ID promotion product trong bundle (nếu có).
`bundle_promotion_multiplier`	`integer`	Multiplier của bundle (nếu có).

invalid_items_explain

Đối tượng này giúp UI/debug biết vì sao item bị loại và nhóm theo nguyên nhân.

Field	Kiểu	Mô tả
`invalid_product_id_list`	`array`	Danh sách `product_id` không hợp lệ (không tồn tại/không active/không được hiển thị).
`invalid_variant_id_list`	`array`	Danh sách `product_variant_id` không hợp lệ.
`invalid_bundle_identifier_list`	`array`	Danh sách `bundle_identifier` không hợp lệ (liên quan item invalid).

bundles_map

bundles_map là map theo bundle_identifier để mô tả bundle promotion đã được apply sau bước bundle evaluate.

Key	Value	Mô tả
`{bundle_identifier}`	`object`	Snapshot/metadata của bundle promotion tương ứng identifier đó.

Các field bên trong mỗi entry có thể thay đổi theo promotion engine, nhưng thường gặp:

Field	Kiểu	Mô tả
`promotion_snapshot`	`object`	Snapshot promotion (ví dụ: `id`, `name`, `type`, ...).
`items`	`array`	Danh sách item thuộc bundle (nếu promotion engine trả về).

Khuyến mãi / Quote / Loyalty

Field	Kiểu	Mô tả
`promotionengine`	`object`	Quyết định khuyến mãi cấp cart (order/shipping/coupon).
`price_quote`	`object`	Thông tin quote để đối chiếu khi checkout.
`price_quote.date_expired`	`integer`	Timestamp hết hạn quote (60 giây sau khi quote).
`price_quote.payload_hash`	`string`	MD5 hash của payload quote.
`price_quote.payload_length`	`integer`	Độ dài payload quote.
`price_quote.payload`	`string`	Payload quote (JSON stringify).
`loyalty`	`object`	Kết quả loyalty redeem evaluate (có thể có `warning`).
`context`	`object`	Context evaluate (shipping/payment/coupon/source...).

HTTP 422 - Lỗi dữ liệu / logic

Mã lỗi	Mô tả
`error_cart_not_found`	Không tìm thấy giỏ hàng theo `uuid`.
`error_calculate_shipping_price_response_no_data`, `error_calculate_shipping_price_request_error`	Không tính được phí vận chuyển.
`error_from_promotionengines_controller_response_no_data`, `error_from_promotionengines_controller_request_error`	Không đánh giá được khuyến mãi.

Lỗi khi đánh giá điểm tích lũy không làm request thất bại, mà được trả trong loyalty.warning.

Lấy báo giá giỏ hàng (Quote)

EndpointCopy Anchor Link

HeadersCopy Anchor Link

Workflow & LogicCopy Anchor Link

Quy trình xử lýCopy Anchor Link

Request BodyCopy Anchor Link

Response SchemaCopy Anchor Link

HTTP 200 - Thành côngCopy Anchor Link

Các field chínhCopy Anchor Link

Thông tin tổng tiềnCopy Anchor Link

Line items & enrich dataCopy Anchor Link

Khuyến mãi / Quote / LoyaltyCopy Anchor Link

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

On this page