Quản lý nhóm sản phẩmBiến thể sản phẩm
Cập nhật hàng loạt biến thể
Cập nhật danh sách biến thể của một sản phẩm cùng lúc
Endpoint
PUT /v1/productvariants/batch/{product_id}
Quyền:
product.manage
Path Parameters
| Tên | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
product_id | int | Có | ID sản phẩm cha của các biến thể |
Request Body
Gửi danh sách các biến thể cần cập nhật hoặc thêm mới trong mảng items. Cần truyền kèm thông tin công ty và người thao tác để kiểm tra phân quyền.
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
company_id | int | Có | ID công ty (dùng để validate và check scope) |
creator_id | int | Có | ID người thao tác (dùng để kiểm tra quyền) |
items | array | Có | Danh sách đối tượng biến thể (tối đa 200 phần tử) |
Cấu trúc item trong mảng items
- Nếu có
id> 0: Hệ thống sẽ tìm và CẬP NHẬT biến thể đó. - Nếu không có
id(hoặc id=0) và cóuuid(dạngnew_...): Hệ thống sẽ TẠO MỚI biến thể.
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
id | int | Không | ID biến thể (>0 để cập nhật, 0 hoặc bỏ trống để tạo mới) |
uuid | string | Không | UUID biến thể. Với biến thể mới có thể gửi dạng new_..., hệ thống sẽ tự chuẩn hóa. |
sku | string | Không | Mã SKU (sẽ được chuẩn hóa bỏ khoảng trắng) |
barcode | string | Không | Mã barcode |
display_name | string | Không | Tên hiển thị của biến thể |
note | string | Không | Ghi chú nội bộ |
price | int | Không | Giá bán chính |
compare_price | int | Không | Giá so sánh (giá gốc trước giảm giá) |
min_stock | int | Không | Tồn kho tối thiểu |
is_serial_tracked | int | Không | Theo dõi serial (1: Có, 0: Không) |
length | int | Không | Chiều dài |
width | int | Không | Chiều rộng |
height | int | Không | Chiều cao |
weight | int | Không | Trọng lượng |
external_id | string | Không | ID liên kết bên ngoài |
price_by_uom | array | Không | Giá theo đơn vị tính |
combo_data | array | Không | Dữ liệu combo (nếu là sản phẩm combo) |
bom | array | Không | Bill of materials |
display_order | int | Không | Thứ tự hiển thị (thường do UI sinh ra tự động) |
option_values | array | Không | Danh sách giá trị tùy chọn (option_id, option_value_id, option_value_name, uuid). Hệ thống kiểm tra từng giá trị; nếu option_value_name khác tên của option_value_id hoặc chưa có ID, hệ thống tìm giá trị cùng tên trong tùy chọn hoặc tự tạo mới. Chỉ được lưu khi có quyền product.managecontent |
photo_gallery_file_id_list | array | Không | Danh sách file ID ảnh gallery cho biến thể (chỉ được lưu khi có quyền product.managecontent) |
is_bom_kit | int | Không | Là BOM kit (chỉ áp dụng khi TẠO MỚI, không đổi được với biến thể đã tồn tại) |
Lưu ý
Mọi biến thể gửi qua API này đều được gán trạng thái
3 (Active) và thuộc sản phẩm product_id trên đường dẫn; trường status, company_id, product_id trong từng item bị bỏ qua.Ví dụ Request Body
Ví dụ payload khi cập nhật nhiều biến thể của cùng một sản phẩm:
{
"company_id": 10311,
"creator_id": 1,
"items": [
{
"id": 2206,
"uuid": "89d2a505-3034-4d67-a307-2e89e4ccc4a6",
"sku": "8938502234534",
"option_values": [
{
"option_id": 8,
"option_value_id": 4,
"option_value_name": "Đen",
"uuid": "4abdd739-a132-49bd-9ed8-341ae6d48bbc"
},
{
"option_id": 9,
"option_value_id": 14,
"option_value_name": "L",
"uuid": "7d66253a-9c87-43f2-996b-712e015aa992"
}
],
"external_id": "",
"price": 199000,
"price_by_uom": [],
"photo_gallery_file_id_list": [4598],
"display_order": 1001,
"barcode": "",
"display_name": "",
"note": "",
"compare_price": 0,
"min_stock": 0,
"is_serial_tracked": 0,
"length": 0,
"width": 0,
"height": 0,
"weight": 0
},
{
"id": 2208,
"uuid": "85eefaf7-07bd-48ea-8c42-e58c2cb60bae",
"sku": "8938502234535",
"option_values": [
{
"option_id": 8,
"option_value_id": 86,
"option_value_name": "Đen",
"uuid": "25c3915c-ed69-4c6d-a1df-88b171ebb516"
},
{
"option_id": 9,
"option_value_id": 84,
"option_value_name": "S",
"uuid": "0dc0a878-f6fe-4157-a119-0916234daa5c"
}
],
"external_id": "",
"price": 199000,
"price_by_uom": [],
"photo_gallery_file_id_list": [4599],
"display_order": 1002,
"barcode": "",
"display_name": "",
"note": "",
"compare_price": 0,
"min_stock": 0,
"is_serial_tracked": 0,
"length": 0,
"width": 0,
"height": 0,
"weight": 0
}
]
}Response Schema
HTTP 200 - OK
Trả về danh sách các biến thể đã được xử lý (bao gồm các ID mới được tạo).
{
"currentpage": 1,
"limit": 200,
"total": 2,
"items": [
{ "id": 1001, ... },
{ "id": 1005, ... }
]
}Error Codes
Lỗi dữ liệu (HTTP 422) trả về dạng mảng trong trường error. Các item được xử lý lần lượt: nếu một item lỗi, các item hợp lệ khác vẫn có thể đã được lưu, nhưng response trả về HTTP 422 kèm danh sách lỗi.
| Mã lỗi | Mô tả |
|---|---|
error_items_property_is_required | Thuộc tính items phải là mảng |
error_items_count_max_200 | Số lượng items vượt quá 200 |
error_product_variant_not_found_in_batch(ID #X) | Không tìm thấy biến thể với ID đã gửi (khi cập nhật) |
error_product_variant_update_fail(ID #X) | Cập nhật biến thể thất bại |
error_product_variant_add_fail(ID #UUID) | Thêm mới biến thể thất bại |
error_option_value_id_invalid(ID #X, inside Option ID #Y) | ID giá trị tùy chọn không hợp lệ |
error_option_value_created(Name #X, inside Option ID #Y) | Không thể tạo giá trị tùy chọn mới |
error_company_id_required | ID công ty không được để trống |
error_company_id_notfound | ID công ty không tìm thấy |
error_user1_id_required | ID người tạo không được để trống |
error_user_id_notfound | ID người tạo không tìm thấy |
error_not_found | Sản phẩm không tồn tại hoặc không thuộc công ty của bạn (HTTP 404) |
error_role_not_available | Không có quyền product.manage (HTTP 403) |