# 客戶

## 列表

透過 GET 請求取得ㄎ清單，並可依據下列查詢參數進行過濾、排序與分頁。

```javascript
GET https://{API_HOST}/api/v1/contact
```

根據下方的 **Query Parameters** 參數進行過濾篩選。

```javascript
curl -X GET
    -H "Content-Type: application/json"
    https://{API_HOST}/api/v1/contact
```

### Query Parameters

<table><thead><tr><th>名稱</th><th>類型</th><th width="95.75390625">必填</th><th>說明</th><th>範例</th></tr></thead><tbody><tr><td>page</td><td>integer</td><td>否</td><td>當前頁碼（從 1 開始）</td><td>page=2</td></tr><tr><td>search</td><td>string</td><td>否</td><td>名字關鍵字搜尋</td><td>search=John</td></tr><tr><td>created_at__start</td><td>string (datetime)</td><td>否</td><td>建立時間（起）</td><td>created_at__start=2023-01-01</td></tr><tr><td>created_at__end</td><td>string (datetime)</td><td>否</td><td>建立時間（迄）</td><td>created_at__end=2023-12-31</td></tr><tr><td>birth_months</td><td>array&#x3C;integer></td><td>否</td><td>出生月份（1–12）</td><td>birth_months=1,2</td></tr><tr><td>membership_no</td><td>string</td><td>否</td><td>會員編號</td><td>membership_no=123456</td></tr><tr><td>sponsor_id</td><td>string</td><td>否</td><td>業主 ID</td><td>sponsor_id=999</td></tr><tr><td>company_ids</td><td>array&#x3C;integer></td><td>否</td><td>公司 ID</td><td>company_ids=1,2,3</td></tr><tr><td>tag_ids</td><td>array&#x3C;integer></td><td>否</td><td>標籤 ID 清單</td><td>tag_ids=101,102</td></tr><tr><td>identity_no</td><td>string</td><td>否</td><td>身份證號碼</td><td>identity_no=A123456789</td></tr><tr><td>phone_number</td><td>string</td><td>否</td><td>電話號碼</td><td>phone_number=0912345678</td></tr><tr><td>age__start</td><td>integer</td><td>否</td><td>年齡（起）</td><td>age__start=20</td></tr><tr><td>age__end</td><td>integer</td><td>否</td><td>年齡（迄）</td><td>age__end=40</td></tr><tr><td>has_duplicate_number</td><td>boolean (0/1)</td><td>否</td><td>是否有重複號碼</td><td>has_duplicate_number=1</td></tr><tr><td>has_number</td><td>boolean (0/1)</td><td>否</td><td>是否有電話號碼</td><td>has_number=1</td></tr><tr><td>has_fb_optin</td><td>boolean (0/1)</td><td>否</td><td>是否有 FB 授權</td><td>has_fb_optin=1</td></tr><tr><td>has_valid_fb_optin</td><td>boolean (0/1)</td><td>否</td><td>是否有有效 FB 授權</td><td>has_valid_fb_optin=1</td></tr><tr><td>has_disturb</td><td>boolean (0/1)</td><td>否</td><td>是否有勿擾資料</td><td>has_disturb=1</td></tr></tbody></table>

### Response

| PROPERTY | TYPE             | DESCRIPTION |
| -------- | ---------------- | ----------- |
| data     | Array of objects | 客戶資料陣列      |
| meta     | Object           | 頁籤資訊        |

## 取得

```javascript
GET https://{API_DOMAIN}/api/v1/contact/{contact}
```

### URL Parameters

| PARAMETER   | REQUIRED | DEFAULT | TYPE   | DESCRIPTION |
| ----------- | -------- | ------- | ------ | ----------- |
| **contact** | True     | NULL    | Number | 客戶的 ID      |

```javascript
curl -X get
    -H "Content-Type: application/json"
    https://{API_HOST}/api/v1/contact/1
```

### Response

請參考[客戶](https://help.firstline.cc/developer/api/hui-ying-wu-jian-ge-shi#ke-hu-contact)回應格式。

| PROPERTY | TYPE   | DESCRIPTION                                                                         |
| -------- | ------ | ----------------------------------------------------------------------------------- |
| **data** | Object | [客戶](https://help.firstline.cc/developer/api/hui-ying-wu-jian-ge-shi#ke-hu-contact) |

```javascript

{
    "data": {
        "id": 1,
        "name": "Angelita D'Amore",
        "first_name": "Angelita",
        "last_name": "D'Amore",
        "membership_no": "8771639",
        "identity_no": "418099",
        "gender": 0,
        "birth_at": "1985-08-27",
        "profile_id": 1,
        "profile": {
            "id": 1,
            "phones": []
        },
        "email_contacts": [],
        "cz_cols": [
            {
                "id": 1,
                "value": "19999",
                "category_id": 1
            },
            {
                "id": 4,
                "value": "51",
                "category_id": 1
            },
            {
                "id": 5,
                "value": null,
                "category_id": 1
            }
        ]
    }
}
```

## 新增

```javascript
POST https://{API_HOST}/api/v1/contact
```

根據下方的 **Query Parameters** 表單的參數進行建立。

```javascript
curl -X POST
    -H "Content-Type: application/json"
    '{"first_name":"abc","last_name":"cde"}'
    https://{API_HOST}/api/v1/contact?xxxx
```

### Query Parameters

| PARAMETER          | REQUIRED | DEFAULT | TYPE   | DESCRIPTION                  |
| ------------------ | -------- | ------- | ------ | ---------------------------- |
| **membership\_no** | false    | NULL    | String | 會員編號                         |
| **identity\_no**   | false    | NULL    | String | 身分證                          |
| **gender**         | false    | NULL    | Number | <p>性別<br>0: 女<br>1: 男</p>    |
| **first\_name**    | true     | NULL    | String | 姓                            |
| **last\_name**     | false    | NULL    | String | 名                            |
| **birth\_at**      | false    | NULL    | Date   | 出生日期                         |
| **cz\_cols**       | false    | NULL    | Array  | 自訂欄位，參數型態參考下方 **CzCol** 表格說明 |
| **company\_ids**   | false    | NULL    | Array  | 公司系統編號                       |

### Response

請參考[客戶](https://help.firstline.cc/developer/api/hui-ying-wu-jian-ge-shi#ke-hu-contact)回應格式

```javascript

{
    "data": {
        "id": 2,
        "name": "abc cde",
        "first_name": "abc",
        "last_name": "cde",
        "membership_no": null,
        "identity_no": null,
        "gender": null,
        "birth_at": null,
        "profile_id": 1,
        "profile": {
            "id": 1,
            "phones": []
        },
        "cz_cols": [
            {
                id: 4,
                value: "123456"
            },
            {
                id: 7,
                value: "apple"
            }
        ],
    }
}
```

## 更新

```javascript
PUT https://{API_HOST}/api/v1/contact/{id}
```

### URL Parameters

| PARAMETER | DESCRIPTION |
| --------- | ----------- |
| **id**    | 客戶的 ID      |

```javascript
curl -X PUT
    -H "Content-Type: application/json"
    '{"first_name":"First","last_name":"Line"}'
    https://{API_HOST}/api/v1/contact/2
```

### Query Parameters

| PARAMETER          | REQUIRED | DEFAULT | TYPE   | DESCRIPTION                  |
| ------------------ | -------- | ------- | ------ | ---------------------------- |
| **membership\_no** | false    | NULL    | String | 會員編號                         |
| **identity\_no**   | false    | NULL    | String | 身分證                          |
| **gender**         | false    | NULL    | Number | <p>性別<br>0: 女<br>1: 男</p>    |
| **first\_name**    | false    | NULL    | String | 姓                            |
| **last\_name**     | false    | NULL    | String | 名                            |
| **birth\_at**      | false    | NULL    | Date   | 出生日期                         |
| **cz\_cols**       | false    | NULL    | Array  | 自訂欄位，參數型態參考下方 **CzCol** 表格說明 |
| **tag\_ids**       | false    | NULL    | Array  | 客戶標籤，傳入客戶標籤 ID               |
| **company\_ids**   | false    | NULL    | Array  | 公司系統編號                       |

### Response

請參考[客戶](https://help.firstline.cc/developer/api/hui-ying-wu-jian-ge-shi#ke-hu-contact)回應格式

```json

{
    "data": {
        "id": 2,
        "name": "First Line",
        "first_name": "First",
        "last_name": "Line",
        "membership_no": null,
        "identity_no": null,
        "gender": null,
        "birth_at": null,
        "profile_id": 1,
        "profile": {
            "id": 1,
            "phones": []
        },
        "cz_cols": [
            {
                id: 4,
                value: "123456"
            },
            {
                id: 7,
                value: "apple"
            },
            {
                id: 18,
                value:  ["A", "B", "C"]
            }
        ],
        "tag_id": [4, 6]
    }
}
```

## 刪除

```
DELETE https://{API_HOST}/api/v1/contact/{id}
```

### URL Parameters

| PARAMETER | DESCRIPTION                                                                                   |
| --------- | --------------------------------------------------------------------------------------------- |
| **id**    | [客戶](https://help.firstline.cc/developer/api/hui-ying-wu-jian-ge-shi#ke-hu-contact)的系統編號
 #ID |

```javascript
curl -X DELETE
    -H "Content-Type: application/json"
    https://{API_HOST}/api/v1/contact/2
```