Lấy danh sách danh mục sản phẩm

API này giúp bạn lấy danh sách các danh mục sản phẩm có trong hệ thống. Bạn có thể sử dụng các tham số (params) như page, limit để phân trang kết quả trả về.

Chỉ trả về danh mục gốc — kèm danh mục con

API chỉ trả về các danh mục gốc (không có danh mục cha). Danh mục con của mỗi danh mục gốc được trả kèm trong trường children của danh mục đó.

---

Endpoint

🔗Endpoint Staging

GET https://staging-manage.api.miniai.vn/api/external/v1/categories

Example

https://staging-manage.api.miniai.vn/api/external/v1/categories?limit=5&page=1

🔗Endpoint Production

GET https://manage-api.miniap.vn/api/external/v1/categories

Xác thực (Authentication)

Mọi request phải gửi kèm API key của bạn trong header:

Header	Giá trị	Yêu cầu
x-api-key	miniai-partner <API_KEY_CỦA_BẠN>	Bắt buộc

Không cần gửi shopId

Hệ thống tự động xác định gian hàng (shopId) từ API key của bạn và gán vào request. Vì vậy bạn không cần gửi shopId trong query — kết quả trả về luôn là danh mục của gian hàng tương ứng với API key.

Tham số truy vấn (Query Parameters)

Tất cả tham số đều là tùy chọn.

Tham số	Kiểu	Yêu cầu	Mặc định	Mô tả
page	number	Tùy chọn	1	Trang cần lấy, số nguyên ≥ 1.
limit	number	Tùy chọn	10	Số danh mục mỗi trang, tối đa 50. Gửi -1 để lấy toàn bộ.
sortBy	string	Tùy chọn	createdAt	Tên trường dùng để sắp xếp (vd: name, position, createdAt).
sortOrder	string	Tùy chọn	desc	Thứ tự sắp xếp: asc (tăng dần) hoặc desc (giảm dần).

Lấy toàn bộ danh mục với limit=-1

Gửi limit=-1 để bỏ phân trang và nhận tất cả danh mục gốc trong một lần gọi. Khi đó hãy bỏ qua các giá trị phân trang trong meta (limit, totalPages) — chỉ total là có ý nghĩa.

Ví dụ Request

cURL

curl -X GET 'https://staging-manage.api.miniai.vn/api/external/v1/categories?page=1&limit=5&sortBy=createdAt&sortOrder=desc' \
  -H 'x-api-key: miniai-partner <API_KEY_CỦA_BẠN>'

Phản hồi (Response)

Thành công trả về mã 200. Danh sách danh mục nằm trong data.categories, thông tin phân trang nằm trong meta (cùng cấp với data).

Response

{
    "success": true,
    "data": {
        "categories": [
            {
                "_id": "68c6dcd4938bb4fca9e005fc",
                "type": "product",
                "name": "Danh mục migrate",
                "slug": "danh-mc-migrate",
                "images": [
                    "https://dmcl0k8mc5oht.cloudfront.net/64204a17a5a97a86f12e1f0a/541877a8-053e-4f28-b55f-1ad0c75579f8.jpeg"
                ],
                "subItemsGroupIDs": [],
                "shopId": "64204a17a5a97a86f12e1f0a",
                "status": "active",
                "createdAt": "2025-09-14T15:18:44.114Z",
                "updatedAt": "2025-09-14T15:19:03.068Z",
                "__v": 0,
                "position": 1,
                "children": [],
                "id": "68c6dcd4938bb4fca9e005fc"
            },
            {
                "images": [],
                "subItemsGroupIDs": [],
                "_id": "68c3896389abbc33d8e8d7b8",
                "type": "product",
                "name": "Sản phẩm nổi bật",
                "slug": "hot-products",
                "sCategoryId": "1004537153",
                "storeId": "200001061016",
                "shopId": "64204a17a5a97a86f12e1f0a",
                "platform": "haravan",
                "status": "active",
                "createdAt": "2025-09-12T02:45:55.486Z",
                "updatedAt": "2025-09-16T08:31:48.796Z",
                "children": [],
                "id": "68c3896389abbc33d8e8d7b8"
            },
            {
                "images": [],
                "subItemsGroupIDs": [],
                "_id": "68c3896389abbc33d8e8d7b7",
                "type": "product",
                "name": "Sản phẩm khuyến mãi",
                "slug": "onsale",
                "sCategoryId": "1004537152",
                "storeId": "200001061016",
                "shopId": "64204a17a5a97a86f12e1f0a",
                "platform": "haravan",
                "status": "active",
                "createdAt": "2025-09-12T02:45:55.486Z",
                "updatedAt": "2025-09-16T08:31:48.796Z",
                "children": [],
                "id": "68c3896389abbc33d8e8d7b7"
            },
            {
                "images": [],
                "subItemsGroupIDs": [],
                "_id": "68c3896389abbc33d8e8d7b6",
                "type": "product",
                "name": "Trang chủ",
                "slug": "frontpage",
                "sCategoryId": "1004537151",
                "storeId": "200001061016",
                "shopId": "64204a17a5a97a86f12e1f0a",
                "platform": "haravan",
                "status": "active",
                "createdAt": "2025-09-12T02:45:55.486Z",
                "updatedAt": "2025-09-16T08:31:48.806Z",
                "children": [],
                "id": "68c3896389abbc33d8e8d7b6"
            },
            {
                "subItemsGroupIDs": [],
                "_id": "68c28f92b4a7efbfddf4eb9b",
                "type": "product",
                "name": "Haravan",
                "slug": "other-haravan",
                "images": [
                    "https://bizweb.dktcdn.net/thumb/1024x1024/100/438/295/products/haravan-01.png"
                ],
                "shopId": "64204a17a5a97a86f12e1f0a",
                "platform": "haravan",
                "status": "active",
                "createdAt": "2025-09-11T09:00:02.134Z",
                "updatedAt": "2025-09-11T09:00:02.134Z",
                "children": [],
                "id": "68c28f92b4a7efbfddf4eb9b"
            }
        ]
    },
    "meta": {
        "total": 42,
        "page": 1,
        "limit": 5,
        "totalPages": 9
    }
}

Các trường trong data.categories[]

Trường	Kiểu	Mô tả
id / _id	string	ID của danh mục — dùng làm categoryId khi tạo sản phẩm
type	string	Luôn là product
name	string	Tên danh mục
slug	string	Đường dẫn thân thiện của danh mục
images	string[]	Danh sách URL ảnh của danh mục
status	string	active hoặc inactive
position	number	Thứ tự hiển thị (nếu có)
children	object[]	Danh sách danh mục con — cùng cấu trúc với danh mục gốc
shopId	string	ID gian hàng
platform	string	Nền tảng nguồn nếu danh mục được đồng bộ từ hệ thống khác (vd: haravan)
sCategoryId	string	ID danh mục trên nền tảng nguồn (chỉ có với danh mục đồng bộ)
storeId	string	ID cửa hàng trên nền tảng nguồn (chỉ có với danh mục đồng bộ)
subItemsGroupIDs	string[]	Danh sách ID nhóm sản phẩm con (nếu có)
createdAt	string	Thời điểm tạo (ISO 8601)
updatedAt	string	Thời điểm cập nhật gần nhất (ISO 8601)

Các trường trong meta

Trường	Kiểu	Mô tả
total	number	Tổng số danh mục gốc của gian hàng (mọi trang)
page	number	Trang hiện tại
limit	number	Số danh mục mỗi trang
totalPages	number	Tổng số trang

Lỗi thường gặp

Mã	Nguyên nhân
400	Tham số sai kiểu (page/limit không phải số), limit vượt quá 50, sortOrder không phải asc/desc
401	Thiếu header x-api-key, sai tiền tố miniai-partner , hoặc API key không hợp lệ
429	Vượt giới hạn số request (xem mục Giới hạn bên dưới)
500	Lỗi hệ thống

Lỗi 400 - Validation

{
    "statusCode": 400,
    "error": "Bad Request",
    "message": "Validation failed",
    "validation": {
        "query": {
            "source": "query",
            "keys": ["limit"],
            "message": "\"limit\" must be less than or equal to 50"
        }
    }
}

Lỗi 401 - Xác thực

Phản hồi là chuỗi văn bản thuần (không phải JSON):

Unauthorized

Lỗi 429 - Quá giới hạn

{
    "error": "Too many requests, limit to 100 requests per minute"
}

Giới hạn (Rate limit)

100 request / phút

Mỗi gian hàng được gọi tối đa 100 request mỗi phút trên toàn bộ External API. Vượt quá giới hạn sẽ nhận mã 429.

Các bước tiếp theo

Với id của danh mục, bạn có thể:

• Tạo sản phẩm mới — gán sản phẩm vào danh mục qua categoryId
• Cập nhật sản phẩm — đổi danh mục của sản phẩm đã có
• Lấy danh sách sản phẩm — truy xuất sản phẩm trong gian hàng