Danh mục

Tổng quan

Danh mục là dữ liệu tham chiếu khi tạo đơn: dòng hàng trỏ tới biến thể sản phẩm, địa chỉ giao trỏ tới mã tỉnh / phường.

Method + path	Scope	Dùng để
GET /products	products_list	Sản phẩm kèm biến thể (keyset)
GET /address/provinces	—	Tỉnh / thành phố
GET /address/wards?provinceCode=	—	Phường / xã của một tỉnh

Trạng thái đơn ở GET /order-statuses, trường tuỳ chỉnh ở GET /custom-fields.

---

Sản phẩm

GET /api/open/v1/products?updatedSince=2026-10-01T00:00:00Z&limit=50

Phân trang keyset, tối đa 50 sản phẩm / lần. Danh mục không giới hạn khoảng 30 ngày (không nhận updatedUntil) — tải toàn bộ được bằng cách đi theo nextCursor. Trả { "data": [sản phẩm…], "nextCursor": … }:

{
  "data": [
    {
      "id": "c3a9…",
      "name": "Áo thun basic",
      "unit": "cái",
      "categoryId": "8d10…",
      "isActive": true,
      "variants": [
        {
          "id": "3e8b…",
          "sku": "AO-THUN-M",
          "barcode": "8936012345678",
          "name": "Trắng / M",
          "attributes": { "Màu": "Trắng", "Size": "M" },
          "price": 150000,
          "vatRate": 0,
          "isActive": true,
          "trackInventory": true,
          "stockQuantity": 42
        }
      ],
      "createdAt": "2026-09-01T02:00:00.000Z",
      "updatedAt": "2026-10-07T09:30:00.000Z"
    }
  ],
  "nextCursor": null
}

• Dòng hàng của đơn gửi variantId hoặc sku của biến thể. price là giá niêm yết — đơn dùng unitPrice bạn gửi.
• Danh sách gồm cả sản phẩm / biến thể ngừng bán (isActive: false) để bạn biết mà tắt bên mình.

Đồng bộ một lần, cập nhật theo updatedSince

Lần đầu tải toàn bộ danh mục (gọi theo nextCursor đến hết), lưu variantId ↔ SKU bên bạn. Các lần sau chỉ lấy updatedSince = thời điểm lần đồng bộ trước.

---

Địa chỉ hành chính

Danh mục theo đơn vị hành chính hiện hành (tỉnh → phường / xã). Không cần scope; có thể cache 1 ngày.

GET /api/open/v1/address/provinces

{
  "data": [
    { "code": "01", "name": "Hà Nội", "fullName": "Thành phố Hà Nội", "type": "thanh-pho" },
    { "code": "79", "name": "Hồ Chí Minh", "fullName": "Thành phố Hồ Chí Minh", "type": "thanh-pho" }
  ]
}

GET /api/open/v1/address/wards?provinceCode=01

{
  "data": [
    { "code": "00070", "name": "Hoàn Kiếm", "fullName": "Phường Hoàn Kiếm", "type": "phuong", "provinceCode": "01" }
  ]
}

Gửi code vào shippingProvinceCode / shippingWardCode khi tạo đơn. Mã sai, hoặc phường không thuộc tỉnh, sẽ làm dòng đơn đó lỗi.