帮我吧文档:数据接口:客户管理:联系人

联系人接口

为了支持比较复杂的自定义字段类型，我们对接口进行了升级，凡是接口名称中包含“_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示例

{
  "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
}

获取联系人列表

GET /api/v1/users_v2.json

旧接口 “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”。

调用者权限

所有客服

也可以使用下面的接口

/*查看服务商下某个客户的联系人*/
GET /api/v1/companies/{company_id}/users_v2.json
GET /api/v1/companies/{company_id}/users.json

调用示例

curl https://www.bangwo8.com/api/v1/users_v2.json \
  -v -u {account}:{password}

返回值示例

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
}

查看指定联系人信息

GET /api/v1/users/{cid}_v2.json

旧接口 “GET /api/v1/{cid}.json”

调用者权限

所有客服

调用示例

curl https://www.bangwo8.com/api/v1/users/{cid}_v2.json \
  -v -u {account}:{password}

返回值示例

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"
    }
}

获取多个联系人信息

GET GET /api/v1/users/show_many.json?ids={ids}

调用者权限

所有客服

调用示例

curl https://www.bangwo8.com/api/v1/users/show_many.json?ids=1,2,3 \
  -v -u {account}:{password}

返回值示例

Status: 200 OK

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

创建联系人

POST /api/v1/users_v2.json

旧接口“POST /api/v1/users.json”

调用者权限

所有客服

调用示例

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"}}'

说明：可通过mobile和fixnumber属性来创建联系人。也就是说，创建联系人时，mobile、fixnumber两者其一必须有值。

若请求数据中包含“下拉列表”，则需传递选中项的ID，调用示例如下：

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"}]}}'

若请求数据中包含“复选框”，则选中时传“1”，未选中传“0”，调用示例如下：

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"}]}}'

若请求数据中包含“高级复选”，则需传递所有勾选项的ID，以逗号分隔，调用示例如下：

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"}]}}'

若请求数据中包含“级联”字段，调用示例如下：

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":["北京市","海淀","清华大学"]}]}}'

返回值示例

Status: 200 OK
Location: https://www.bangwo8.com/api/v1/users/{id}.json

{
  "user": {
    "cId":   11,
    "name": "张三",
    ...
  }
}

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

修改联系人信息

PUT /api/v1/users/{cid}.json

调用者权限

所有客服

更新系统字段调用示例

curl -v -u {account}:{password} https://www.bangwo8.com/api/v1/users/123.json \
  -H "Content-Type: application/json" -X PUT -d '{"user": {"name": "张三"}}'

返回值示例

Status: 200 OK

{
  "user": {
    "cId":   11,
    "name": "张三",
    ...
  }
}

更新自定义字段调用示例

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"}]}}'

返回值示例

Status: 200 OK

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

搜索联系人

GET /api/v1/users/search.json

获取全部数据（包含已删除数据），需在链接后拼接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为例）

  * 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当天

调用示例

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

返回值示例

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
}

删除多个联系人

DELETE /api/v1/users/destroy_many.json

调用者权限

所有客服

调用示例

curl https://www.bangwo8.com/api/v1/users/destroy_many.json?ids=123,234 \
  -v -u {account}:{password} \
  -X DELETE

返回值示例

Status: 200 OK

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

目录

联系人接口

JSON格式

JSON示例

获取联系人列表

查看指定联系人信息

获取多个联系人信息

创建联系人

修改联系人信息

搜索联系人

删除多个联系人