获取自定义字段列表

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

请求方法

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 计算字段

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": "下拉选项1", "value": "0"},
                {"title": "下拉选项2", "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": "单选框选项1", "value": "1"},
                {"title": "单选框选项2", "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": "多选框选项1", "value": "3"},
                {"title": "多选框选项2", "value": "4"},
                {"title": "多选框选项3", "value": "1"},
                {"title": "多选框选项4", "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_97SelectField_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

名称类型是否必须默认值备注其他信息
titlestring非必须下拉选项标题精确查询
valuestring非必须下拉选项value
create_rangestring非必须选项创建时间范围(YYYY-MM-DD HH:mm,YYYY-MM-DD HH:mm)
update_rangestring非必须选项更新时间范围(YYYY-MM-DD HH:mm,YYYY-MM-DD HH:mm)
pagenumber非必须页码(默认为1)
per_pagenumber非必须每页记录数量(最大100,默认20)

返回数据

名称类型是否必须默认值备注其他信息
codenumber非必须响应状态码(1000成功)
messagestring非必须响应状态说明
metaobject非必须
├─ pagenumber非必须页码
├─ total_pagesnumber非必须总页数
├─ total_countnumber非必须总记录条数
select_optionsobject []非必须

item 类型: object

├─ titlestring非必须选项标题
├─ valuestring非必须选项值
├─ is_hideboolean非必须是否隐藏
├─ defaultboolean非必须是否默认选项
├─ created_atstring非必须创建时间
├─ updated_atstring非必须更新时间

请求报文示例

{
    "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