Lấy danh sách tag khách hàng

API này trả về danh sách tag khách hàng của gian hàng (ví dụ "Khách VIP", "Khách mới"). Bạn có thể dùng page, limit để phân trang kết quả.

Dùng để ghép với hashTags của khách hàng

Mỗi khách hàng trong danh sách khách hàng có trường hashTags là mảng ID tag. id trả về ở API này khớp với các phần tử trong hashTags đó.

---

Endpoint

🔗Endpoint Staging

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

Example

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

🔗Endpoint Production

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

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à tag 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	50	Số tag mỗi trang, số nguyên từ 1 đến 100.

Kết quả luôn được sắp xếp mới nhất trước (theo createdAt giảm dần).

Ví dụ Request

cURL

curl -X GET 'https://staging-manage.api.miniai.vn/api/external/v1/tags?page=1&limit=50' \
  -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 tag nằm trong data.tags, thông tin phân trang nằm trong data.meta.

Response

{
    "success": true,
    "data": {
        "tags": [
            {
                "_id": "6653000000000000000000a1",
                "id": "6653000000000000000000a1",
                "tag": "Khách VIP",
                "description": "Chi tiêu > 5tr",
                "type": "manual",
                "color": "#3B82F6",
                "createdAt": "2026-09-10T02:00:00.000Z",
                "updatedAt": "2026-09-10T02:00:00.000Z"
            }
        ],
        "meta": {
            "page": 1,
            "limit": 50,
            "total": 8,
            "totalPages": 1
        }
    }
}

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

Trường	Kiểu	Mô tả
id / _id	string	ID của tag — khớp phần tử trong hashTags của khách hàng
tag	string	Tên tag
description	string | null	Mô tả tag
type	string | null	Loại tag do gian hàng đặt khi tạo
color	string	Mã màu hiển thị của tag (mặc định #3B82F6)
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 data.meta

Trường	Kiểu	Mô tả
total	number	Tổng số tag của gian hàng (mọi trang)
page	number	Trang hiện tại
limit	number	Số tag 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ố nguyên), page < 1, limit ngoài khoảng 1–100
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 100"
        }
    }
}

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

• Lấy danh sách khách hàng — ghép hashTags của khách với id tag ở trên