# Danh sách khách hàng

* API này dùng để lấy [danh sách khách hàng](https://nhanh.vn/customer/code/customerlist).
* **Chú ý**: Nếu bạn hay thường xuyên cần gọi toàn bộ danh sách khách hàng, bạn nên lưu giá trị thời gian lần cuối cùng quét toàn bộ, sau đó dùng 2 request params là updatedAtFrom và updatedAtTo để chỉ lấy về các khách hàng có cập nhật mới, không cần gọi lại toàn bộ khách cũ không có thay đổi gì.

## Request

* Xem [common request params](/v3/readme.md#request-params).

```curl
curl --location 'https://pos.open.nhanh.vn/v3.0/customer/list?appId={{appId}}&businessId={{businessId}}' \
--header 'Authorization: {{accessToken}}' \
--header 'Content-Type: application/json'
--data '{
    "filters": {
        "type": 1,
        "updatedAtFrom": 1753981200
    },
    "paginator": {
        "size": 10
    }
}'
```

### Filters

| Key                | Type   | Description                                               |
| ------------------ | ------ | --------------------------------------------------------- |
| ids                | array  | Mảng ID khách hàng trên Nhanh.vn, tối đa 100.             |
| mobile             | string | Số điện thoại khách hàng. VD: 0988999999                  |
| lastBoughtDateFrom | string | Từ ngày mua cuối cùng (yyyy-mm-dd). VD: 2022-09-25        |
| lastBoughtDateTo   | string | Đến ngày mua cuối cùng (yyyy-mm-dd). VD: 2022-09-26       |
| updatedAtFrom      | int    | Ngày cập nhật khách hàng từ ngày (Định dạng timestamp)    |
| updatedAtTo        | int    | Ngày cập nhật khách hàng đến ngày (Định dạng timestamp)   |
| type               | int    | Loại khách hàng. (1 = Khách lẻ, 2 = Khách sỉ, 3 = Đại lý) |

## Response

* Xem cấu trúc chung [tại đây](/v3/readme.md#response).

### Failed response

* Xem các mã lỗi chung [tại đây](/v3/readme.md#failed-response).

### Successful response

```json
{
  "code": 1,
  "paginator": {
    "next": "Giá trị để lấy dữ liệu trang tiếp theo"
  },
  "data": [
    {
      "id": "(int) ID khách hàng",
      "type": "(int) Loại khách hàng (1 = Khách lẻ, 2 = Khách buôn, 3 = Đại lý)",
      "name": "(string) Tên khách hàng 1",
      "mobile": "(string) Số điện thoại khách hàng",
      "code": "(string) Mã khách hàng",
      "gender": "(int) Giới tính (1 = nam, 2 = nữ)",
      "address": "170 Đê La Thành - Đống Đa - Hà Nội",
      "email": "(string) Email khách hàng",
      "birthday": "(string) Ngày sinh của khách hàng (định dạng Y-m-d)",
      "points": "(int) Điểm tích lũy hiện tại của khách hàng",
      "saleName": "(string) Thông tin nhân viên được gắn cho khách hàng",
      "startedDate": "(string) Ngày bắt đầu mua hàng (định dạng Y-m-d)",
      "taxCode": "(string) Mã số thuế",
      "locations": {
        "cityId": "(int) ID tỉnh/thành phố",
        "districtId": "(int) ID quận/huyện",
        "wardId": "(int) ID phường xã"
      },
      "location": {
        "cityId": "(int) ID tỉnh/thành phố (Địa chỉ 2 cấp)",
        "wardId": "(int) ID phường xã (Địa chỉ 2 cấp)"
      },
      "business": {
        "name": "(string) Tên công ty",
        "address": "(string) Địa chỉ công ty"
      },
      "level": {
        "id": "(int) ID cấp độ khách hàng",
        "name": "(string) Tên cấp độ khách hàng"
      },
      "group": {
        "id": "(int) ID nhóm khách hàng",
        "name": "(string) Tên nhóm khách hàng"
      },
      "totalAmount": "(double) Tổng số tiền khách mua hàng",
      "updatedAt": "(int) Ngày cập nhật khách hàng"
    }
  ]
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://apidocs.nhanh.vn/v3/customer/list.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.