SubizTài liệu API
Sản phẩm

API 4.0

Tạo sản phẩm

Thêm sản phẩm vào danh mục, hoặc cập nhật theo ID sản phẩm của bạn.

POSThttps://api.subiz.com.vn/4.0/accounts/{accid}/products

Dùng endpoint này để thêm sản phẩm vào danh mục Subiz, ví dụ khi đồng bộ sản phẩm từ cửa hàng của bạn. Xem Định dạng sản phẩm để biết mọi trường.

Trước khi bắt đầu

  • Lấy Bearer access token và ID tài khoản.
  • Agent sở hữu token cần quyền tạo và cập nhật sản phẩm.

Body yêu cầu

Trường Kiểu Mô tả
name string Bắt buộc. Tên sản phẩm.
source_id string Nên có. ID sản phẩm của riêng bạn. Xem Tránh trùng lặp.
sku string Mã SKU.
price, market_price number Giá bán và giá tham chiếu.
currency string Đơn vị tiền tệ của giá, như VND.
stock integer Số lượng tồn kho.
availability string in_stock, out_of_stock, online_only, pre_order, pre_sale hoặc sold_out.
visibility string published (mặc định) hoặc hidden.
condition string new, refurbished hoặc used.
description, category, brand, url string Thông tin tùy chọn. category tối đa 255 byte.
image, images string, array URL ảnh. Subiz lưu bản sao riêng. Xem Hình ảnh.
props array Thuộc tính dạng cặp key/value.
product_group_id string Tùy chọn. Đưa sản phẩm vào một nhóm biến thể có sẵn. Xem Biến thể.

Đừng gửi id. Subiz bỏ qua và tự tạo ID. Subiz cũng tự đặt created, created_by, updated và updated_by.

Tránh trùng lặp

Trước khi tạo sản phẩm, Subiz tìm sản phẩm đã có:

  1. Nếu bạn gửi source_id, Subiz tìm sản phẩm có cùng source_id.
  2. Nếu bạn không gửi source_id, Subiz tìm sản phẩm có cùng sku.

Nếu tìm thấy, Subiz thay thế sản phẩm đó bằng các trường bạn gửi thay vì tạo sản phẩm mới. Các trường bạn bỏ trống sẽ bị xóa. Luôn gửi sản phẩm đầy đủ.

Đặt source_id là ID của sản phẩm trong hệ thống của bạn. Điều này giúp thử lại an toàn. Nếu không có cả source_id lẫn sku, mỗi yêu cầu tạo một sản phẩm mới.

Phản hồi

Yêu cầu thành công trả HTTP 200 cùng sản phẩm đã lưu. Một số trường:

{
  "id": "product_example",
  "account_id": "account_example",
  "source_id": "shop-sku-mug-01",
  "name": "Ceramic mug",
  "sku": "MUG-01",
  "price": 120000,
  "currency": "VND",
  "stock": 25,
  "availability": "in_stock",
  "visibility": "published",
  "product_group_id": "product_example",
  "created": 1763107200000,
  "updated": 1763107200000
}

Lưu id để đọc hoặc cập nhật sản phẩm sau này.

Lỗi

Vấn đề Kết quả
Thiếu name Lỗi dữ liệu không hợp lệ nêu tên name.
category dài hơn 255 byte Lỗi dữ liệu không hợp lệ nêu tên category.
availability, visibility hoặc condition có giá trị khác Lỗi trường không hợp lệ nêu tên trường.
Không tải được URL ảnh Yêu cầu thất bại.
Thiếu quyền Lỗi phân quyền.

Xem Xử lý lỗi để biết định dạng lỗi.

Yêu cầu HTTP

Thay YOUR_ACCID và YOUR_ACCESS_TOKEN bằng giá trị của bạn.

POST https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/products
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "source_id": "YOUR_SOURCE_PRODUCT_ID",
  "name": "Ceramic mug",
  "sku": "MUG-01",
  "price": 120000,
  "currency": "VND",
  "stock": 25,
  "availability": "in_stock"
}