OVIRO LogoOVIRO
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.manage hoặc product.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ền product.managecontent mới được phép ghi nhận thay đổi).

Request Body

TrườngKiểuBắt buộcMô tả
company_idintCóID công ty
creator_idintCóID người thao tác
namestringCóTên sản phẩm
name_shortstringKhôngTên ngắn của sản phẩm
codestringKhôngMã sản phẩm. Phải là duy nhất.
external_idstringKhôngID tham chiếu hệ thống ngoài. Phải là duy nhất.
statusintCó1 (Nháp), 3 (Hoạt động), 5 (Lưu trữ/Đã xóa)
category_primaryintKhôngID danh mục chính
category_id_listarrayKhôngDanh sách ID danh mục phụ
brand_idintKhôngID thương hiệu
supplier_idarrayKhôngDanh sách ID nhà cung cấp
optionsarrayKhôngCấu trúc tùy chọn biến thể (Size, Color...)`
sell_on_zerointKhông1: 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.
visibilityintKhôngTrạng thái hiển thị sản phẩm
installmentarrayKhôngCấu hình trả góp
tax_ratiofloatKhôngThuế suất (%)
weight_sale_modeintKhôngChế độ bán theo trọng lượng (chỉ dùng khi weight_type là trọng lượng)
weight_presetsarrayKhôngCác mức cân nặng định sẵn
physical_catch_weight_uom_idintKhôngĐơn vị tính vật lý cho Catch weight (khi weight_sale_mode là Counting)
pricing_typeintKhôngLoại định giá
allow_preorderintKhôngCho phép đặt hàng trước
default_variant_idintKhôngID biến thể mặc định
country_of_originstringKhôngXuất xứ
hs_codestringKhôngHS Code
tagsarrayKhôngDanh sách tag
notestringKhôngGhi chú nội bộ
attribute_detailarrayKhôngThông tin thuộc tính chi tiết
category_displayorderarrayKhôngThứ tự hiển thị theo danh mục
need_customizeintKhông1: Cần tùy biến trước khi bán
mockup_supportedintKhông1: Hỗ trợ mockup
config3d_supportedintKhông1: Hỗ trợ cấu hình 3D
material_typeintKhôngLoại vật liệu
lengthintKhôngChiều dài (dùng cho logistics/đóng gói)
widthintKhôngChiều rộng
heightintKhôngChiều cao
packing_priorityintKhôngĐộ ưu tiên khi sắp xếp đóng gói
page_idintKhôngID trang nội dung liên kết
default_warehouse_location_idintKhôngVị trí kho mặc định
lead_timeintKhôngThời gian chuẩn bị hàng (ngày)
expiry_trackedintKhông1: Theo dõi hạn sử dụng
badgestringKhôngNhãn hiển thị (Mới, Hot, ...)
certificationstringKhôngThông tin chứng nhận
summarystringKhôngTóm tắt sản phẩm
descriptionstringKhôngMô tả chi tiết
info_packagestringKhôngThông tin đóng gói
info_warrantystringKhôngThông tin bảo hành
info_promotionstringKhôngThông tin khuyến mãi
info_promotion_notestringKhôngGhi chú khuyến mãi
seo_urlstringKhôngURL SEO (nếu trống sẽ được auto-gen từ name + code)
seo_titlestringKhôngTiêu đề SEO
seo_meta_descriptionstringKhôngMô tả Meta SEO
seo_meta_keywordstringKhôngTừ khóa SEO
seo_graph_file_idintKhôngID ảnh dùng cho Open Graph
seo_canonicalstringKhôngCanonical URL
seo_optionsarrayKhôngCác tùy chọn SEO khác
avatar_file_id_listarray<int>KhôngDanh 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_listarray<int>KhôngDanh sách ID ảnh thư viện. Yêu cầu quyền product.managecontent.
photo360_file_id_listarray<int>KhôngDanh sách ID ảnh 360. Yêu cầu quyền product.managecontent.
embed_video_scriptsstringKhôngScript nhúng video. Yêu cầu quyền product.managecontent.
product_uomsarrayKhôngDanh sách đơn vị tính quy đổi (nếu có), được xử lý riêng qua processProductUom()
translationsarrayKhôngDanh 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 $avatarfileidlist và lưu xuống cột p_avatarfileidlist (varchar(512)) dưới dạng chuỗi ID phân cách bằng dấu phẩy thông qua BaseModel::idListEncoder() (và giải mã thành mảng qua BaseModel::idListDecoder()).
  • Quyền hạn & Cơ chế ghi đè khi cập nhật:
    • Endpoint PUT /v1/products/:id cho phép truy cập khi người dùng có quyền product.manage hoặc product.managecontent.
    • Tuy nhiên, avatar_file_id_list nằm trong nhóm trường nội dung/media và chỉ được xử lý khi tài khoản có quyền product.managecontent. Nếu người gọi chỉ có quyền product.manage, giá trị avatar_file_id_list gử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/:id không hỗ trợ cập nhật trực tiếp avatar_file_id_list ở cấp sản phẩm gốc (chỉ hỗ trợ cập nhật qua PUT /v1/products/:id, hoặc cập nhật bản dịch qua trường translations).
  • 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 trong avatar_file_id_list. Trên Storefront, phần tử thứ hai (avatar_file_id_list[1], tương ứng thumbnails[1]) được dùng cho hiệu ứng đổi ảnh khi di chuột qua thẻ sản phẩm (change_image hover effect).
  • 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 ID avatar_file_id_list, response tự động hydrate và trả về thêm trường avatar_file_list chứa danh sách đối tượng File chi 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ếp avatar_file_id_list trong 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_list sang trường thumbnails cho 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 tra file_id có thuộc avatar_file_id_list củ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_list rỗng), hệ thống sẽ tự động fallback về kiểm tra trong avatar_file_id_list của sản phẩm cha.
  • 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ọi PUT /v1/products/:id hoặc PATCH /v1/products/:id) có thể truyền avatar_file_id_list (hoặc avatar_file.file_id_list) để ghi đè bộ ảnh đại diện riêng cho ngôn ngữ đó (lưu tại cột pt_avatarfileidlist trong ProductTranslation).

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ỗiMô tả
error_product_permission_not_foundKhông có quyền chỉnh sửa sản phẩm (cần product.manage hoặc product.managecontent)
error_name_requireTên sản phẩm không được để trống
error_name_duplicatedTên sản phẩm đã tồn tại
error_code_existedMã sản phẩm (code) đã tồn tại
error_external_id_existedExternal ID đã tồn tại
error_status_not_existTrạng thái không hợp lệ
error_brand_not_validID thương hiệu không hợp lệ
error_supplier_not_validID nhà cung cấp không hợp lệ
error_category_not_validID 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_requiredID công ty không được để trống
error_company_id_notfoundID công ty không tìm thấy
error_user1_id_requiredID người tạo không được để trống
error_user_id_notfoundID người tạo không tìm thấy

On this page