旧版鉴权方法

返回用户列表

请求方法

• url: /api/v1/customers.json
• 方式: get

请求参数

sign: 签名值 必选项
page: 页码 默认值为1 可选项
per_page: 每页数量 默认值为20 可选项

请求示例

• curl http://yourdomain.udesk.cn/api/v1/customers.json?page=1&per_page=10&sign=b48d4134e7d13839b09b5423e300c352 -v

返回结果

{
  status: 0表示添加成功
  message: "成功"
  size: 返回用户数量
  total:用户总数量
  contents:
  [{
      id:用户id
      email: 用户邮箱
      nick_name: 用户昵称
      telephone:用户电话(废弃)
    cellphone:用户电话
      weibo_name: 用户微博号
      weixin_id:用户微信id
  },...]
}

返回用户自定义字段

请求方法

• url: /api/v2/user_fields.json
• 方式: get

请求参数

sign: 签名值 必选项

请求示例

• curl http://yourdomain.udesk.cn/api/v2/user_fields.json?sign=b48d4134e7d13839b09b5423e300c352 -v

返回结果

{
  status: 0表示添加成功
  message: "成功"
  user_fields:
  [{
      field_name:字段名
      field_label: 字段别名
      content_type: 字段类型
      comment:字段描述
      options:选择类型字段的选项
      permission:客户权限设置
      requirment:是否必选
  },...]
}

返回指定id的用户详细信息

请求方法

• url: /api/v1/customers/#{id}.json
• 方式: get

请求参数

sign: 签名值 必选项
id: 用户id  必选项

请求示例

• curl http://yourdomain.udesk.cn/api/v1/customers/1.json?sign=b48d4134e7d13839b09b5423e300c352 -v

返回结果

{
  status: 0表示成功  1表示失败
  message: status=0，则"成功"     status=1，则“指定的id不存在”
  size: 1
  total: 1
  contents:指定id的用户详细信息
    {
      id：用户id
      email: 用户邮箱
      nick_name:用户昵称
      telephone:用户电话(废弃)
    cellphone:用户电话
      weibo_name:用户微博
      weixin_id:用户微信id
    }
}

返回指定id或email的用户详细信息

若指定email找不到，则创建新的用户。

请求方法

• url: /api/v1/customers/find_or_create_customer.json
• 方式: get

请求参数

sign: 签名值 必选项
id: 客户id 可选项，若客户email为空，则id必选
email:客户email 可选项，若客户id为空，则email必选

请求示例

• curl http://yourdomain.udesk.cn/api/v1/customers/find_or_create_customer.json?email=test@test.com&sign=b48d4134e7d13839b09b5423e300c352 -v

返回结果

{
  status: 0表示成功 1表示失败
  message: "成功"   若id和email均为空，则“请指定id或email” 若指定id但id不正确，则“指定的id不存在”
  若指定email但格式不正确，则指定的邮箱格式不正确，并创建新的用户
  customer:返回客户详细信息
  {
      id: 用户id
      email:用户邮箱
      nick_name:用户昵称
      telephone:用户电话（废弃）
    cellphone:用户电话
      weibo_name:用户微博
      weixin_id: 用户微信id
  }
}

创建用户

系统会优先根据提交的参数“客户邮箱”去查找客户，如果匹配成功，则根据本次提交的其它参数更新对应客户信息； 如果参数“客户邮箱”没有匹配，则根据参数“客户电话”继续查找客户，如果匹配成功，则根据本次提交的其它参数更新客户信息，如果仍没有匹配成功，则创建新用户。

请求方法

• url: /api/v2/customer_import.json
• 方式: post

请求参数

参数说明：

参数名称	必选	说明
sign	是	签名值,此接口签名只需对企业的secret进行md5加密
email	否	客户邮箱
nick_name	否	客户姓名
cellphone	否	客户电话
description	否	客户描述
weixin_id	否	微信
weibo_name	否	微博
qq	否	qq账号
org_name	否	公司名称
owner_group_name	否	客户负责组名称
agent_email	否	客户负责人，请提交已在系统注册的客服邮箱。
customer_field	否	客户自定义字段

注:如果需要添加客户自定义字段 1. 请先用管理员账号登录Udesk，在“管理中心-管理中心”下添加客户自定义字段。 2. 然后调用接口“返回客户自定义字段接口”，取“field_name”值作为自定义字段的key值。详见请求示例。

请求示例

-H "Content-Type: application/json"

{
    "sign":"d84e9bc64a91cb8bb4d115167ec80fb5",
    "user":{
        "email":"huxj0101@163.com",
        "nick_name":"我是api创建的",
        "cellphone":"18878238222",
        "description":"这是描述",
        "weixin_id":"微信测试号",
        "weibo_name":"微博测试号",
        "qq":"12312",
        "org_name":"沃丰时代",
    "owner_group_name":"默认组",
    "agent_email":"agent@163.com",
        "customer_field":{
            "TextField_437":"意向客户",
            "SelectField_495":["1"]
        }
    }
}

请求示例

• curl http://yourdomain.udesk.cn/api/v2/customer_import.json \ -d '{"email":"test@test.com", "nick_name":"test", "sign":"b48d4134e7d13839b09b5423e300c352"}' \ -H "Content-Type: application/json" -X POST

返回结果

{
  status: 0表示添加成功   1001表示添加失败
  message: 若status=0 则"客户创建成功"  若status=1001 提示相应的错误信息
}

客户批量导入

请求示例

• URL: http://yourdomain.udesk.cn/api/v2/customer_import_async?sign=d5dddb0aa968fc0ab4578369be700327
• VERB: POST
• 限制: 每隔20秒可以调用1次

请求参数

users:              客户数据数组
  email:            邮箱
  nick_name:        姓名
  description:      描述
  cellphone:        电话
  owner_group_name: 负责客服组名称
  agent_email:      负责客服邮箱

返回结果

status: 状态, 成功时为0
job_id: 导入任务id, 用于查询任务进度和执行结果

客户批量导入任务查询

• URL: http://yourdomain.udesk.cn/api/v2/customer_import_async/job_status?job_id=1sign=d5dddb0aa968fc0ab4578369be700327
• VERB: GET

请求参数

job_id 导入任务id

返回结果

status: 状态, 成功时为0
job_status:
  completed:  是否完成, true|false
  total:      客户总数量
  success:    成功导入的客户数
  failed:     导入失败的客户数
  failed_msg: 导入失败的原因, 数组: [[列数, 失败原因],...]

更新客户

请求方法

• URL http://yourdomain.udesk.cn/api/v2/customers/:id.json?sign=d5dddb0aa968fc0ab4578369be700327
• VERB POST

请求参数说明：

user:
  email:            String
  nick_name:        String
  weixin_id:        String
  weibo_name:        String
  cellphone:        String
  sdk_token:        String
  qq:        String
  description:        String
  custom_fields: {
    SelectField_1: ["0", "1"],
    TextField_2: "string"
  }

返回结果
{
  status: 0,
  message: 'success',
  robot:   '',
  customer: customer(客户信息对象)
}

删除客户

请求方法

• URL http://yourdomain.udesk.cn/api/v2/customers/:id?sign=d5dddb0aa968fc0ab4578369be700327
• VERB DELETE

返回成功

{
    status: 0,
    message: 'success'
}

返回失败

{
    "status": 1000,
    "message": "failure"
}