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

API này trả về danh sách khách hàng của gian hàng, kèm thông tin liên hệ, người giới thiệu, số đơn, chi tiêu, điểm và tag. Bạn có thể dùng page, limit, sortBy, sortType để phân trang và sắp xếp, và lọc theo thời điểm tạo / cập nhật bằng createdFrom, createdTo, updatedFrom, updatedTo.

Phạm vi khách hàng trả về

API chỉ trả về khách hàng có số điện thoại, chưa bị xoá và không phải khách vãng lai (guest). Số điện thoại trả về đầy đủ, không bị che.

---

Endpoint

🔗Endpoint Staging

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

Example

https://staging-manage.api.miniai.vn/api/external/v1/customers?limit=50&page=1&sortBy=createdAt&sortType=asc

🔗Endpoint Production

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

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à khách hàng 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ố khách mỗi trang, số nguyên từ 1 đến 50.
sortBy	string	Tùy chọn	createdAt	Trường dùng để sắp xếp: createdAt hoặc updatedAt.
sortType	string	Tùy chọn	desc	Thứ tự sắp xếp: asc (tăng dần) hoặc desc (giảm dần).
createdFrom	string (ISO 8601)	Tùy chọn	—	Chỉ lấy khách có createdAt ≥ giá trị này.
createdTo	string (ISO 8601)	Tùy chọn	—	Chỉ lấy khách có createdAt ≤ giá trị này.
updatedFrom	string (ISO 8601)	Tùy chọn	—	Chỉ lấy khách có updatedAt ≥ giá trị này.
updatedTo	string (ISO 8601)	Tùy chọn	—	Chỉ lấy khách có updatedAt ≤ giá trị này.

Lọc theo thời gian

Các tham số ngày dùng riêng hoặc kết hợp đều được, so sánh theo giờ UTC. Để lấy trọn một ngày, truyền mốc cuối ngày rõ ràng, ví dụ createdTo=2026-10-14T23:59:59.999Z.

Thứ tự ổn định khi phân trang

Khi nhiều khách có cùng giá trị sortBy, hệ thống xếp thêm theo ID khách hàng (cùng chiều sortType). Nhờ vậy lặp qua các trang sẽ không bị trùng hoặc sót khách có cùng thời điểm tạo.

Ví dụ Request

cURL

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

cURL - khách cập nhật từ một mốc

curl -X GET 'https://staging-manage.api.miniai.vn/api/external/v1/customers?page=1&limit=50&updatedFrom=2026-10-14T00:00:00.000Z&sortBy=updatedAt&sortType=asc' \
  -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 khách hàng nằm trong data.customers, thông tin phân trang nằm trong data.meta.

Response

{
    "success": true,
    "data": {
        "customers": [
            {
                "id": "6650a1b2c3d4e5f6a7b8c9d0",
                "info": {
                    "fullName": "Nguyễn Văn A",
                    "avatar": "https://s120-ava-talk.zadn.vn/a/b/c/avatar.jpg",
                    "phone": "0901234123",
                    "alias": "Anh A",
                    "lastLoginAt": "2026-10-07T08:12:00.000Z"
                },
                "initiatorReferrer": {
                    "id": "6650a1b2c3d4e5f6a7b8c9aa",
                    "fullName": "Trần Thị B",
                    "phone": "0912345678",
                    "avatar": "https://s120-ava-talk.zadn.vn/d/e/f/avatar.jpg"
                },
                "totalOrders": 5,
                "totalSpent": 1250000,
                "taskPoints": 300,
                "cumulativePoints": 1200,
                "hashTags": ["6653000000000000000000a1"],
                "createdAt": "2026-09-01T03:00:00.000Z",
                "updatedAt": "2026-10-07T08:12:00.000Z"
            }
        ],
        "meta": {
            "page": 1,
            "limit": 10,
            "total": 1534,
            "totalPages": 154
        }
    }
}

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

Trường	Kiểu	Mô tả
id	string	ID khách hàng
info.fullName	string	Tên khách hàng. Trả "Guest" khi khách chưa có tên
info.avatar	string	URL ảnh đại diện (nếu có)
info.phone	string	Số điện thoại đầy đủ, giữ nguyên định dạng đang lưu (09…, 84… hoặc +84…)
info.alias	string	Tên gợi nhớ do gian hàng đặt (nếu có)
info.lastLoginAt	string | null	Lần đăng nhập gần nhất (ISO 8601)
initiatorReferrer	object | null	Người giới thiệu khách: id, fullName, phone, avatar. null nếu không có
totalOrders	number	Số đơn hàng thành công
totalSpent	number	Tổng chi tiêu (VNĐ)
taskPoints	number	Điểm nhiệm vụ hiện có
cumulativePoints	number	Điểm tích luỹ
hashTags	string[]	Mảng ID tag của khách — khớp id trong danh sách tag
createdAt	string	Thời điểm tạo khách (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ố khách khớp điều kiện lọc (mọi trang)
page	number	Trang hiện tại
limit	number	Số khách mỗi trang
totalPages	number	Tổng số trang

Đồng bộ khách hàng

Lần đầu — kéo toàn bộ:

1. Gọi limit=50&sortBy=createdAt&sortType=asc&page=1.
2. Tăng page cho tới khi page = meta.totalPages.
3. Ghép hashTags của mỗi khách với danh sách tag.

Các lần sau — chỉ kéo phần thay đổi:

1. Gọi updatedFrom=<thời điểm lần đồng bộ trước>&sortBy=updatedAt&sortType=asc&limit=50.
2. Lặp page như trên.

Tiết kiệm hạn mức request

Hạn mức 100 request / phút dùng chung cho mọi External API của gian hàng. Với limit=50, 10.000 khách cần 200 request (khoảng 2 phút). Chỉ kéo toàn bộ một lần, các lần sau dùng updatedFrom để kéo phần thay đổi.

Lỗi thường gặp

Mã	Nguyên nhân
400	Tham số sai kiểu, page < 1, limit ngoài khoảng 1–50, sortBy khác createdAt/updatedAt, sortType khác asc/desc, ngày không đúng định dạng ISO 8601
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

• Lấy danh sách tag khách hàng — tra tên tag từ hashTags