# 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

<table><thead><tr><th width="64.33333333333331" data-type="number">STT</th><th width="193">Tên trường</th><th width="162">Kiểu dữ liệu<select><option value="2a353d3434774486ae86a359db22b0cc" label="TEXT(255)" color="blue"></option><option value="96eaa0bd08df4a6e82b19c30e681dd5a" label="INT" color="blue"></option><option value="8180e1a9201c46a6be4a6d9a0da2c4a3" label="SELECTONE" color="blue"></option><option value="fa06aa625469464899e2e5b3afa5ee5a" label="MULTIPLE SELECT" color="blue"></option><option value="01483ea447a642b28b8da91ad3260825" label="EMAIL" color="blue"></option><option value="f677b4cb982e427f8c0b1c017a4700bf" label="TELEPHONE" color="blue"></option><option value="68546980a4954142891f7a23a85a929d" label="DATETIME" color="blue"></option><option value="198ea03807404ef2b9bfce7b672fb269" label="DATE" color="blue"></option><option value="111c0ebfeb3b4edca5e073d8570cec43" label="ARRAY" color="blue"></option><option value="83a62d80fef041869490d60ef9fc3b17" label="OBJECT" color="blue"></option></select></th><th>Ghi chú</th></tr></thead><tbody><tr><td>1</td><td>id</td><td><span data-option="96eaa0bd08df4a6e82b19c30e681dd5a">INT</span></td><td>ID của người dùng</td></tr><tr><td>2</td><td>username</td><td><span data-option="2a353d3434774486ae86a359db22b0cc">TEXT(255)</span></td><td>Họ tên</td></tr><tr><td>3</td><td>email</td><td><span data-option="01483ea447a642b28b8da91ad3260825">EMAIL</span></td><td>Email người dùng</td></tr><tr><td>4</td><td>email2</td><td><span data-option="01483ea447a642b28b8da91ad3260825">EMAIL</span></td><td>Email thứ 2</td></tr><tr><td>5</td><td>phone_no</td><td><span data-option="f677b4cb982e427f8c0b1c017a4700bf">TELEPHONE</span></td><td>Số điện thoại của người dùng</td></tr><tr><td>6</td><td>phone_no2</td><td><span data-option="f677b4cb982e427f8c0b1c017a4700bf">TELEPHONE</span></td><td>Số điện thoại thứ 2</td></tr><tr><td>7</td><td>phone_no3</td><td><span data-option="f677b4cb982e427f8c0b1c017a4700bf">TELEPHONE</span></td><td>Số điện thoại thứ 3</td></tr><tr><td>8</td><td>created_at</td><td><span data-option="68546980a4954142891f7a23a85a929d">DATETIME</span></td><td>Ngày tạo</td></tr><tr><td>9</td><td>updated_at</td><td><span data-option="68546980a4954142891f7a23a85a929d">DATETIME</span></td><td>Ngày cập nhật.</td></tr><tr><td>10</td><td>created_from</td><td><span data-option="96eaa0bd08df4a6e82b19c30e681dd5a">INT</span></td><td>Nguồn tạo (<a href="phieu-ghi/danh-sach-nguon">Xem danh sách nguồn</a>) Cột Source ID</td></tr><tr><td>11</td><td>organization_id</td><td><span data-option="96eaa0bd08df4a6e82b19c30e681dd5a">INT</span></td><td>ID tổ chức</td></tr><tr><td>12</td><td>organization</td><td><span data-option="2a353d3434774486ae86a359db22b0cc">TEXT(255)</span></td><td>Tên tổ chức</td></tr><tr><td>13</td><td>city_id</td><td><span data-option="96eaa0bd08df4a6e82b19c30e681dd5a">INT</span></td><td>ID thành phố (Tham khảo danh sách tỉnh thành)</td></tr><tr><td>14</td><td>district_id</td><td><span data-option="96eaa0bd08df4a6e82b19c30e681dd5a">INT</span></td><td>ID huyện/quận </td></tr><tr><td>15</td><td>address</td><td><span data-option="2a353d3434774486ae86a359db22b0cc">TEXT(255)</span></td><td>Địa chỉ</td></tr><tr><td>16</td><td>gender</td><td><span data-option="96eaa0bd08df4a6e82b19c30e681dd5a">INT</span></td><td>Giới tính: 0. Nam, 1 Nữ, 2 Không xác định </td></tr><tr><td>17</td><td>facebook</td><td><span data-option="96eaa0bd08df4a6e82b19c30e681dd5a">INT</span></td><td>ID facebook (De-precade) </td></tr><tr><td>18</td><td>campaign_handler_id</td><td><span data-option="96eaa0bd08df4a6e82b19c30e681dd5a">INT</span></td><td>ID chiến dịch xử lý</td></tr><tr><td>19</td><td>custom_fields</td><td><span data-option="111c0ebfeb3b4edca5e073d8570cec43">ARRAY</span></td><td>Danh sách trường động </td></tr><tr><td>20</td><td>follower_id</td><td><span data-option="96eaa0bd08df4a6e82b19c30e681dd5a">INT</span></td><td>Id của chuyên viên quản lý (xem <a data-mention href="chuyen-vien">chuyen-vien</a> Trường ID </td></tr><tr><td>21</td><td>take_phone_at</td><td><span data-option="68546980a4954142891f7a23a85a929d">DATETIME</span></td><td>Thời điểm thu thập được số điện thoại (Null hoặc Ngày tháng)</td></tr><tr><td>22</td><td>take_email_at</td><td><span data-option="68546980a4954142891f7a23a85a929d">DATETIME</span></td><td>Thời điểm thu thập được email(Null hoặc Ngày tháng)</td></tr></tbody></table>

## 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

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FPiuz2I6Te9ptO8LcqaOR%2FcreateContact.png?alt=media&#x26;token=6e5ceaad-7f1a-41ba-97be-52d5916a13b5" alt=""><figcaption></figcaption></figure>

## Thêm mới khách hàng

<mark style="color:green;">`POST`</mark> `{{domain}/api/v1/contacts`

#### Headers

| Name | Type   | Description                                                                                |
| ---- | ------ | ------------------------------------------------------------------------------------------ |
| \*\* | String | [Thông tin xác thực chung ](https://docs.caresoft.vn/thong-tin-chung#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" %}

<table><thead><tr><th width="72">STT</th><th width="171">Tên trường</th><th width="97">Kiểu</th><th>Ý nghĩa</th></tr></thead><tbody><tr><td>1</td><td>code</td><td>String</td><td>"ok": Thành công, "errors": Thất bại</td></tr><tr><td>2</td><td>contact</td><td>Object</td><td>Đối tượng thông tin khách hàng được tạo mới </td></tr><tr><td>3</td><td><strong>contact.id</strong></td><td>Int</td><td><a data-footnote-ref href="#user-content-fn-1">ID khách hàng (?)</a></td></tr><tr><td>4</td><td>contact.phone_no</td><td>String</td><td>Số điện thoại</td></tr><tr><td>5</td><td>contact.email</td><td>Email</td><td>Email</td></tr><tr><td>6</td><td>contact.username</td><td>String</td><td>Họ tên khách hàng</td></tr><tr><td>7</td><td>contact.created_at</td><td></td><td>Ngày tạo</td></tr><tr><td>8</td><td>contact.updated_at</td><td></td><td>Ngày cập nhật</td></tr></tbody></table>
{% 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" %}

<pre class="language-json"><code class="lang-json">{
    "code": "errors",
    "message": "email already exist",
    "extra_data": {
        "duplicate_id": "<a data-footnote-ref href="#user-content-fn-2">63216006</a>"
    }
}
</code></pre>

{% 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&#x20;
{% endhint %}

## Cập nhật người dùng

<mark style="color:orange;">`PUT`</mark> `{{domain}/api/v1/contacts/{{contactId}}`

#### Headers

| Name                                   | Type   | Description                                                                                |
| -------------------------------------- | ------ | ------------------------------------------------------------------------------------------ |
| \*\*<mark style="color:red;">\*</mark> | String | [Thông tin xác thực chung ](https://docs.caresoft.vn/thong-tin-chung#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&#x20;

Mẫu tham khảo cấu hình POSTMAN lấy danh sách khách hàng

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2FIcsVRKLvyNoiMS82oeie%2FkhachhangDanhsach.png?alt=media&#x26;token=aff6a1b9-ec34-4f4d-8f9e-bfcce8a92af8" alt=""><figcaption></figcaption></figure>

## Danh sách khách hàng

<mark style="color:blue;">`GET`</mark> `{{domain}/api/v1/contacts`

#### Query Parameters

| Name           | Type               | Description                                                                      |
| -------------- | ------------------ | -------------------------------------------------------------------------------- |
| updated\_since | DateTime (ISO8601) | Có thời điểm cập nhật từ ngày (Kiểu dữ liệu YYYY-MM-DDTHH:mm:ssZ)                |
| updated\_to    | DateTime (ISO8601) | Có thời điểm cập nhật đến ngày (Kiểu dữ liệu YYYY-MM-DDTHH:mm:ssZ)               |
| created\_since | DateTime (ISO8601) | Có thời điểm tạo từ ngày (Kiểu dữ liệu YYYY-MM-DDTHH:mm:ssZ)                     |
| created\_to    | DateTime (ISO8601) | Có thời điểm tạo từ ngày (Kiểu dữ liệu 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             | <p>Kiểu sắp xếp <br>DESC hoặc ASC (Giảm dần hoặc tăng dần) <br>Mặc định DESC</p> |

#### Headers

| Name                                   | Type   | Description                                                                                |
| -------------------------------------- | ------ | ------------------------------------------------------------------------------------------ |
| \*\*<mark style="color:red;">\*</mark> | String | [Thông tin xác thực chung ](https://docs.caresoft.vn/thong-tin-chung#phuong-thuc-xac-thuc) |

{% tabs %}
{% tab title="200: OK Kết quả thành công" %}
{% tabs %}
{% tab title="Kết quả điển hình" %}

```json
{
    "code": "ok",
    "numFound": 3,
    "contacts": [
        {
            "id": 165027003,
            "created_at": "2023-04-14T09:43:24Z",
            "updated_at": "2023-04-14T09:43:24Z",
            "phone_no": "0334992975",
            "username": "0334992975"
        }, 
    ...
  ]
}

```

{% endtab %}

{% tab title="Second Tab" %}

<table><thead><tr><th width="120">Stt</th><th width="159">Tên trường</th><th>Chú thích</th></tr></thead><tbody><tr><td>1</td><td>code</td><td>Trạng thái thành công:<br>ok: Thành công<br>errors: Thất bại</td></tr><tr><td>2</td><td>numFound</td><td>Số bản ghi tìm thấy theo điều kiện lọc</td></tr><tr><td>3</td><td>contacts []</td><td><p>Mảng dữ liệu danh sách khách hàng. Gồm các object có cấu trúc như sau</p><ul><li><code>id</code>:  Id của khách hàng - Dùng ID này để truy xuất thông tin chi tiết, tham số    <code>{{contactId}}</code></li><li><code>username</code>: Họ tên khách hàng</li><li><code>created_at</code>: Ngày tạo</li><li><code>updated_at</code>: Ngày cập nhật</li><li><code>phone_no</code>: Số điện thoại thứ nhất của khách hàng</li></ul></td></tr></tbody></table>
{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

## Chi tiết khách hàng

Dựa vào các hàm tạo mới hay cập nhật khách hàng hoặc danh sách khách hàng,  trả về các **{{contactId}}**. Nhà phát triển sử dụng hàm này để lấy thông tin chi tiết 1 khách hàng. API này bắt buộc phải có contactID mới thực hiện được

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2F9HisoB5s7CgEv2cgB93h%2FChitietLienhe.png?alt=media&#x26;token=773080e3-cbd4-427e-a365-8e8cf10f6b6c" alt=""><figcaption></figcaption></figure>

## Chi tiết khách hàng

<mark style="color:blue;">`GET`</mark> `{{domain}/api/v1/contacts/{{contactId}}`

#### Headers

| Name                                   | Type   | Description                                                                                |
| -------------------------------------- | ------ | ------------------------------------------------------------------------------------------ |
| \*\*<mark style="color:red;">\*</mark> | String | [Thông tin xác thực chung ](https://docs.caresoft.vn/thong-tin-chung#phuong-thuc-xac-thuc) |

{% tabs %}
{% tab title="200: OK Thành công" %}
{% tabs %}
{% tab title="Kết quả điển hình" %}

```
{
    "code": "ok",
    "contact": {
        "id": 124921946,
        "username": "Nguyễn Văn Nam",
        "email": "demoapi@gmail.com",
        "email2": null,
        "phone_no": "0646546546546",
        "phone_no2": "09887456123",
        "phone_no3": null,
        "facebook": null,
        "gender": 1,
        "organization_id": 246080,
        "address": null,
        "city_id": null,
        "district_id": null,
        "created_at": "2021-10-30 00:16:04",
        "updated_at": "2023-04-24 17:56:13",
        "role_id": 3,
        "campaign_handler_id": null,
        "take_phone_at": "2022-04-12 14:30:00",
        "take_email_at": "2023-04-24 17:55:56",
        "custom_fields": [
                      {
                "id": 7492,
                "lable": "GIỚI TÍNH",
                "type": "Single drop-down list",
                "value": "33213"
            },
            {
                "id": 7584,
                "lable": "Tên trên QLBH",
                "type": "Text",
                "value": "AB"
            }
            ....           
          
        ],
        "organization": {
            "organization_id": 246080,
            "organization_domain": "323232",
            "organization_name": "sấ"
        }
    }
}
ta
```

{% endtab %}

{% tab title="Cấu trúc dữ liệu" %}

<table><thead><tr><th width="94">STT</th><th width="172">Tên trường</th><th>Ý nghĩa</th></tr></thead><tbody><tr><td>1</td><td>code</td><td>Trạng thái <br>ok: Thành công<br>error: Lỗi</td></tr><tr><td>2</td><td>contact</td><td>Đối tượng thông tin khách hàng khách hàng  <br>(xem chi tiết ở bảng dưới) </td></tr></tbody></table>

Chi tiết đối tượng thông tin khách hàng (object)&#x20;

<table><thead><tr><th width="86">STT</th><th width="157">Tên trường</th><th>Ý nghĩa</th></tr></thead><tbody><tr><td>1</td><td>id</td><td>ID khách hàng</td></tr><tr><td>2</td><td>username</td><td>Họ tên khách hàng</td></tr><tr><td>3</td><td>email</td><td>Email </td></tr><tr><td>4</td><td>email2</td><td>Email 2</td></tr><tr><td>5</td><td>phone_no</td><td>Số điện thoại</td></tr><tr><td>6</td><td>phone_no2</td><td>Số điện thoại thứ 2</td></tr><tr><td>7</td><td>phone_no3</td><td>Số điện thoại 3</td></tr><tr><td>8</td><td>gender</td><td>Giới tính (0: Nam, 1 Nữ, 2: Không xác định)</td></tr><tr><td>9</td><td>organization_id</td><td>ID tổ chức </td></tr><tr><td>10</td><td>address</td><td>Địa chỉ</td></tr><tr><td>11</td><td>city_id</td><td>ID tỉnh/thành phố</td></tr><tr><td>12</td><td>district_id</td><td>ID huyện/Quận</td></tr><tr><td>13</td><td>created_at</td><td>Ngày tạo</td></tr><tr><td>14</td><td>updated_at</td><td>Ngày cập nhật</td></tr><tr><td>15</td><td>take_phone_at</td><td>Thời điểm thu thập số điện thoại</td></tr><tr><td>16</td><td>take_email_at</td><td>Thời điểm thu thập được email</td></tr><tr><td>17</td><td>custom_fields</td><td>Thông tin trường động (xem thêm ở <a data-mention href="../../thong-tin-chung/truong-dong-custom-fields">truong-dong-custom-fields</a>)</td></tr><tr><td>18</td><td>organization</td><td>Tổ chức </td></tr><tr><td>19</td><td>zalo_id</td><td>Zalo ID</td></tr><tr><td>20</td><td>zalo_followers</td><td>Mảng dữ liệu object các Zalo Oa mà khách đang theo dõi nếu Zalo_id có giá trị.<br>Trong đó: <br>- oa_name: Tên Zalo OA <br>- oa_id:  ID OA,<br>- 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)<br>- follow_status: Trạng thái follow của khách ( 1: Đang follow, null / 0: Không follow hoặc đã hủy) <br>-  updated_at: Ngày cập nhật mới nhất  </td></tr><tr><td>21</td><td>facebook</td><td>ID facebook </td></tr><tr><td>22</td><td>psid</td><td>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 đó<br>- page_id: ID của page<br>- psid: ID của khách trên page </td></tr></tbody></table>
{% 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.

<figure><img src="https://2193274687-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fw9FEMPuWidjTVayVtnJj%2Fuploads%2Fbwf1BpPxTsfey2aKilAy%2Fpho.png?alt=media&#x26;token=d49ba920-e227-4ec1-9a1e-698f8b701821" alt=""><figcaption><p>(Mẫu Postman tham khảo)</p></figcaption></figure>

## Tìm khách hàng theo số điện thoại

<mark style="color:blue;">`GET`</mark> `{{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<mark style="color:red;">\*</mark> | 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" %}

<pre class="language-json"><code class="lang-json">{
    "code": "ok",
    "contact": {
        "username": "A **",
        "id": <a data-footnote-ref href="#user-content-fn-3">63150747</a>,
        "email": "abc123@gmail.com",
        "phone_no": "09839**",
        "phone_no2": "0555****",
        "phone_no3": null,
        "email2": "****",
        "facebook": "546869858829726_2012787322172363",
        "gender": null,
        "organization_id": null,
        "created_at": "2020-01-17 10:12:18",
        "updated_at": "2023-06-24 16:54:10"
    }
}
</code></pre>

{% 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]: