Quản lý nhóm sản phẩmSản phẩm
Cập nhật sản phẩm
Cập nhật toàn bộ thông tin một sản phẩm
Endpoint
PUT /v1/products/:id
Quyền:
product.managehoặcproduct.managecontent(riêng nhóm trường nội dung và media nhưavatar_file_id_list,photo_gallery_file_id_list,summary,description,seo_*bắt buộc phải có quyềnproduct.managecontentmới được phép ghi nhận thay đổi).
Request Body
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
company_id | int | Có | ID công ty |
creator_id | int | Có | ID người thao tác |
name | string | Có | Tên sản phẩm |
name_short | string | Không | Tên ngắn của sản phẩm |
code | string | Không | Mã sản phẩm. Phải là duy nhất. |
external_id | string | Không | ID tham chiếu hệ thống ngoài. Phải là duy nhất. |
status | int | Có | 1 (Nháp), 3 (Hoạt động), 5 (Lưu trữ/Đã xóa) |
category_primary | int | Không | ID danh mục chính |
category_id_list | array | Không | Danh sách ID danh mục phụ |
brand_id | int | Không | ID thương hiệu |
supplier_id | array | Không | Danh sách ID nhà cung cấp |
options | array | Không | Cấu trúc tùy chọn biến thể (Size, Color...)` |
sell_on_zero | int | Không | 1: Cho phép bán khi tồn kho bằng 0. Với sản phẩm dạng booking đính kèm thì luôn = 1. |
visibility | int | Không | Trạng thái hiển thị sản phẩm |
installment | array | Không | Cấu hình trả góp |
tax_ratio | float | Không | Thuế suất (%) |
weight_sale_mode | int | Không | Chế độ bán theo trọng lượng (chỉ dùng khi weight_type là trọng lượng) |
weight_presets | array | Không | Các mức cân nặng định sẵn |
physical_catch_weight_uom_id | int | Không | Đơn vị tính vật lý cho Catch weight (khi weight_sale_mode là Counting) |
pricing_type | int | Không | Loại định giá |
allow_preorder | int | Không | Cho phép đặt hàng trước |
default_variant_id | int | Không | ID biến thể mặc định |
country_of_origin | string | Không | Xuất xứ |
hs_code | string | Không | HS Code |
tags | array | Không | Danh sách tag |
note | string | Không | Ghi chú nội bộ |
attribute_detail | array | Không | Thông tin thuộc tính chi tiết |
category_displayorder | array | Không | Thứ tự hiển thị theo danh mục |
need_customize | int | Không | 1: Cần tùy biến trước khi bán |
mockup_supported | int | Không | 1: Hỗ trợ mockup |
config3d_supported | int | Không | 1: Hỗ trợ cấu hình 3D |
material_type | int | Không | Loại vật liệu |
length | int | Không | Chiều dài (dùng cho logistics/đóng gói) |
width | int | Không | Chiều rộng |
height | int | Không | Chiều cao |
packing_priority | int | Không | Độ ưu tiên khi sắp xếp đóng gói |
page_id | int | Không | ID trang nội dung liên kết |
default_warehouse_location_id | int | Không | Vị trí kho mặc định |
lead_time | int | Không | Thời gian chuẩn bị hàng (ngày) |
expiry_tracked | int | Không | 1: Theo dõi hạn sử dụng |
badge | string | Không | Nhãn hiển thị (Mới, Hot, ...) |
certification | string | Không | Thông tin chứng nhận |
summary | string | Không | Tóm tắt sản phẩm |
description | string | Không | Mô tả chi tiết |
info_package | string | Không | Thông tin đóng gói |
info_warranty | string | Không | Thông tin bảo hành |
info_promotion | string | Không | Thông tin khuyến mãi |
info_promotion_note | string | Không | Ghi chú khuyến mãi |
seo_url | string | Không | URL SEO (nếu trống sẽ được auto-gen từ name + code) |
seo_title | string | Không | Tiêu đề SEO |
seo_meta_description | string | Không | Mô tả Meta SEO |
seo_meta_keyword | string | Không | Từ khóa SEO |
seo_graph_file_id | int | Không | ID ảnh dùng cho Open Graph |
seo_canonical | string | Không | Canonical URL |
seo_options | array | Không | Các tùy chọn SEO khác |
avatar_file_id_list | array<int> | Không | Danh sách ID file ảnh đại diện sản phẩm (lấy từ File Service). Yêu cầu quyền product.managecontent để cập nhật. |
photo_gallery_file_id_list | array<int> | Không | Danh sách ID ảnh thư viện. Yêu cầu quyền product.managecontent. |
photo360_file_id_list | array<int> | Không | Danh sách ID ảnh 360. Yêu cầu quyền product.managecontent. |
embed_video_scripts | string | Không | Script nhúng video. Yêu cầu quyền product.managecontent. |
product_uoms | array | Không | Danh sách đơn vị tính quy đổi (nếu có), được xử lý riêng qua processProductUom() |
translations | array | Không | Danh sách bản dịch đa ngôn ngữ của sản phẩm (hỗ trợ ghi đè avatar_file_id_list riêng theo từng ngôn ngữ) |
Chi tiết trường avatar_file_id_list
Trường avatar_file_id_list quản lý danh sách hình ảnh đại diện ở cấp độ sản phẩm cha trong dịch vụ cp-product:
- Kiểu dữ liệu & Lưu trữ:
- Nhận mảng các số nguyên (
array<int>) là ID của các file hình ảnh đã được tải lên File Service (ví dụ:[4596]hoặc[4596, 4598]). - Trong
Model\Product, dữ liệu được gán vào thuộc tính$avatarfileidlistvà lưu xuống cộtp_avatarfileidlist(varchar(512)) dưới dạng chuỗi ID phân cách bằng dấu phẩy thông quaBaseModel::idListEncoder()(và giải mã thành mảng quaBaseModel::idListDecoder()).
- Nhận mảng các số nguyên (
- Quyền hạn & Cơ chế ghi đè khi cập nhật:
- Endpoint
PUT /v1/products/:idcho phép truy cập khi người dùng có quyềnproduct.managehoặcproduct.managecontent. - Tuy nhiên,
avatar_file_id_listnằm trong nhóm trường nội dung/media và chỉ được xử lý khi tài khoản có quyềnproduct.managecontent. Nếu người gọi chỉ có quyềnproduct.manage, giá trịavatar_file_id_listgửi lên sẽ bị bỏ qua (giữ nguyên ảnh đại diện cũ). - Khi có quyền
product.managecontent, hệ thống ép kiểu(array)$formData['avatar_file_id_list']và ghi đè toàn bộ danh sách ID hiện tại. Do đó, khi cập nhật cần truyền đầy đủ các ID ảnh muốn giữ lại; nếu truyền mảng rỗng[]hoặc bỏ trống trường này, toàn bộ ảnh đại diện hiện tại của sản phẩm sẽ bị xóa. - Lưu ý: Endpoint
PATCH /v1/products/:idkhông hỗ trợ cập nhật trực tiếpavatar_file_id_listở cấp sản phẩm gốc (chỉ hỗ trợ cập nhật quaPUT /v1/products/:id, hoặc cập nhật bản dịch qua trườngtranslations).
- Endpoint
- Thứ tự phần tử & Cấu hình nhiều ảnh đại diện (
product_allow_multiple_avatar):- Phần tử đầu tiên (
avatar_file_id_list[0]): Luôn là ảnh đại diện chính của sản phẩm, hiển thị mặc định trên danh sách sản phẩm Admin, màn hình bán hàng POS và danh sách sản phẩm Storefront. - Nhiều ảnh đại diện: Khi công ty bật cấu hình
product_allow_multiple_avatar = 1, sản phẩm có thể lưu nhiều ID trongavatar_file_id_list. Trên Storefront, phần tử thứ hai (avatar_file_id_list[1], tương ứngthumbnails[1]) được dùng cho hiệu ứng đổi ảnh khi di chuột qua thẻ sản phẩm (change_imagehover effect).
- Phần tử đầu tiên (
- Dữ liệu trả về & Tương tác với các API liên quan:
- Product Object (
GET /v1/products/:id,PUT /v1/products/:id,GET /v1/products): Bên cạnh mảng IDavatar_file_id_list, response tự động hydrate và trả về thêm trườngavatar_file_listchứa danh sách đối tượngFilechi tiết (URL ảnh, đường dẫn resize/thumbnail, tên file, kích thước...). - Full Data API (
GET /v1/products/fulldata): Trả về trực tiếpavatar_file_id_listtrong payload tổng hợp của sản phẩm. - Storefront API (
/site/products/...): Ánh xạ danh sách file từavatar_file_id_listsang trườngthumbnailscho giao diện website. - Xác thực & Fallback ảnh biến thể (
GET /v1/products/avatar): Khi truy xuất ảnh đại diện qua endpoint/v1/products/avatar, hệ thống kiểm trafile_idcó thuộcavatar_file_id_listcủa sản phẩm hay không. Nếu truy vấn theo biến thể (product_variant_id) mà biến thể đó chưa được gán ảnh riêng (photo_gallery_file_id_listrỗng), hệ thống sẽ tự động fallback về kiểm tra trongavatar_file_id_listcủa sản phẩm cha.
- Product Object (
- Hỗ trợ đa ngôn ngữ (
translations):- Trong trường hợp công ty sử dụng tính năng đa ngôn ngữ sản phẩm, mỗi phần tử ngôn ngữ trong mảng
translations(khi gọiPUT /v1/products/:idhoặcPATCH /v1/products/:id) có thể truyềnavatar_file_id_list(hoặcavatar_file.file_id_list) để ghi đè bộ ảnh đại diện riêng cho ngôn ngữ đó (lưu tại cộtpt_avatarfileidlisttrongProductTranslation).
- Trong trường hợp công ty sử dụng tính năng đa ngôn ngữ sản phẩm, mỗi phần tử ngôn ngữ trong mảng
Ví dụ Request Body
Ví dụ payload đầy đủ (tham khảo từ dữ liệu thực tế) khi cập nhật một sản phẩm đang hoạt động:
{
"company_id": 10311,
"creator_id": 1,
"name": "Áo Thun Nam BT TEST 01",
"name_short": "",
"summary": "",
"description": "",
"code": "AT.BT.TS001",
"options": [
{
"option_id": 8,
"use_image": 1,
"option_values": [
{
"option_id": 8,
"option_value_id": 4,
"option_value_name": "Đen",
"uuid": "4abdd739-a132-49bd-9ed8-341ae6d48bbc",
"file_id_list": [],
"file_list": [],
"meta": []
}
]
},
{
"option_id": 9,
"use_image": 1,
"option_values": [
{
"option_id": 9,
"option_value_id": 14,
"option_value_name": "L",
"uuid": "7d66253a-9c87-43f2-996b-712e015aa992",
"file_id_list": [],
"file_list": [],
"meta": []
},
{
"option_id": 9,
"option_value_id": 84,
"option_value_name": "S",
"uuid": "70348955-c609-41b0-9b29-ca596d2af292",
"file_id_list": [],
"file_list": [],
"meta": []
},
{
"option_id": 9,
"option_value_id": 85,
"option_value_name": "M",
"uuid": "4606380c-9acb-48c2-a810-d2ceb4892e8d",
"file_id_list": [],
"file_list": [],
"meta": []
}
]
}
],
"external_id": "",
"category_primary": 212,
"category_id_list": [],
"brand_id": 117,
"supplier_id": [36, 40, 41],
"sell_on_zero": 0,
"info_package": "",
"info_warranty": "",
"info_promotion": "",
"info_promotion_note": "",
"visibility": 1,
"installment": [],
"tax_ratio": 0,
"weight_sale_mode": 0,
"category_displayorder": [
{
"id": 212,
"label": "Áo thun",
"order": 9999
}
],
"weight_type": 1,
"weight_sale_mode": 0,
"weight_presets": [],
"physical_catch_weight_uom_id": 0,
"pricing_type": 1,
"allow_preorder": 0,
"default_variant_id": 0,
"country_of_origin": "",
"hs_code": "",
"badge": "",
"certification": "",
"status": 3,
"seo_url": "ao-thun-nam-bt-test-01",
"seo_title": "Áo Thun Nam BT TEST 01",
"seo_meta_description": "",
"seo_meta_keyword": "",
"seo_graph_file_id": 0,
"seo_canonical": "",
"seo_options": {},
"avatar_file_id_list": [4596],
"photo_gallery_file_id_list": [4597],
"photo360_file_id_list": [],
"embed_video_scripts": "[]",
"attribute_detail": [],
"tags": [
"ao-thun",
"bt-test-01"
],
"note": "",
"product_uoms": [
{
"company_id": 10311,
"creator_id": 15526,
"uom_id": 1000,
"allow_sale": 1,
"allow_purchase": 1,
"allow_stock": 1,
"factor": 1,
"weight": 320,
"is_default": 1,
"display_order": 0,
"icon_svg": "",
"file_id_list": [],
"file_list": []
}
],
"booking_attachable": 0,
"need_customize": 0,
"mockup_supported": 0,
"config3d_supported": 0,
"material_type": 0,
"length": 100,
"width": 100,
"height": 100,
"packing_priority": 100,
"page_id": 0,
"default_warehouse_location_id": 10003,
"lead_time": 0,
"expiry_tracked": 0
}Response Schema
HTTP 200 - OK
Trả về Product Object sau khi cập nhật.
Error Codes
Lỗi dữ liệu đầu vào. Trả về mảng các mã lỗi:
| Mã lỗi | Mô tả |
|---|---|
error_product_permission_not_found | Không có quyền chỉnh sửa sản phẩm (cần product.manage hoặc product.managecontent) |
error_name_require | Tên sản phẩm không được để trống |
error_name_duplicated | Tên sản phẩm đã tồn tại |
error_code_existed | Mã sản phẩm (code) đã tồn tại |
error_external_id_existed | External ID đã tồn tại |
error_status_not_exist | Trạng thái không hợp lệ |
error_brand_not_valid | ID thương hiệu không hợp lệ |
error_supplier_not_valid | ID nhà cung cấp không hợp lệ |
error_category_not_valid | ID danh mục không hợp lệ |
error_option_id_invalid(ID #X) | ID tùy chọn (option) không hợp lệ |
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_option_value_file_id_list_invalid(Name #X, inside Option ID #Y) | File ID trong giá trị tùy chọn không hợp lệ |
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 |