客户接口

获取客户列表

该接口用于一次获取多个客户信息

请求方法

GET /api/v1/customers.json

请求参数(Query String)

参数名 必填 说明
page 页码,从1开始,默认为1
per_page 每页数量,默认20,最大100

返回数据

属性名 类型 说明
status 整型 执行结果码,0代表成功
message 字符串 执行结果说明
size 整型 本次返回的数据数量
total 整型 数据总数
total_pages 整型 总页数
contents 数组 客户列表,每个客户的内容参见客户数据结构

示例

curl http://demo.udesk.cn/api/v1/customers?page=1&per_page=10&sign=129da7df812jdfsa9912jfdadf81

返回

{
    "status": 0,
    "message": "成功",
    "size": 1,
    "total": 1,
    "contents": [
        {
            "id": 1,
            "email": "customer@sample.com",
            "nick_name": "测试用户",
            "telephone": "13000000001",
            "cellphone": "13000000001"
        }
    ]
}

查找或创建客户

该接口用于根据id或邮箱查找客户,如果没有找到则创建一个新客户并返回

请求方法

GET /api/v1/customers/find_or_create_customer.json

请求参数(Query String)

参数名 必填 说明
id 客户id,如果email为空,则id必填
email 客户邮箱,如果id为空,则email必填

如果同时提供了 id 和 email,则查找顺序为先按 id 查找,找不到再按 email 查找,再次找不到则创建客户。

返回数据

属性名 类型 说明
status 整型 执行结果码,0代表成功
message 字符串 执行结果说明
customer 对象 客户信息,参见客户数据结构

示例

curl http://demo.udesk.cn/api/v1/customers/find_or_create_customer?email=customer@sample.com&sign=129da7df812jdfsa9912jfdadf81

返回

{
    "status": 0,
    "message": "成功",
    "customer": {
        "id": 1,
        "email": "customer@sample.com",
        "nick_name": "测试用户",
        "telephone": "13000000001",
        "cellphone": "13000000001"
    }
}

获取客户详情

该接口用于获取指定 id 的单个客户信息

请求方法

GET /api/v1/customers/:id.json

请求参数(URL中)

参数名 必填 说明
id 客户id

返回数据

属性名 类型 说明
status 整型 执行结果码,0代表成功
message 字符串 执行结果说明
size 整型 本次返回的数据数量(废弃)
total 整型 数据总数(废弃)
contents 对象 客户信息,参见客户数据结构

示例

curl http://demo.udesk.cn/api/v1/customers/1?sign=129da7df812jdfsa9912jfdadf81

返回

{
    "status": 0,
    "message": "成功",
    "size": 1,
    "total": 1,
    "contents": {
        "id": 1,
        "email": "customer@sample.com",
        "nick_name": "测试用户",
        "telephone": "13000000001",
        "cellphone": "13000000001"
    }
}

获取客户自定义字段列表

该接口用于一次获取全部客户自定义字段信息

请求方法

GET /api/v2/user_fields.json

请求参数

返回数据

属性名 类型 说明
status 整型 执行结果码,0代表成功
message 字符串 执行结果说明
user_fields 数组 自定义字段列表,每个元素的结构参见客户自定义字段

该接口不支持级联字段,虽然能获取到级联字段的信息但是其 options 格式是不正确的。

示例

curl http://demo.udesk.cn/api/v2/user_fields?sign=129da7df812jdfsa9912jfdadf81

返回

{
    "status": 0,
    "message": "success",
    "user_fields": [
        {
            "field_name": "TextField_9",
            "field_label": "单行文本字段",
            "content_type": "text",
            "comment": null,
            "options": null,
            "permission": 2,
            "requirment": false
        },
        {
            "field_name": "TextField_10",
            "field_label": "多行文本字段",
            "content_type": "area_text",
            "comment": null,
            "options": null,
            "permission": 2,
            "requirment": false
        },
        {
            "field_name": "TextField_11",
            "field_label": "日期字段",
            "content_type": "date",
            "comment": null,
            "options": null,
            "permission": 2,
            "requirment": false
        },
        {
            "field_name": "TextField_12",
            "field_label": "时间字段",
            "content_type": "time",
            "comment": null,
            "options": null,
            "permission": 2,
            "requirment": false
        },
        {
            "field_name": "TextField_13",
            "field_label": "日期时间字段",
            "content_type": "datetime",
            "comment": null,
            "options": null,
            "permission": 2,
            "requirment": false
        },
        {
            "field_name": "TextField_14",
            "field_label": "链接字段",
            "content_type": "link",
            "comment": null,
            "options": null,
            "permission": 2,
            "requirment": false
        },
        {
            "field_name": "TextField_15",
            "field_label": "正整数字段",
            "content_type": "number",
            "comment": null,
            "options": null,
            "permission": 2,
            "requirment": false
        },
        {
            "field_name": "TextField_16",
            "field_label": "数值字段",
            "content_type": "numeric",
            "comment": null,
            "options": null,
            "permission": 2,
            "requirment": false
        },
        {
            "field_name": "SelectField_5",
            "field_label": "下拉列表字段",
            "content_type": "droplist",
            "comment": null,
            "options": [
                {"0": "下拉选项1"},
                {"1": "下拉选项2"},
                {"2": "下拉选项3"}
            ],
            "permission": 2,
            "requirment": true
        },
        {
            "field_name": "SelectField_6",
            "field_label": "单选框字段",
            "content_type": "radio",
            "comment": null,
            "options": [
                {"0": "单选框选项1"},
                {"1": "单选框选项2"}
            ],
            "permission": 2,
            "requirment": true
        },
        {
            "field_name": "SelectField_6",
            "field_label": "多选框字段",
            "content_type": "checkbox",
            "comment": null,
            "options": [
                {"0": "多选框选项1"},
                {"1": "多选框选项2"},
                {"2": "多选框选项3"},
                {"3": "多选框选项4"}
            ],
            "permission": 2,
            "requirment": false
        }
    ]
}

数据结构-客户

属性名 类型 说明
id 整型 唯一标识
email 字符串 邮箱
nick_name 字符串 姓名
cellphone 字符串 第一个联系电话
telephone 字符串 联系电话(已废弃,内容与cellphone相同)

数据结构-客户自定义字段

属性 类型 说明
field_name 字符串 标识名
field_label 字符串 名称
content_type 字符串 类型
comment 字符串 备注
options 数组 选择类型自定义字段的选项,参看以下<选择类型自定义字段选项结构>
permission 整型 客户权限(已废弃)
requirement 布尔 是否必填(已废弃)

content_type 的取值范围

含义
text 单行文本
area_text 多行文本
date 日期
time 时间
datetime 日期时间
link 链接
number 正整数
numeric 数值
droplist 下拉列表
checkbox 多选框
radio 单选框
chained_droplist 级联

permission 的取值范围

含义
0 客户不可见
1 客户可见但不可编辑
2 客户可编辑
3 客户必填

options 的结构

下拉列表、多选框、单选框options的格式为[{"选项索引":"选项名称"}, ...],例如单选框"性别"的options可能是:

{
    "options": [
        {"0": "男"},
        {"1": "女"},
        {"2": "保密"}
    ]
}

自定义字段及其值的设置方法

自定义字段分为文本类型和选择类型,文本类型的值就是符合特定格式的字符串,选择类型则是其选项的索引值。 下面以客户为例,说明自定义字段的设置方法。

假设有以下客户自定义字段:

[
    {
        "field_name": "TextField_1",
        "field_label": "单行文本字段",
        "content_type": "text",
    },
    {
        "field_name": "TextField_2",
        "field_label": "多行文本字段",
        "content_type": "area_text",
    },
    {
        "field_name": "TextField_3",
        "field_label": "日期字段",
        "content_type": "date",
    },
    {
        "field_name": "TextField_4",
        "field_label": "时间字段",
        "content_type": "time",
    },
    {
        "field_name": "TextField_5",
        "field_label": "日期时间字段",
        "content_type": "datetime",
    },
    {
        "field_name": "TextField_6",
        "field_label": "链接字段",
        "content_type": "link",
    },
    {
        "field_name": "TextField_7",
        "field_label": "正整数字段",
        "content_type": "number",
    },
    {
        "field_name": "TextField_8",
        "field_label": "数值字段",
        "content_type": "numeric",
    },
    {
        "field_name": "SelectField_1",
        "field_label": "下拉列表字段",
        "content_type": "droplist",
        "options": [
            {"0": "下拉选项1"},
            {"1": "下拉选项2"},
            {"2": "下拉选项3"}
        ],
    },
    {
        "field_name": "SelectField_2",
        "field_label": "单选框字段",
        "content_type": "radio",
        "options": [
            {"0": "单选框选项1"},
            {"1": "单选框选项2"}
        ],
    },
    {
        "field_name": "SelectField_3",
        "field_label": "多选框字段",
        "content_type": "checkbox",
        "options": [
            {"0": "多选框选项1"},
            {"1": "多选框选项2"},
            {"2": "多选框选项3"},
            {"3": "多选框选项4"}
        ],
    }
]

在某个客户中,其表示如下:

{
    "customer": {
        "custom_fields": {
            "TextField_1": "普通文本内容",                    // 普通文本
            "TextField_2": "多行文本内容1\r\n多行文本内容2",  // 多行文本
            "TextField_3": "2016-08-11",                      // 日期
            "TextField_4": "14:44:36",                        // 时间
            "TextField_5": "2017-05-03 14:44",                // 日期时间
            "TextField_6": "http://www.sample.com",           // 链接
            "TextField_7": "13",                              // 正整数
            "TextField_8": "13.33",                           // 数值
            "SelectField_1": "0",                             // 下拉列表,下拉选项1
            "SelectField_2": "0",                             // 单选框,单选框选项1
            "SelectField_3": "0,3",                           // 多选框,多选框选项1、多选框选项4
        }
    }
}