自定义字段接口 - Udesk

获取自定义字段列表

该接口用于获取已创建的自定义字段

请求方法

get /custom_fields

请求参数

参数名	必填	类型	说明	限制
category	否	字符串	要获取的自定义字段类型，具体说明见下文，默认为工单	枚举，取值范围：`["ticket", "customer", "organization"]` 若传入其他值，不会报错，但相当于传入了ticket

category 说明

选项	说明
ticket	工单自定义字段
customer	客户自定义字段
organization	客户公司自定义字段

返回数据

属性名	类型	说明
code	整型	执行结果码，1000代表成功
fields	数组	自定义字段列表，具体见下文

custom_fields 中元素说明

属性名	类型	说明
id	整型	id
field_name	字符串	字段标识
field_label	字符串	字段显示名称
content_type	字符串	字段类型，具体见下文
comment	字符串	字段备注
updated_at	日期时间	字段最后更新时间
options	数组	字段选项，仅选择类型字段返回，具体见下文
customer_permission	字符串	客户权限，仅客户字段与工单字段返回，具体见下文
agent_permission	字符串	客服权限，仅客户字段与客户公司字段返回，具体见下文
calculate_result_type	字符串	计算字段的计算结果类型，仅计算字段返回，具体见下文

content_type 取值范围

取值	说明
text	单行文本
area_text	多行文本
date	日期
time	时间
datetime	日期时间
link	超链接
location	地理位置
number	正整数
numeric	数值
droplist	下拉列表
radio	单选
checkbox	多选
chained_droplist	级联
calculate	计算字段

content_type的取值范围会随着功能的增加而扩大，建议业务逻辑保持对新类型的扩展性。
具体每种自定义字段类型的选项结构，见示例。

calculate_result_type 取值范围

取值	说明
numeric	数字
duration	时长
percentage	百分比

options 说明

数组元素结构

属性名	类型	说明
title	字符串	选项文字描述
value	字符串	选项值
default	布尔值	是否为默认选项
is_hide	布尔值	是否隐藏
subs	数组	子选项，仅级联字段包含，结构与options相同

customer_permission 取值范围

取值	说明
none	客户不可见
readonly	客户可见，但不可编辑
readwrite	客户可编辑
must	客户必填

agent_permission 取值范围

取值	说明
readonly	客服可见，但不可编辑
readwrite	客服可编辑
must	客服必填

示例

请求

curl -s https://demo.udesk.cn/open_api_v1/custom_fields?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
&category=customer

{
    "code": 1000,
    "fields": [
        {
            "field_name": "TextField_1",
            "field_label": "单行文本字段",
            "content_type": "text",
            "comment": null,
            "updated_at": "2017-01-17T14:13:41.000+08:00",
            "options": null,
            "customer_permission": "readwrite",
            "agent_permission": "must"
        },
        {
            "field_name": "TextField_2",
            "field_label": "多行文本字段",
            "content_type": "area_text",
            "comment": null,
            "updated_at": "2017-01-17T14:13:41.000+08:00",
            "options": null,
            "cusotmer_permission": "readwrite",
            "agent_permission": "readwrite"
        },
        {
            "field_name": "TextField_3",
            "field_label": "日期字段",
            "content_type": "date",
            "comment": null,
            "updated_at": "2017-01-17T14:13:41.000+08:00",
            "options": null,
            "customer_permission": "read",
            "agent_permission": "must"
        },
        {
            "field_name": "TextField_4",
            "field_label": "日期时间字段",
            "content_type": "datetime",
            "comment": null,
            "updated_at": "2017-01-17T14:13:41.000+08:00",
            "options": null,
            "customer_permission": "read",
            "agent_permission": "readwrite"
        },
        {
            "field_name": "TextField_5",
            "field_label": "链接字段",
            "content_type": "link",
            "comment": null,
            "updated_at": "2017-01-17T14:13:41.000+08:00",
            "options": null,
            "customer_permission": "must",
            "agent_permission": "readwrite"
        },
        {
            "field_name": "TextField_6",
            "field_label": "地理位置字段",
            "content_type": "location",
            "comment": null,
            "updated_at": "2017-01-17T14:13:41.000+08:00",
            "options": null,
            "customer_permission": "none",
            "agent_permission": "readwrite"
        },
        {
            "field_name": "TextField_7",
            "field_label": "时间字段",
            "content_type": "time",
            "comment": null,
            "updated_at": "2017-01-17T14:13:41.000+08:00",
            "options": null,
            "customer_permission": "none",
            "agent_permission": "readwrite"
        },
        {
            "field_name": "TextField_8",
            "field_label": "正整数字段",
            "content_type": "number",
            "comment": null,
            "updated_at": "2017-01-17T14:13:41.000+08:00",
            "options": null,
            "customer_permission": "none",
            "agent_permission": "must"
        },
        {
            "field_name": "TextField_9",
            "field_label": "数值字段",
            "content_type": "numeric",
            "comment": null,
            "updated_at": "2017-01-17T14:13:41.000+08:00",
            "options": null,
            "customer_permission": "none",
            "agent_permission": "readwrite"
        },
        {
            "field_name": "SelectField_1",
            "field_label": "下拉列表字段",
            "content_type": "droplist",
            "comment": null,
            "updated_at": "2017-01-17T14:13:41.000+08:00",
            "customer_permission": "read",
            "agent_permission": "readwrite",
            "options": [
                {"title": "下拉选项１", "value": "0"},
                {"title": "下拉选项２", "value": "1"}
            ]
        },
        {
            "field_name": "SelectField_2",
            "field_label": "单选框字段",
            "content_type": "radio",
            "comment": null,
            "updated_at": "2017-01-17T14:13:41.000+08:00",
            "customer_permission": "read",
            "agent_permission": "readwrite",
            "options": [
                {"title": "单选框选项１", "value": "1"},
                {"title": "单选框选项２", "value": "0"}
            ]
        },
        {
            "field_name": "SelectField_3",
            "field_label": "多选框字段",
            "content_type": "checkbox",
            "comment": null,
            "updated_at": "2017-01-17T14:13:41.000+08:00",
            "customer_permission": "none",
            "agent_permission": "must",
            "options": [
                {"title": "多选框选项１", "value": "3"},
                {"title": "多选框选项２", "value": "4"},
                {"title": "多选框选项３", "value": "1"},
                {"title": "多选框选项４", "value": "7"}
            ]
        },
        {
            "field_name": "SelectField_4",
            "field_label": "级联字段",
            "content_type": "chained_droplist",
            "comment": null,
            "updated_at": "2017-01-17T14:13:41.000+08:00",
            "options": [
                {"title": "北京市", "value": "0", "subs": [
                    {"title": "海淀区", "value": "0", "subs": [
                        {"title": "知春路", "value": "0"}
                    ]}
                ]},
                {"title": "天津市", "value": "0", "subs": [
                    {"title": "和平区", "value": "0"}
                ]}
            ],
            "customer_permission": "none",
            "agent_permission": "must"
        }
    ]
}

获取单个自定义字段

该接口用于获取单个自定义字段详情

请求方法

GET /custom_fields/:field_name

请求参数

无

返回数据

属性名	类型	说明
code	整型	执行结果码，1000代表成功
field	对象	具体字段含义参考上边的custom_fields 中元素说明

示例

curl https://demo.udesk.cn/open_api_v1/custom_fields/SelectField_1?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2

返回：
{
  "code": 1000,
  "field": {
    "id": 1,
    "field_name": "SelectField_1",
    "field_label": "下拉列表",
    "content_type": "droplist",
    "comment": "",
    "updated_at": "2020-10-19T13:37:01.000+08:00",
    "customer_permission": "readwrite",
    "options": [
        {
            "title": "a",
            "value": "0"
        },
        {
            "title": "b",
            "value": "1",
            "default": true
        },
        {
            "title": "c",
            "value": "2"
        }
    ]
  }
}

更新自定义字段

该接口用于更新指定自定义字段，暂不支持级联字段

请求方法

PUT /custom_fields/:field_name

通过获取自定义字段列表接口可以获取所有自定义字段信息

请求参数

参数	必填	类型	说明
field_name	是	字符串	参数field_name可在自定义字段配置页面中的字段ID列获取，或者通过获取自定义字段列表api接口返回数据中的field_name字段获取如`TextField_97`，`SelectField_166`
title	否	字符串	自定义字段标题
comment	否	字符串	自定义字段备注
select_options	否	数组	选择形字段选项参数，仅更新选择性字段时需要此参数。如果不更新选择性字段的选项，该参数可不填

select_options中的元素说明

通过获取自定义字段列表接口可以获取自定义字段信息

参数	必填	类型	说明	限制
title	是	字符串	选项标题
value	是	字符串	选项值	1.`value`为系统自动生成，不要修改！ 2. 当新增选项时，不需要传递`value`选项！
default	否	布尔值	默认生效选项	如果使用了该参数，那么它的值只能为`true`

value 为系统自动生成，不要修改！

当新增选项时，不需要传递value选项！

示例

更新单选字段

curl https://demo.udesk.cn/open_api_v1/custom_fields/SelectField_1?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
 \
-X PUT \
-H 'content-type:application/json' \
-d '
{
  "title": "api测试更改单选框自定义字段",
  "comment": "api测试更改单选框自定义字段",
  "select_options": [
      {
          "title": "第一个选项",
          "value": "0",
          "default": true
      },
      {
          "title": "第二个选项",
          "value": "1",
          "is_hide": true
      },
      {
          "title": "新增第三个选项",
      }
  ]
}'

更新单行文本字段

curl https://demo.udesk.cn/open_api_v1/custom_fields/TextField_1?email=admin@udesk.cn&timestamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
 \
-X PUT \
-H 'content-type:application/json' \
-d '
{
  "title": "api测试更改单行文本自定义字段",
  "comment": "api测试更改单行文本自定义字段",
}'

返回值

{
  "code": 1000,
  "message": "更新成功"
}

获取下拉大批量选项字段对应选项

基本信息

Path： /open_api_v1/custom_fields/large_droplists/{field_id}

Method： POST

接口描述： 本接口针对下拉大批量选项，根据给定筛选条件获取对应的选项列表（支持分页）

请求参数

Headers

Content-Type: application/json

路径参数

参数名称	示例	备注
field_id	SelectField_1	下拉字段名称

Query

参数名称	是否必须	示例	备注
email	是	test@udesk.cn	管理员邮箱
timestamp	是	1676616977	时间戳
nonce	是	42a5551c	随机串
sign_version	是	v2
sign	是	c24ad2a82901c1014572a51381ef0f32b278bd7ccf998af5a0ed592536e6ecc1	签名

Body

名称	类型	是否必须	备注	其他信息
title	string	非必须	下拉选项标题	精确查询
value	string	非必须	下拉选项value
create_range	string	非必须	选项创建时间范围（YYYY-MM-DD HH:mm,YYYY-MM-DD HH:mm）
update_range	string	非必须	选项更新时间范围（YYYY-MM-DD HH:mm,YYYY-MM-DD HH:mm）
page	number	非必须	页码（默认为1）
per_page	number	非必须	每页记录数量（最大100，默认20）

返回数据

名称	类型	是否必须	备注	其他信息
code	number	非必须	响应状态码（1000成功）
message	string	非必须	响应状态说明
meta	object	非必须
├─ page	number	非必须	页码
├─ total_pages	number	非必须	总页数
├─ total_count	number	非必须	总记录条数
select_options	object []	非必须		item 类型: object
├─ title	string	非必须	选项标题
├─ value	string	非必须	选项值
├─ is_hide	boolean	非必须	是否隐藏
├─ default	boolean	非必须	是否默认选项
├─ created_at	string	非必须	创建时间
├─ updated_at	string	非必须	更新时间

请求报文示例

{
    "page":1,
    "update_range":"2023-02-17 08:00,2023-02-17 12:00"
}

响应报文示例

{
    "code":1000,
    "message":"success",
    "meta":{
        "page":1,
        "total_pages":10,
        "total_count":300
    },
    "select_options":[
        {
            "title":"选项标题",
            "value":"1",
            "is_hide":false,
            "default":true,
            "created_at":"2023-02-17 11:11:11",
            "updated_at":"2023-02-17 11:11:11"
        }
    ]
}

自定义字段结构说明

说明

Udesk目前支持两种自定义字段名称 SelectField TextField

字段名	类型	说明
SelectField_1	数组	选择型字段类型（包含下拉、复选框、及联字段），类型名称_唯一ID
TextField_1	字符串	文本型字段类型，类型名称_唯一ID

Code错误码

错误码	message信息	exception:message信息	描述
2005	没有找到该资源	未找到指定自定义字段	传入的field_name格式有误或根据所传field_name找不到对应资源
2015	非管理员不可以操作	非管理员不可以操作	调用接口时的邮箱必须为管理员邮箱，非管理员不可以操作
2059	open api签名不对	open api签名不对	open api签名不对，详细内容参考鉴权部分的文档
2062	参数错误	参数select_options数组中元素中的title必填	修改自定义字段时，参数select_options数组中元素中的title必填
	参数错误	field_name参数仅支持 TextField	SelectField

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

获取自定义字段列表

请求方法

请求参数

category 说明

返回数据

custom_fields 中元素说明

content_type 取值范围

calculate_result_type 取值范围

options 说明

customer_permission 取值范围

agent_permission 取值范围

示例

获取单个自定义字段

请求方法

请求参数

返回数据

示例

更新自定义字段

请求方法

请求参数

select_options中的元素说明

示例

更新单选字段

更新单行文本字段

返回值

获取下拉大批量选项字段对应选项

基本信息

请求参数

返回数据

请求报文示例

响应报文示例

自定义字段结构说明

说明

Code错误码

文档反馈