=====联系人接口=====
\\
为了支持比较复杂的自定义字段类型，我们对接口进行了升级，凡是接口名称中包含“_v2”的均为新接口，不包含的仍为旧接口，新接口的增加不对旧接口的逻辑产生任何影响，可放心使用旧接口。 \\
\\
新接口与旧接口的区别：
  - 新接口新增了对“高级复选框”、“级联”类型的自定义字段的支持。
  - 新接口的请求数据或返回值中如果包含下拉列表类型的字段，则传值为选项ID，旧接口则是选项内容。

====JSON格式====
^名称	^类型	^只读	^必填	^注释^
|cId		|int		|是	|否	|联系人ID，系统自动生成 |	
|url |varchar |是 |否 |该联系人的url | 
|name	|varchar	|否	|否	|姓名		|
|mobile	|varchar	|否	|是	|手机号码，创建联系人时手机号码、座机号码任填写一个即可 	|	
|fixnumber|varchar	|否	|是	|座机号码，创建联系人时手机号码、座机号码任填写一个即可	|
|email  |varchar        |否      |否      |邮件           |	
|position	|varchar	|否	|否	|职位		|
|state   	|int	|否	|否	|联系人状态（1-在职、2-离职、3-已删除）		|	
|QQ		 |varchar	|否	|否	|QQ号码	|	
|note	 |varchar	|否	|否	|联系人备注		|
|companyId|int		|是	|否	|联系人所属公司ID，如果是2B模式必填，2C模式不用填	|
|uniqueId|varchar	|是	|否	|联系人下的远程ID，远程客户端安装完毕后自动生成的。旧接口的返回值	|
|uniqueIds|array	|否	|否	|联系人下的远程ID及ID的备注。新接口的返回值	|
|supportId|int		|是	|否	|负责该联系人的客服ID，系统自动生成	|
|createrId|int		|否	|否	|创建人id	|
|default|tinyint		|否	|否	|是否是该公司的默认联系人，取值为：1-默认联系人，0-普通联系人|
|createDT |date	|是	|否	|创建时间，格式为：2018-02-03 00:00:00		|
|updateDT|date	|是	|否	|更新时间，格式为：2018-02-03 00:00:00		|
|custom_fields|array	|否	|否	|联系人自定义字段		|
|userGroup|int	|否	|否	|联系人所属分组，2C模式下存在该字段，默认取值为0，即不属于任何分组，多个分组用,分隔|
|tableName | varchar |否     |否     |标签，多个英⽂逗号隔开    |


====JSON示例====
<code>
{
  "cId": 1,
  "url": "https://www.bangwo8.com/api/v1/users_v2/1.json",
  "name": "张三",
  "mobile": "13240138429",
  "email": "234576@163.com",
  "fixnumber": "010-63701717",
  "position": "项目经理",
  "QQ": "601100987",
  "note": "这里是联系人的备注",
  "companyId": 123,
  "uniqueId": "291045895",
  "supportId": 3,
  "createDT": "2017-09-12 10:12:22",
  "updateDT": "2017-09-12 10:12:22",
  "custom_fields": [
      {
	"key": "field_1",
	"value": "4334"
      },
      {
	"key": "field_3",//复选框
	"value": "是" 
      },
      {
	"key": "field_2",//下拉列表
	"value": "下拉菜单的某一项"//选项ID
      }
      {
	"key": "field_5",//高级复选框
	"value": "232,565,454"//勾选项的ID列表，以逗号分隔
      }
      {
	"key": "field_7",//级联
	"value": [
	  {
            "level_id":"s1",//级联的第一级别的id
            "item_key":"11"//选中项的ID
          },
          {
            "level_id":"s2",//级联的第二级别的id
            "item_key":"21"
          },
          {
	    "level_id":"s3",//级联的第三级别的id
	    "item_key":"31"
          }
	]
     }
   ],
   "userGroup": 221
}   
</code>

====获取联系人列表====
<code>
GET /api/v1/users_v2.json
</code>
旧接口  “GET /api/v1/users.json”
 \\ 获取全部数据（包含已删除数据），需在链接后拼接deStat=1，/api/v1/users_v2.json?deStat=1


**查询参数**
^名称		^必需的		^类型		^注释	^
|created_start	|否		|string		|按创建时间筛选，开始时间，包含当天|
|created_end	|否		|string		|按创建时间筛选，结束时间，包含当天|
|updated_start	|否		|string		|按更新时间筛选，开始时间，包含当天|
|updated_end	|否		|string		|按更新时间筛选，结束时间，包含当天|
|created_order	|否		|string		|按创建时间排序，取值为：asc-升序，desc-降序|
|updated_order	|否		|string		|按更新时间排序，取值为：asc-升序，desc-降序|
|page		|否		|int		|分页获取，默认为1|
|per_page	|否		|int		|每页大小，默认为100|
//说明：默认按编码升序返回。时间参数（created_start、created_end、updated_start、updated_end）格式为“2012-01-01 00:00:00”。//

**调用者权限**
  所有客服
 
也可以使用下面的接口
<code>
/*查看服务商下某个客户的联系人*/
GET /api/v1/companies/{company_id}/users_v2.json
GET /api/v1/companies/{company_id}/users.json
</code>

**调用示例**
<code>
curl https://www.bangwo8.com/api/v1/users_v2.json \
  -v -u {account}:{password}
</code>

**返回值示例**
<code>
Status: 200 OK

{
	"users": [
		{
			"cId": 1,
			"name": "张三",
			...
		},
		{
			"cId": 2,
			"name": "李四",
			...
		}
	],
        "count": 42,
        "next_page": "https://www.bangwo8.com/api/v1/users_v2.json?per_page=40&page=2",
        "previous_page": null
}
</code>

====查看指定联系人信息====
<code>
GET /api/v1/users/{cid}_v2.json
</code>
旧接口 “GET /api/v1/{cid}.json”

**调用者权限**
  所有客服
  
**调用示例**
<code>
curl https://www.bangwo8.com/api/v1/users/{cid}_v2.json \
  -v -u {account}:{password}
</code>
  
**返回值示例**
<code>
Status: 200 OK

{
    "user": {
        "cId": "41451311",
        "name": "测试1",
        "mobile": "18811119637",
        "email": "",
        "fixnumber": "",
        "position": "",
        "QQ": "",
        "note": "",
        "companyId": "0",
        "supportId": "0",
        "multiServiceList": "",
        "default": "",
        "service_groupid": "0",
        "createDT": "2022-01-10 11:10:43",
        "updateDT": "2022-02-10 15:16:16",
        "tableName": "",
        "uniqueId": "",
        "custom_fields": [
            {
                "key": "field_1",
                "value": ""
            },
            {
                "key": "authaccount",
                "value": "212108284829637117"
            },
            {
                "key": "field_3",
                "value": [
                    "北京市",
                    "海淀",
                    "清华大学"
                ]
            }
        ],
        "userGroup": "0"
    }
}
</code>


====获取多个联系人信息====
<code>
GET GET /api/v1/users/show_many.json?ids={ids}
</code>

**调用者权限**
  所有客服
  
**调用示例**
<code>
curl https://www.bangwo8.com/api/v1/users/show_many.json?ids=1,2,3 \
  -v -u {account}:{password}
</code>

**返回值示例**
<code>
Status: 200 OK

{
  "users": [
    {
      "cId": 1,
      "name": "张三",
      ...
    },
    {
      "cId": 2,
      "name": "李四",
      ...
    }
  ]
}
</code>


====创建联系人====

<code>
POST /api/v1/users_v2.json
</code>
旧接口“POST /api/v1/users.json” \\
\\
**调用者权限**
  所有客服
  
**调用示例**
<code>
curl -v -u {account}:{password} https://www.bangwo8.com/api/v1/users.json \
  -H "Content-Type: application/json" -X POST -d '{"user":{"name":"张三","mobile":"13240134214"}}'
</code>
//说明：可通过mobile和fixnumber属性来创建联系人。也就是说，创建联系人时，mobile、fixnumber两者其一必须有值。// \\
\\
若请求数据中包含“下拉列表”，则需传递选中项的ID，调用示例如下：
<code>
curl -v -u {account}:{password} https://www.bangwo8.com/api/v1/users.json \
  -H "Content-Type: application/json" -X POST -d '{"user":{"name":"张三","mobile":"13240134214", \
"custom_fields":[{"key":"droplist_job","value":"232"}]}}'
</code>
若请求数据中包含“复选框”，则选中时传“1”，未选中传“0”，调用示例如下：
<code>
curl -v -u {account}:{password} https://www.bangwo8.com/api/v1/users.json \
  -H "Content-Type: application/json" -X POST -d '{"user":{"name":"张三","mobile":"13240134214", \
"custom_fields":[{"key":"checkbox_married","value":"1"}]}}'
</code>
若请求数据中包含“高级复选”，则需传递所有勾选项的ID，以逗号分隔，调用示例如下：
<code>
curl -v -u {account}:{password} https://www.bangwo8.com/api/v1/users.json \
  -H "Content-Type: application/json" -X POST -d '{"user":{"name":"张三","mobile":"13240134214", \
"custom_fields":[{"key":"advance_checkbox_hobby","value":"21,23"}]}}'
</code>
若请求数据中包含“级联”字段，调用示例如下：
<code>
curl -v -u {account}:{password} https://www.bangwo8.com/api/v1/users.json \
  -H "Content-Type: application/json" -X POST -d '{"user":{"name":"张三","mobile":"13240134214", \
"custom_fields":[{"key":"field_3","value":["北京市","海淀","清华大学"]}]}}'
</code>

**返回值示例**
<code>
Status: 200 OK
Location: https://www.bangwo8.com/api/v1/users/{id}.json

{
  "user": {
    "cId":   11,
    "name": "张三",
    ...
  }
}
</code>  

[注] 联系人是与手机号码一一对应，因此：\\
1、2B模式下，不同公司下可以有相同联系人（手机号码），同一公司下不能有相同联系人（手机号码）（即：同一个人可能出现在多个公司里，但同一个人不能在同一公司出现两次）；\\
2、2C模式下，没有公司概念，所有联系人在一起，不能有相同联系人（手机号码）\\
否则通过API创建联系人时会报错：[{"errorMsg":"The \"mobile\" has been used","status":"110017"}] 
====修改联系人信息====
<code>
PUT /api/v1/users/{cid}.json
</code>

**调用者权限**
  所有客服
  
**更新系统字段调用示例**
<code>
curl -v -u {account}:{password} https://www.bangwo8.com/api/v1/users/123.json \
  -H "Content-Type: application/json" -X PUT -d '{"user": {"name": "张三"}}'
</code>

**返回值示例**
<code>
Status: 200 OK

{
  "user": {
    "cId":   11,
    "name": "张三",
    ...
  }
}
</code>

**更新自定义字段调用示例**
<code>
curl -v -u {account}:{password} https://www.bangwo8.com/api/v1/users/123.json \
  -H "Content-Type: application/json" -X PUT -d '{"user":{"custom_fields":[{"key":"field_1","value":"123"}]}}'
</code>

**返回值示例**
<code>
Status: 200 OK

{
  "user": {
    "cId":   11,
    "name": "张三",
     "custom_fields": [
            {
                "key": "field_1",
                "value": "123"
            }
        ]
  }
}
</code>

====搜索联系人====
<code>
GET /api/v1/users/search.json
</code>
获取全部数据（包含已删除数据），需在链接后拼接deStat=1，/api/v1/users/search.json?deStat=1

**调用者权限**
  所有客服
  
**请求参数**
^名称 ^类型 ^必需的 ^注释 ^
|query |string |是 |搜索内容|
|sort_by |string | 否 |按时间排序，目前支持：createDT-创建时间，updateDT-更新时间|
|sort_order| string | 否 | 按升序还是降序返回，取值为：asc-升序，desc-降序，默认为降序|

**query参数说明**
^搜索内容 ^返回结果 ^
|query=2444 | 模糊搜索，返回姓名或者手机号包含该内容的联系人|
|query=mobile:13240138429 | 搜索手机号为“13240138429”的联系人，此为精确搜索 |
|query=userId:9516936 mobile:13240134213 | 搜索公司id为“9516936”且手机号码为“13240134213 ”的联系人，此为精确搜索 |
|query=authaccount:454 | 返回自定义字段唯一标识为“authaccount”为454的联系人，此条件为精准查询|
|query=2444 createDT>2017-07-01|返回姓名或者手机号包含"2444"，并且创建时间是2017年7月1日以后的联系人|
|query=2444 createDT>=2017-07-01 createDT<2017-08-01|返回姓名或者手机号包含"2444"，并且时间是7月份的联系人|

//说明： //\\
//1、目前不支持搜索内容本身带有空格// \\
//2、当query参数增加了时间的过滤条件时，两个条件之间要以空格分开，比如“2444 createDT>2017-07-01”// \\
//3、时间过滤条件目前支持以下几种方式：（以createDT为例）//\\

<code>
  * createDT<2017-09-01 //过滤创建时间为2017-09-01之前的联系人，不包含2017-09-01当天
  * createDT>2017-09-01 //过滤创建时间为2017-09-01之后的联系人，不包含2017-09-01当天 
  * createDT:2017-09-01 //过滤创建时间为2017-09-01当天的联系人 
  * createDT<=2017-09-01 //过滤创建时间为2017-09-01之前的联系人，包含2017-09-01当天 
  * createDT>=2017-09-01 //过滤创建时间为2017-09-01之后的联系人，包含2017-09-01当天
</code>


**调用示例**
<code>
curl "https://www.bangwo8.com/api/v1/users/search.json" \
  -G --data-urlencode "query=132 createDT>2017-07-03" \
  -v -u {account}:{password}
</code>

**返回值示例**
<code>
Status: 200 OK

{
  "results": [
    {
      "name":   "张三",
      "createDT":  "2009-05-13 10:07:08",
      "updateDT":  "2011-07-22 11:11:12",
      "cId":  111,
      "url":       "https://www.bangwo8.com/api/v1/users/111.json"
    },
    {
      "subject":   "李四",
      "createDT":  "2010-07-13 10:07:08",
      "updateDT":  "2011-07-13 11:11:12",
      "cId":  112,
      "url":       "https://www.bangwo8.com/api/v1/users/112.json"
    },
    ...
  ],
  "next_page": "https://www.bangwo8.com/api/v1/users/search.json?query=132 createDT>2017-07-03&sort_by=createDT&sort_order=desc&page=2",
  "prev_page": null,
  "count":     100
}
</code>




====删除多个联系人====
<code>
DELETE /api/v1/users/destroy_many.json
</code>

**调用者权限**
  所有客服
  

**调用示例**
<code>
curl https://www.bangwo8.com/api/v1/users/destroy_many.json?ids=123,234 \
  -v -u {account}:{password} \
  -X DELETE
</code>

**返回值示例**
<code>
Status: 200 OK

{
  "users": [
    {
      "cId": 123,
      "name": "张三",
      ...
    },
    {
      "cId": 234,
      "name": "李四",
      ...
    }
  ]
}
</code>