字段类型说明

创建或更新记录时, 请根据字段类型, 按照以下格式组装数据。

字段类型 类型名称 字段值格式 说明
field_type_single_line 单行文本 "测试_single_line" 文本类字段, 长度不能超过限制.
field_type_text_long 长文本 "测试_text_long" 文本类字段, 长度不能超过限制.
field_type_rich_text 富文本 "测试_rich_text" 文本类字段, 长度不能超过限制.
field_type_multi_line 多行文本 "测试_multi_line" 文本类字段, 长度不能超过限制.
field_type_date 日期 "2020-01-01" "yyyy-MM-dd"
field_type_date_time 时间 "2020-01-01 12:12:12" "yyyy-MM-dd HH:mm:ss ", 精确到秒.
field_type_numeric 数字 "1"
field_type_telephone 电话 "13300000001,13300000002" 多个号码使用逗号分隔.

号码必须合法,
1. 手机号: "1[3456789]"开头
2. 电话号: 不能包含横杠
3. 400热线
4. 运营商热线: 10086, 10010, 10000
field_type_email 电子邮件 "admin1@test.cn,admin2@test.cn" 多个邮箱地址使用逗号分隔.
邮箱地址必须合法
field_type_single_listbox 单选列表 "选项名称1"
field_type_multi_listbox 多选列表 "选项名称1,选项名称2" 多个选项使用逗号分隔.
field_type_auto_number 自动编号 自动编号字段不支持接口变更.
field_type_formular 计算公式 计算公式字段不支持接口变更.
field_type_lookup 查找型 "000001"
"13300000001"
"admin1@test.cn"
查找对象唯一字段的值, 需要配合foreignExternalFieldApiName一起使用. 不传foreignExternalFieldApiName时,fieldDataList[].fieldValue要传dataId
field_type_staff 查找员工 "admin3@test.cn" 员工邮箱地址.
field_type_percent 百分比 "0.3" 原始值, 如30%, 传0.3即可.
field_type_owner 所有人 所有人字段不支持接口变更.
field_type_work_time 工作时间 "测试工作时间01"
field_type_geography 坐标 "116.1884784900,39.9902888700" 经度在前, 纬度在后, 中间使用逗号分隔.
field_type_wechat 微信 "公众号id,OpenId", 逗号分隔.
field_type_sign 签名 签名字段不支持接口变更.
field_type_voice 语音 语音字段不支持接口变更.
field_type_lead_pool 公海 "测试公海01"
field_type_statistics 统计 统计字段不支持接口变更.
field_type_timer 计时 计时字段不支持接口变更.
field_type_cascade 级联 "选项1,选项11" "父级选项名称,子级选项名称",英文逗号隔开
field_type_customize_structure 定制 "{\"values\":[]}" 定制字段的值

查询字段列表

GET /v1/fields

请求参数
参数 类型 必填 说明
objectApiName 字符串 对象API_NAME.
响应数据
属性名 类型 说明
code 整型 响应编码.
message 字符串 响应消息.
visible 布尔型 是否可见, true / false .
data 数组 业务对象.
data[].id 整型 字段ID.
data[].label 字符串 显示名称.
data[].apiName 字符串 API名称.
data[].fieldTypeName 字符串 字段类型.
data[].permissionCode 整型 字段权限码:1隐藏;2只读;3必填;4选填.
data[].optionList 数组 单选或多选字段选项信息
data[].optionList[].id 整型 选项ID
data[].optionList[].name 字符串 选项名称
请求示例
$ curl 'https://servicego.udesk.cn/api/v1/fields?email=admin@udesk.cn&timestamp=1496631984&sign=ef506d04ef74e1031f91025494244e88f3559b78&objectApiName=contact' -i -H 'Content-Type: application/json' -H 'Accept: application/json'
响应示例
{
  "code" : 200,
  "message" : "OK",
  "visible" : false,
  "data" : [ {
    "id" : 7,
    "label" : "姓名",
    "apiName" : "name",
    "fieldTypeName" : "单行文本",
    "permissionCode" : 3,
    "optionList":[]
  }, {
    "id" : 13,
    "label" : "邮箱",
    "apiName" : "mailAddress",
    "fieldTypeName" : "电子邮件",
    "permissionCode" : 4,
    "optionList":[]
  }, {
    "id" : 14,
    "label" : "电话",
    "apiName" : "phone",
    "fieldTypeName" : "电话",
    "permissionCode" : 4
    "optionList":[]
  }, {
    "id" : 15,
    "label" : "性别",
    "apiName" : "gender",
    "fieldTypeName" : "性别",
    "permissionCode" : 4
    "optionList":[ {
            "id": 1,
            "name": "男"
        }, {
            "id": 2,
            "name": "女"
        } ]
  } ]
}

查询部分字段

POST /v1/fields

请求参数
参数 类型 必填 说明
objectApiName 字符串 对象API_NAME.
fieldApiNameList 数组 字段API_NAME数组
响应数据
属性名 类型 说明
code 整型 响应编码.
message 字符串 响应消息.
visible 布尔型 是否可见, true / false .
data 数组 业务对象.
data[].id 整型 字段ID.
data[].label 字符串 显示名称.
data[].apiName 字符串 API名称.
data[].fieldTypeName 字符串 字段类型.
data[].permissionCode 整型 字段权限码:1隐藏;2只读;3必填;4选填.
data[].optionList 数组 单选或多选字段选项信息
data[].optionList[].id 整型 选项ID
data[].optionList[].name 字符串 选项名称
请求示例
$ curl 'https://servicego.udesk.cn/api/v1/fields?email=admin@udesk.cn&timestamp=1496631984&sign=ef506d04ef74e1031f91025494244e88f3559b78' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
    "objectApiName":"case",
    "fieldApiNameList":["name","mailAddress","phone","gender"]
}'
响应示例
{
  "code" : 200,
  "message" : "OK",
  "visible" : false,
  "data" : [ {
    "id" : 7,
    "label" : "姓名",
    "apiName" : "name",
    "fieldTypeName" : "单行文本",
    "permissionCode" : 3,
    "optionList":[]
  }, {
    "id" : 13,
    "label" : "邮箱",
    "apiName" : "mailAddress",
    "fieldTypeName" : "电子邮件",
    "permissionCode" : 4,
    "optionList":[]
  }, {
    "id" : 14,
    "label" : "电话",
    "apiName" : "phone",
    "fieldTypeName" : "电话",
    "permissionCode" : 4
    "optionList":[]
  }, {
    "id" : 15,
    "label" : "性别",
    "apiName" : "gender",
    "fieldTypeName" : "性别",
    "permissionCode" : 4
    "optionList":[ {
            "id": 1,
            "name": "男"
        }, {
            "id": 2,
            "name": "女"
        } ]
  } ]
}

更新字段信息

PUT /v1/field

请求参数
参数 类型 必填 说明
id 整型 字段ID.
fieldType 整型 字段类型
customizeStructure 字符串 当fieldType为35(定制字段)时,使用该字段信息
响应数据
属性名 类型 说明
code 整型 响应编码.
message 字符串 响应消息.
visible 布尔型 是否可见, true / false .
请求示例
curl --location --request PUT 'http://servicego.udesk.cn/v1/field?email=1@test.cn&timestamp=1608114461&sign=74cfd90f2e7a62d5cba147719f014d6a94d325a3' \
--header 'Content-Type: application/json' \
--data-raw '{
  "customizeStructure": "[{}]",
  "fieldType": 35,
  "id": 26745
}'
响应示例
成功响应:
{
    "code": 200,
    "visible": false,
    "message": "OK"
}
失败响应:
{
    "code": 400,
    "message": "字段类型不能为空!",
    "visible": true
}

创建字段选项值

为单选,多选和级联字段创建选项值

POST /v1/fields/options
请求参数
参数 类型 必填 说明
objectApiName 字符串 自定义对象API名称
fieldDataList[] 对象数组 字段信息
fieldDataList[].fieldApiName 字符串 对象自定义字段API名称,只支持单选字段,多选字段,级联字段
fieldDataList[].options[] 字符串数组 字段选项值,每个字符串代表一个选项值,级联字段使用英文冒号来
响应数据
属性名 类型 说明
code 整型 响应编码.
message 字符串 响应消息.
visible 布尔型 是否可见, true / false .
请求示例
$ curl 'https://servicego.udesk.cn/api/v1/fields/options?email=admin@udesk.cn&timestamp=1496631984&sign=ef506d04ef74e1031f91025494244e88f3559b78' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d '{
    "objectApiName":"case",
    "fieldDataList":[{
        "fieldApiName":"level",
        "options":["一星级", "二星级","三星级"]
    },{
        "fieldApiName":"cascadeField",
        "options":["北京:海淀", "北京:西城","上海"]
    }]
}'
响应示例
成功响应:
{
    "code": 200,
    "visible": false,
    "message": "OK"
}
失败响应:
{
    "code": 400,
    "message": "对象ApiName不能为空",
    "visible": true
}

查询级联关系

GET /v1/cascadeFields/{ids}

请求参数
参数 类型 必填 说明
ids String 级联关系Id,多个使用英文逗号隔开
响应数据
属性名 类型 说明
code 整型 响应编码.
message 字符串 响应消息.
visible 布尔型 是否可见, true / false .
data 数组 业务对象.
data.name 字符串 级联关系名称.
data.id 整型 级联关系ID.
data.supperFieldId 整型 上级字段ID.
data.supperFieldName 字符串 上级字段名称.
data.subFieldId 整型 下级字段ID.
data.subFieldName 字符串 下级字段name.
data.objectId 整型 级联关系对应的对象ID.
data.relationList 数组 级联关系.
data.relationList[].supperId 整型 上级字段选项ID.
data.relationList[].subIdList[] 数组 下级字段选项ID列表.
请求示例
$ curl 'https://servicego.udesk.cn/api/v1/cascadeFields/3?email=admin@udesk.cn&timestamp=1496631984&sign=ef506d04ef74e1031f91025494244e88f3559b7&cascadeId=3&customObjectId=15 -i -H 'Content-Type: application/json' -H 'Accept: application/json'
响应示例
{
    "code": 200,
    "message": "OK",
    "visible": false,
    "data": [
        {
            "name": "级联关系",
            "supperFieldId": 428,
            "supperFieldName": "级联上级",
            "subFieldId": 429,
            "subFieldName": "下级",
            "objectId": 15,
            "relationList": [
                {
                    "supperId": 2,
                    "subIdList": [
                        2,
                        9,
                        10
                    ]
                },
                {
                    "supperId": 3,
                    "subIdList": [
                        1,
                        2,
                        3,
                        4,
                        5,
                        6,
                        7,
                        8,
                        9,
                        10
                    ]
                },
                {
                    "supperId": 6,
                    "subIdList": [
                        10
                    ]
                }
            ]
        }
    ]
}

新增级联关系

POST /v1/cascadeFields

请求参数
参数 类型 必填 说明
name String 字段关系名称
objectId int 对象id
supperFieldId int 上级字段id
subFieldId int 下级字段id
relationList 数组 字段级联关系数据
relationList[].supperId 整型 上级字段选项ID.
relationList[].subIdList[] 数组 下级字段选项ID列表.
响应数据
属性名 类型 说明
code 整型 响应编码.
message 字符串 响应消息.
visible 布尔型 是否可见, true / false .
请求示例
$ curl 'https://servicego.udesk.cn/api/v1/cascadeFields?email=admin@udesk.cn&timestamp=1496631984&sign=ef506d04ef74e1031f91025494244e88f3559b78' -i -X POST -H 'Content-Type: application/json' -H 'Accept: application/json' -d  '{"name":"省市","supperFieldId":42028,"subFieldId":42029,"relationList":[{"supperId":1,"subIdList":[1]},{"supperId":3,"subIdList":[2,3,4]},{"supperId":4,"subIdList":[8]},{"supperId":5,"subIdList":[6]},{"supperId":6,"subIdList":[7]},{"supperId":8,"subIdList":[5]}],"objectId":"2230"}'
响应示例
{
    "code": 200,
    "message": "OK",
    "visible": false
}

编辑级联关系

PUT /v1/cascadeFields

请求参数
参数 类型 必填 说明
name String 字段关系名称
id int 关系id
supperFieldId int 上级字段id
subFieldId int 下级字段id
relationList 数组 字段级联关系数据
relationList[].supperId 整型 上级字段选项ID.
relationList[].subIdList[] 数组 下级字段选项ID列表.
relationListShow 数组 字段级联关系数据展示
relationListShow[].supperId 整型 上级字段选项ID.
relationListShow[].subIdList[] 数组 下级字段选项ID列表.
响应数据
属性名 类型 说明
code 整型 响应编码.
message 字符串 响应消息.
visible 布尔型 是否可见, true / false .
请求示例
$ curl --location --request PUT 'https://servicego.udesk.cn/v1/cascadeFields?email=1@test.cn&timestamp=1608114461&sign=74cfd90f2e7a62d5cba147719f014d6a94d325a3' --header 'Content-Type: application/json' --data-raw '{"id":33,"name":"llk","supperFieldId":1546,"subFieldId":1547,"fieldRelation":"[{\"supperId\":1,\"subIdList\":[1]},{\"supperId\":2,\"subIdList\":[2,3,4,5]}]","relationList":[{"supperId":1,"subIdList":[1]},{"supperId":2,"subIdList":[2,3,4]}]}'
响应示例
{
    "code": 200,
    "message": "OK",
    "visible": false
}

查询树形字段

GET /v1/field

请求参数
参数 类型 必填 说明
objectApiName String 对象apiname
fieldApiName String 字段apiname
响应数据
属性名 类型 说明
code 整型 响应编码.
message 字符串 响应消息.
visible 布尔型 是否可见, true / false .
data 对象 字段数据.
data.label 字符串 字段label.
data.id 整型 字段ID.
data.customObjectId 整型 对象ID.
data.fieldType 整型 字段类型.
data.optionList 数组 树形字段选项.
data.optionList[].id 整型 选项ID.
data.optionList[].name 字符串 选项值.
data.optionList[].optionPermissionFlag 整型 选项可选权限 0:无显示权限 1:有显示权限.
data.optionList[].parentId 整型 树形字段父节点
data.optionList[].isTag 整型 标签标识
data.optionList[].parentIds 字符串 树形字段上级节点
data.optionList[].color 字符串 颜色
data.optionList[].textColor 字符串 字体颜色
data.optionList[].sort 整型 排序序号
请求示例
$ curl 'https://servicego.udesk.cn/v1/field?email=admin@udesk.cn&timestamp=1608114461&sign=74cfd90f2e7a62d5cba147719f014d6a94d325a3&objectApiName=wanglufeideceshi&fieldApiName=shuxingziduan -i -H 'Content-Type: application/json' -H 'Accept: application/json' 
响应示例
{
    "code": 200,
    "message": "OK",
    "visible": false,
    "data": {
        "id": 1549,
        "customObjectId": 88,
        "label": "树形字段",
        "apiName": "shuxingziduan",
        "fieldType": 34,
        "optionList": [
            {
                "id": 1,
                "name": "客服系统",
                "optionPermissionFlag": 1,
                "parentId": 0,
                "isTag": 0,
                "parentIds": "0",
                "color": "#ffffff",
                "textColor": "#000000",
                "sort": 1
            },
            {
                "id": 2,
                "name": "呼叫中心",
                "optionPermissionFlag": 1,
                "parentId": 1,
                "isTag": 1,
                "parentIds": "0,1",
                "color": "#ffffff",
                "textColor": "#000000",
                "sort": 2
            },
            {
                "id": 3,
                "name": "在线客服",
                "optionPermissionFlag": 1,
                "parentId": 1,
                "isTag": 1,
                "parentIds": "0,1",
                "color": "#ffffff",
                "textColor": "#000000",
                "sort": 3
            },
            {
                "id": 4,
                "name": "工单",
                "optionPermissionFlag": 1,
                "parentId": 1,
                "isTag": 1,
                "parentIds": "0,1",
                "color": "#ffffff",
                "textColor": "#000000",
                "sort": 4
            },
            {
                "id": 5,
                "name": "其他系统",
                "optionPermissionFlag": 1,
                "parentId": 0,
                "isTag": 0,
                "parentIds": "0",
                "color": "#ffffff",
                "textColor": "#000000",
                "sort": 5
            },
            {
                "id": 6,
                "name": "BI系统",
                "optionPermissionFlag": 1,
                "parentId": 5,
                "isTag": 0,
                "parentIds": "0,5",
                "color": "#ffffff",
                "textColor": "#000000",
                "sort": 6
            },
            {
                "id": 7,
                "name": "Insight",
                "optionPermissionFlag": 1,
                "parentId": 6,
                "isTag": 1,
                "parentIds": "0,5,6",
                "color": "#ffffff",
                "textColor": "#000000",
                "sort": 7
            },
            {
                "id": 8,
                "name": "AI系统",
                "optionPermissionFlag": 1,
                "parentId": 5,
                "isTag": 0,
                "parentIds": "0,5",
                "color": "#ffffff",
                "textColor": "#000000",
                "sort": 8
            },
            {
                "id": 9,
                "name": "文本机器人",
                "optionPermissionFlag": 1,
                "parentId": 8,
                "isTag": 1,
                "parentIds": "0,5,8",
                "color": "#ffffff",
                "textColor": "#000000",
                "sort": 9
            },
            {
                "id": 10,
                "name": "语音机器人",
                "optionPermissionFlag": 1,
                "parentId": 8,
                "isTag": 1,
                "parentIds": "0,5,8",
                "color": "#ffffff",
                "textColor": "#000000",
                "sort": 10
            }
        ]
    }
}

修改树形字段

PUT /v1/treeField

请求参数
参数 类型 必填 说明
objectApiName String 对象apiname
fieldApiName String 字段apiname
label 字符串 字段label.
fieldType 整型 字段类型(树形-34).
optionList 数组 树形字段选项.
optionList[].id 整型 选项ID.
optionList[].name 字符串 选项值.
optionList[].optionPermissionFlag 整型 选项可选权限 0:无显示权限 1:有显示权限.
optionList[].parentId 整型 树形字段父节点
optionList[].isTag 整型 标签标识
optionList[].parentIds 字符串 树形字段上级节点
optionList[].color 字符串 颜色
optionList[].textColor 字符串 字体颜色
optionList[].sort 整型 排序序号
响应数据
属性名 类型 说明
code 整型 响应编码.
message 字符串 响应消息.
visible 布尔型 是否可见, true / false .
请求示例
$ curl --location --request PUT 'https://servicego.udesk.cn/v1/treeField?email=1@test.cn&timestamp=1608114461&sign=74cfd90f2e7a62d5cba147719f014d6a94d325a3' --header 'Content-Type: application/json' --data-raw
'{
     "objectApiName":"wanglufeideceshi",
     "label":"树形字段",
     "fieldApiName":"shuxingziduan",
     "fieldType":34,
     "optionList":[
         {
             "id":1,
             "parentId":0,
             "parentIds":"0",
             "name":"客服系统",
             "textColor":"#000000",
             "color":"#ffffff",
             "isTag":0,
             "sort":1
         },
         {
             "id":2,
             "parentId":1,
             "parentIds":"0,1",
             "name":"呼叫中心",
             "textColor":"#000000",
             "color":"#ffffff",
             "isTag":1,
             "sort":2
         },
         {
             "id":3,
             "parentId":1,
             "parentIds":"0,1",
             "name":"在线客服",
             "textColor":"#000000",
             "color":"#ffffff",
             "isTag":1,
             "sort":3
         },
         {
             "id":4,
             "parentId":1,
             "parentIds":"0,1",
             "name":"工单",
             "textColor":"#000000",
             "color":"#ffffff",
             "isTag":1,
             "sort":4
         },
         {
             "id":5,
             "parentId":0,
             "parentIds":"0",
             "name":"其他系统",
             "textColor":"#000000",
             "color":"#ffffff",
             "isTag":0,
             "sort":5
         },
         {
             "id":6,
             "parentId":5,
             "parentIds":"0,5",
             "name":"BI系统",
             "textColor":"#000000",
             "color":"#ffffff",
             "isTag":0,
             "sort":6
         },
         {
             "id":7,
             "parentId":6,
             "parentIds":"0,5,6",
             "name":"Insight",
             "textColor":"#000000",
             "color":"#ffffff",
             "isTag":1,
             "sort":7
         },
         {
             "id":8,
             "parentId":5,
             "parentIds":"0,5",
             "name":"AI系统",
             "textColor":"#000000",
             "color":"#ffffff",
             "isTag":0,
             "sort":8
         },
         {
             "id":9,
             "parentId":8,
             "parentIds":"0,5,8",
             "name":"文本机器人",
             "textColor":"#000000",
             "color":"#ffffff",
             "isTag":1,
             "sort":9
         },
         {
             "id":10,
             "parentId":8,
             "parentIds":"0,5,8",
             "name":"语音机器人",
             "textColor":"#000000",
             "color":"#ffffff",
             "isTag":1,
             "sort":10
         },
         {
             "id":11,
             "parentId":0,
             "parentIds":"0",
             "name":"销售系统",
             "iconUrl":"",
             "textColor":"#000000",
             "color":"#ffffff",
             "isTag":0,
             "sort":11
         }
     ]
 }' 
响应示例
{
    "code": 200,
    "message": "OK",
    "visible": false
}