CartGiỏ hàng khách hàng
Thêm sản phẩm vào giỏ
Thêm một sản phẩm (biến thể) vào giỏ hàng.
Endpoint
PUT /site/customercarts/{uuid}/additem
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). |
Path Parameters
| Tên | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
uuid | string | Có | UUID của giỏ hàng (nhận được khi tạo giỏ hàng). |
Workflow & Logic
- Kiểm tra
product_variant_idvàuom_quantitylà số. - Nếu sản phẩm là combo (
type = 5), bắt buộc gửiselections(danh sách biến thể thành phần đã chọn); tổng số lượng chọn phải khớp với cấu hình combo. - Nếu
pricing_context_typekhácdefault(VD:flash_sale), hệ thống kiểm tra giới hạn số lượng của chương trình (tính cả số lượng đã có trong giỏ). - Nếu trong giỏ đã có dòng cùng
product_variant_id,uom_id,weight_preset_idvà cùng ngữ cảnh giá → cộng dồn số lượng; ngược lại thêm dòng mới. Sản phẩm combo luôn tạo dòng mới. - Tính lại giá, khuyến mãi và trả về giỏ hàng.
Quyền truy cập giỏ hàng
Giỏ hàng được tìm theo uuid trong shop hiện tại. Nếu giỏ đã gắn với một khách hàng, khách hàng khác đang đăng nhập sẽ nhận lỗi error_cart_not_found. Khách chưa đăng nhập vẫn dùng được giỏ bằng uuid, vì vậy cần giữ uuid bí mật (VD: lưu trong cookie).
Request Body
{
"product_variant_id": 101,
"uom_id": 0,
"uom_name": "",
"uom_quantity": 2,
"selected_options": [
{ "option_id": 1, "option_value_id": 5 }
],
"weight_preset_id": "",
"pricing_context_type": "default",
"pricing_context_id": 0
}| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
product_variant_id | integer | Có | ID biến thể sản phẩm. |
uom_quantity | integer | Có | Số lượng theo đơn vị tính. |
uom_id | integer | Không | ID đơn vị tính (0 = đơn vị cơ bản). Xem product_uoms trong Product Object. |
uom_name | string | Không | Tên đơn vị tính. |
selected_options | array | Không | Tùy chọn (màu, size...) của biến thể. |
weight_sale_mode, weight_preset_id, weight_preset_name, weight_preset_factor | Không | Thông tin bán theo cân (với sản phẩm bán theo khối lượng). | |
pricing_type | integer | Không | Kiểu tính giá. |
selections | array | Với combo | Các biến thể thành phần đã chọn của combo. |
pricing_context_type | string | Không | Ngữ cảnh giá: default (mặc định), flash_sale, order_window. |
pricing_context_id | integer | Không | ID chương trình tương ứng (VD: ID flash sale). |
pricing_context_name | string | Không | Tên chương trình (hiển thị). |
Response Schema
HTTP 200 - Thành công
Trả về giỏ hàng đã được tính lại giá và khuyến mãi (các trường cơ bản + details, total_item, total_weight, promotionengine, ...). Xem Customer Cart Object và mô tả details[] tại Lấy báo giá giỏ hàng.
HTTP 422 - Lỗi dữ liệu
| Mã lỗi | Mô tả |
|---|---|
error_cart_not_found | Không tìm thấy giỏ hàng. |
error_cart_data_item_missing_property | Thiếu product_variant_id hoặc uom_quantity. |
error_combo_requires_selections | Sản phẩm combo nhưng không gửi selections. |
error_combo_invalid_quantity, error_combo_selection_invalid_structure, error_combo_selection_variant_invalid, error_combo_selection_quantity_mismatch | selections của combo không hợp lệ. |
error_additem | Lưu giỏ hàng thất bại. |
Khi vượt giới hạn số lượng của flash sale/khung giờ đặt hàng, API trả mã lỗi tương ứng của chương trình (kèm thông điệp mô tả).