> For the complete documentation index, see [llms.txt](https://docs.caresoft.vn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caresoft.vn/danh-muc/restful-api-cua-caresoft/khach-hang.md).
# Khách hàng
Trên hệ thống CareSoft. Mỗi người dùng/Khách hàng được định nghĩa bằng số điện thoại hoặc email. Một người dùng có tối đa ba (03) số điện thoại và hai (02) email làm định danh.
### Các trường thông tin của người dùng
Thời điểm thu thập được số điện thoại (Null hoặc Ngày tháng)
22
take_email_at
DATETIME
Thời điểm thu thập được email(Null hoặc Ngày tháng)
## Thêm mới khách hàng
Để thêm mới khách hàng. Lập trình viên cần tạo 1 đối tượng contact kiểu Json Object có cấu trúc sau. Các trường dữ liệu
{% code title="Mẫu body request tạo khách hàng" %}
```json
{
"contact": {
"email": "{{Email khách hàng}}",
"phone_no": "{{Số điện thoại khách hàng}}",
"username": "{{Họ tên của khách hàng",
"address":"{{Địa chỉ khách hàng}}",
"gender":"{{Giới tính của khách hàng}}"
"custom_fields": [
{
"id": {{ID trường động khách hàng}},
"value": "{{Giá trị trường động}}"
}
]
}
}
```
{% endcode %}
Ví dụ tham khảo mẫu POSTMAN tạo mới khách hàng
## Thêm mới khách hàng
`POST` `{{domain}/api/v1/contacts`
#### Headers
| Name | Type | Description |
| ---- | ------ | --------------------------------------------------------------------- |
| \*\* | String | [Thông tin xác thực chung ](/thong-tin-chung.md#phuong-thuc-xac-thuc) |
#### Request Body
| Name | Type | Description |
| ------- | ------ | ---------------------- |
| contact | Object | Cấu trúc object ở trên |
{% tabs %}
{% tab title="200: OK " %}
{% tabs %}
{% tab title="Kết quả điển hình" %}
```json
{
"code": "ok",
"contact": {
"phone_no": "024***22",
"updated_at": "2023-04-12 14:54:24",
"created_at": "2023-04-12 14:54:24",
"id": 63216006,
"email": "uyel**@**l.com",
"username": "Le ***yen"
}
}
```
{% endtab %}
{% tab title="Mô tả trường thông tin điển hình" %}
{% endtab %}
{% endtabs %}
{% endtab %}
{% tab title="400: Bad Request " %}
Thông tin trùng lặp hoặc thiếu sẽ thể hiện qua thông báo lỗi này
{% tabs %}
{% tab title="Trùng email" %}
{% endtab %}
{% tab title="Trùng số điện thoại" %}
```json
{
"code": "errors",
"message": "phone_no already exist",
"extra_data": {
"duplicate_id": "63216007"
}
}
```
{% endtab %}
{% endtabs %}
{% endtab %}
{% tab title="500: Internal Server Error " %}
{% endtab %}
{% tab title="401: Unauthorized " %}
{% endtab %}
{% endtabs %}
## Cập nhật khách hàng
Trong trường hợp có thay đổi thông tin khách hàng, VD: Thay đổi số điện thoại, email hay thông tin người phụ trách hoặc các thông tin phân loại được tùy biến. Lập trình viên sử dụng hàm này để cập nhật dữ liệu lên hệ thống
{% hint style="info" %}
Gợi ý: Trong một số trường hợp không lưu contactId của khách hoặc khách phát sinh trước khi tích hợp, thì sử dụng hàm tạo mới khách hàng sau đó dựa trên `dublicated_id` phát sinh (nếu trùng) để thực hiện cập nhật
{% endhint %}
## Cập nhật người dùng
`PUT` `{{domain}/api/v1/contacts/{{contactId}}`
#### Headers
| Name | Type | Description |
| -------------------------------------- | ------ | --------------------------------------------------------------------- |
| \*\*\* | String | [Thông tin xác thực chung ](/thong-tin-chung.md#phuong-thuc-xac-thuc) |
#### Request Body
| Name | Type | Description |
| ------- | ------ | ---------------------------------- |
| contact | Object | Cấu trúc object như ví dụ minh họa |
{% tabs %}
{% tab title="200: OK " %}
{% tabs %}
{% tab title="Kết quả điển hình" %}
```
{
"code": "ok",
"contact": {
"phone_no": "024***22",
"updated_at": "2023-04-12 14:54:24",
"created_at": "2023-04-12 14:54:24",
"id": 63216006,
"email": "uyel**@**l.com",
"username": "Le ***yen"
}
}
```
{% endtab %}
{% endtabs %}
{% endtab %}
{% tab title="400: Bad Request " %}
{% endtab %}
{% tab title="500: Internal Server Error " %}
{% endtab %}
{% endtabs %}
## Danh sách khách hàng
Là dữ liệu biến thiên theo ngày tháng. Sẽ tăng dần theo thời gian, Danh sách này có kết quả gồm số ít trường thông tin mang tính chất điển hình gồm ID, số điện thoại, họ tên, email ngày tạo. Dựa vào danh sách này có thể lấy thông tin đầy đủ và chi tiết cho 1 khách hàng bằng api Chi tiết khách hàng phía dưới
Mẫu tham khảo cấu hình POSTMAN lấy danh sách khách hàng
## Danh sách khách hàng V2
> ### Thông báo chuyển đổi API
>
> API GET {{domain}}/api/v1/contacts sẽ kết thúc vào ngày 02/09/2026. Sau thời điểm này, hệ thống sẽ tự động chuyển sang endpoint V2 tương ứng:
>
> Để tránh gián đoạn tích hợp, bạn nên chuyển sang V2 trước thời điểm trên. Trong giai đoạn chuyển đổi, API V1 vẫn có thể hoạt động nhưng sẽ được đánh dấu là deprecated.
Dữ liệu được cập nhật theo thời gian. Danh sách trả về một số trường thông tin cơ bản, điển hình như Phiên bản V2 vẫn giữ cấu trúc response gần tương tự V1 để thuận tiện chuyển đổi, đồng thời bổ sung các mốc thời gian thực tế sau khi hệ thống chuẩn hóa khoảng thời gian truy vấn.
### Danh sách khách hàng V2
`GET` `{{domain}}/api/v2/contacts`
**Query Parameters**
| Name | Type | Description |
| --------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `updated_since` | DateTime (ISO8601) | Thời điểm bắt đầu cập nhật. Định dạng: YYYY-MM-DDTHH:mm:ssZ |
| `updated_to` | DateTime (ISO8601) | Thời điểm kết thúc cập nhật. Định dạng: YYYY-MM-DDTHH:mm:ssZ |
| `created_since` | DateTime (ISO8601) | Thời điểm bắt đầu tạo. Định dạng: YYYY-MM-DDTHH:mm:ssZ |
| `created_to` | DateTime (ISO8601) | Thời điểm kết thúc tạo. Định dạng: YYYY-MM-DDTHH:mm:ssZ |
| `page` | Int | Trang số. Mặc định `1` |
| `count` | Int | Số bản ghi trên trang. Mặc định `50`, tối đa theo cấu hình hệ thống |
| `order_by` | String | Sắp xếp theo trường dữ liệu. Hỗ trợ: `id`, `username`, `email`, `email2`, `phone_no`, `phone_no2`, `phone_no3`, `facebook`, `gender`, `organization_id`, `created_at`, `updated_at`. Mặc định `created_at` |
| `order_type` | String | Kiểu sắp xếp `DESC` hoặc `ASC`. Mặc định `DESC` |
**Headers**
| Name | Type | Description |
| ----- | ------ | ------------------------ |
| `***` | String | Thông tin xác thực chung |
**Lưu ý khi sử dụng**
* Chỉ chấp nhận các query parameter nằm trong danh sách trên. Nếu truyền parameter ngoài whitelist, hệ thống trả về HTTP `400`.
* Nếu không có bất kỳ điều kiện ngày hợp lệ nào thuộc nhóm `created_*` hoặc `updated_*`, hệ thống sẽ trả về danh sách rỗng để tránh quét toàn bộ dữ liệu khách hàng.
* Mỗi cặp điều kiện thời gian `created_since/created_to` hoặc `updated_since/updated_to` chỉ được xử lý trong phạm vi tối đa `31 ngày`.
**Quy tắc xử lý thời gian**
* Nếu truyền đủ `created_since` và `created_to`:
* Nếu khoảng thời gian không quá `31 ngày` thì giữ nguyên.
* Nếu quá `31 ngày` hoặc `created_since >= created_to` thì hệ thống tự chuẩn hóa thành `created_since = created_to - 31 days`.
* Nếu chỉ truyền `created_since`, hệ thống tự bổ sung `created_to = created_since + 31 days`.
* Nếu chỉ truyền `created_to`, hệ thống tự bổ sung `created_since = created_to - 31 days`.
* Cặp `updated_since/updated_to` áp dụng quy tắc tương tự.
* Giá trị ngày không đúng định dạng hoặc nằm ngoài phạm vi hợp lệ sẽ được hiểu như chưa truyền.
**Kết quả điển hình**
```json
{
"code": "ok",
"numFound": 123,
"created_since": "2026-07-01T00:00:00Z",
"created_to": "2026-08-01T00:00:00Z",
"updated_since": null,
"updated_to": null,
"contacts": [
{
"id": 1001,
"username": "Nguyen Van A",
"email": "a@example.com",
"email2": null,
"phone_no": "0900000000",
"phone_no2": null,
"phone_no3": null,
"facebook": null,
"gender": 0,
"organization_id": null,
"created_at": "2026-07-15 09:30:00",
"updated_at": "2026-07-20 10:00:00"
}
]
}
```
#### Mô tả kết quả
| STT | Tên trường | Chú thích |
| --- | --------------- | ---------------------------------------------------------------------------- |
| 1 | `code` | Trạng thái thành công. `ok`: Thành công, `errors`: Thất bại |
| 2 | `numFound` | Số bản ghi tìm thấy theo điều kiện lọc |
| 3 | `created_since` | Thời điểm bắt đầu thực tế của điều kiện tạo sau khi hệ thống chuẩn hóa |
| 4 | `created_to` | Thời điểm kết thúc thực tế của điều kiện tạo sau khi hệ thống chuẩn hóa |
| 5 | `updated_since` | Thời điểm bắt đầu thực tế của điều kiện cập nhật sau khi hệ thống chuẩn hóa |
| 6 | `updated_to` | Thời điểm kết thúc thực tế của điều kiện cập nhật sau khi hệ thống chuẩn hóa |
| 7 | `contacts[]` | Mảng dữ liệu danh sách khách hàng |
Cấu trúc từng phần tử trong `contacts[]` gồm các trường điển hình sau:
* `id`: ID khách hàng
* `username`: Họ tên khách hàng
* `email`: Email chính
* `email2`: Email thứ 2
* `phone_no`: Số điện thoại thứ nhất
* `phone_no2`: Số điện thoại thứ 2
* `phone_no3`: Số điện thoại thứ 3
* `facebook`: Facebook ID
* `gender`: Giới tính
* `organization_id`: ID tổ chức
* `created_at`: Ngày tạo
* `updated_at`: Ngày cập nhật
**Ví dụ truy vấn**
```http
GET /api/v2/contacts?created_to=2026-07-31T00:00:00Z&page=1&count=50&order_by=created_at&order_type=DESC
```
Trong ví dụ trên, hệ thống sẽ tự chuẩn hóa khoảng thời gian và có thể trả về thêm các trường:
```json
{
"created_since": "2026-06-30T00:00:00Z",
}
Trước ngày 02/09/2026, endpoint GET {{domain}}/api/v1/contacts vẫn có thể hoạt động
để hỗ trợ quá trình chuyển đổi. Tuy nhiên, endpoint này đã được đánh dấu là deprecated.
Khuyến nghị chuyển sang GET {{domain}}/api/v2/contacts sớm nhất có thể.
Sau ngày 02/09/2026, API V1 sẽ ngừng hoạt động. Nếu tiếp tục gửi yêu cầu đến V1,
hệ thống sẽ tự động chuyển sang V2.
```
## Danh sách khách hàng (V1)
`GET` `{{domain}/api/v1/contacts`
API này sẽ ngừng hoạt động sau ngày 02/09/2026. Vui lòng chuyển sang V2 để tiếp tục sử dụng.
#### Query Parameters
| Name | Type | Description |
| -------------- | ------------------ | -------------------------------------------------------------------------------- |
| updated\_since | DateTime (ISO8601) | Thời điểm bắt đầu cập nhật. Định dạng: YYYY-MM-DDTHH:mm:ssZ |
| updated\_to | DateTime (ISO8601) | Thời điểm kết thúc cập nhật. Định dạng: YYYY-MM-DDTHH:mm:ssZ |
| created\_since | DateTime (ISO8601) | Thời điểm bắt đầu tạo. Định dạng: YYYY-MM-DDTHH:mm:ssZ |
| created\_to | DateTime (ISO8601) | Thời điểm kết thúc tạo. Định dạng: YYYY-MM-DDTHH:mm:ssZ |
| page | Int | Trang số |
| count | Int | Số bản ghi trên trang (Tối đa 500) |
| order\_by | String | Sắp xếp theo trường dữ liệu (mặc định created\_at) |
| order\_type | String |
Kiểu sắp xếp DESC hoặc ASC (Giảm dần hoặc tăng dần) Mặc định DESC
Mảng dữ liệu object các Zalo Oa mà khách đang theo dõi nếu Zalo_id có giá trị. Trong đó: - oa_name: Tên Zalo OA - oa_id: ID OA, - active: Trạng thái tích hợp của OA (1: Đang kích hoạt, 0. Ngừng kích hoạt) - follow_status: Trạng thái follow của khách ( 1: Đang follow, null / 0: Không follow hoặc đã hủy) - updated_at: Ngày cập nhật mới nhất
21
facebook
ID facebook
22
psid
Mảng dữ liệu object các Facebook Page khách hàng đang theo dõi nếu trường facebook có giá trị. Trong đó - page_id: ID của page - psid: ID của khách trên page
{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}
## Tìm khách hàng theo số điện thoại
Trong trường hợp cần tìm 1 khách hàng đã tồn tại hay chưa sử dụng API dưới đây, hệ thống sẽ trả về thông tin cơ bản của khách hàng.
(Mẫu Postman tham khảo)
## Tìm khách hàng theo số điện thoại
`GET` `{{domain}/api/v1/api/v1/contactsByPhone`
Sử dụng parametter phoneNo để tìm khách hàng (Xem ảnh mô tả)
#### Query Parameters
| Name | Type | Description |
| ----------------------------------------- | ------ | ------------------------------------------ |
| phoneNo\* | String | Số điện thoại của khách hàng (Dạng 0XXXXX) |
{% tabs %}
{% tab title="200: OK Kết quả thành công" %}
{% tabs %}
{% tab title="Kết quả điển hình" %}
{% endtab %}
{% endtabs %}
{% endtab %}
{% tab title="404: Not Found Không tìm thấy dữ liệu" %}
{% tabs %}
{% tab title="Kết quả điển hình" %}
```
{ "code": "errors", "message": "Not found user" }
```
{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}
[^1]: ID này dùng để thực hiện các tác vụ liên quan đến khách hàng này.\
Vd: Cập nhật thông tin cá nhân, Tạo phiếu ghi cho khách hàng
[^2]: ID khách hàng có email trùng khớp đang hiện hữu trên hệ thống
[^3]: