客户接口 - Udesk | 开发者中心

获取客户列表

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

请求方法

GET /api/v1/customers.json

请求参数（Query String）

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

返回数据

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

示例

curl https://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 https://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 https://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 https://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": "https://www.sample.com",           // 链接
            "TextField_7": "13",                              // 正整数
            "TextField_8": "13.33",                           // 数值
            "SelectField_1": "0",                             // 下拉列表，下拉选项1
            "SelectField_2": "0",                             // 单选框，单选框选项1
            "SelectField_3": "0,3",                           // 多选框，多选框选项1、多选框选项4
        }
    }
}

status错误码说明

错误码	message信息	描述	备注
1001	指定的id不存在	没有指定{id}或{email}	用于”查找或创建客户“接口
	指定的id不存在	url中参数{id}错误，未匹配到值	用于”获取客户详情“接口

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search

获取客户列表

请求方法

请求参数（Query String）

返回数据

示例

查找或创建客户

请求方法

请求参数（Query String）

返回数据

示例

获取客户详情

请求方法

请求参数（URL中）

返回数据

示例

获取客户自定义字段列表

请求方法

请求参数

返回数据

示例

数据结构-客户

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

content_type 的取值范围

permission 的取值范围

options 的结构

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

status错误码说明

文档反馈