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

联系人接口


为了支持比较复杂的自定义字段类型,我们对接口进行了升级,凡是接口名称中包含“_v2”的均为新接口,不包含的仍为旧接口,新接口的增加不对旧接口的逻辑产生任何影响,可放心使用旧接口。

新接口与旧接口的区别:

  1. 新接口新增了对“高级复选框”、“级联”类型的自定义字段的支持。
  2. 新接口的请求数据或返回值中如果包含下拉列表类型的字段,则传值为选项ID,旧接口则是选项内容。

JSON格式

名称 类型 只读 必填 注释
cId int 联系人ID,系统自动生成
url varchar 该联系人的url
name varchar 姓名
mobile varchar 手机号码
fixnumbervarchar 座机号码
email varchar 邮件
position varchar 职位
QQ varchar QQ号码
note varchar 联系人备注
companyIdint 联系人所属公司ID,系统自动生成
uniqueIdvarchar 联系人下的远程ID,远程客户端安装完毕后自动生成的。旧接口的返回值
uniqueIdsarray 联系人下的远程ID及ID的备注。新接口的返回值
supportIdint 负责该联系人的客服ID,系统自动生成
defaulttinyint 是否是该公司的默认联系人,取值为:1-默认联系人,0-普通联系人
createDT date 创建时间,格式为:2018-02-03 00:00:00
updateDTdate 更新时间,格式为:2018-02-03 00:00:00
custom_fieldsarray 联系人自定义字段
userGroupint 联系人所属分组,2C模式下存在该字段,默认取值为0,即不属于任何分组

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”

查询参数

名称 必需的 类型 注释
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/{id}_v2.json

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

调用者权限

所有客服

调用示例

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

返回值示例

Status: 200 OK

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

获取多个联系人信息

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

旧接口 “GET /api/v1/users/show_many.json?ids={ids}”

调用者权限

所有客服

调用示例

curl https://www.bangwo8.com/api/v1/users/show_many_v2.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":"cascade_address","value":[{"level_id":"s1","item_key":"4"}, \
{"level_id":"s2","item_key":"42"}, \
{"level_id":"s3","item_key":"427"}]}]}}'

返回值示例

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

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

修改联系人信息

PUT /api/v1/users/{id}.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": "张三",
    ...
  }
}

搜索联系人

GET /api/v1/users/search.json

调用者权限

所有客服

请求参数

名称 类型 必需的 注释
query string 搜索内容
sort_by string 按时间排序,目前支持:createDT-创建时间,updateDT-更新时间
sort_order string 按升序还是降序返回,取值为:asc-升序,desc-降序,默认为降序

query参数说明

搜索内容 返回结果
query=2444 模糊搜索,返回姓名或者手机号包含该内容的联系人
query=mobile:13240138429 搜索手机号为“13240138429”的联系人,此为精确搜索
query=field_1:454 返回自定义字段唯一标识为“field_1”的内容里面包含“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当天

4、目前搜索功能只支持手机号(mobile)筛选。

调用示例

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": "李四",
      ...
    }
  ]
}

页面工具