回调更新自定义字段枚举

用于外部系统回调更新自定义字段。fieldId 必填。单选/多选字段传 description，description 是 JSON 数组字符串；级联字段传 parentId 和 categoryList。若仅传 fieldId 且字段为 API 配置模式，将按字段配置的 API 地址执行全量覆盖更新。

请求参数

名称	类型	必填	描述
appKey	string	是	应用 AppKey
time	int64	是	请求时间戳（秒）
checksum	string	是	请求签名校验和
checksumAlgorithm	int32	否	签名算法：0 - 默认(SHA1)，1 - SHA256

请求体

名称	类型	必填	描述	示例值
fieldId	int64	是	自定义字段 ID	10001
parentId	int64	否	级联字段父级枚举 ID；更新第一级枚举时传 0。非级联字段不需要传。	0
categoryList	object[]	否	级联字段枚举项列表，每项需包含 id 和 name；当 categoryList 或 description 非空时更新传入的枚举项。	[{"id":100001,"name":"华东"},{"id":100002,"name":"华南"}]
└opId	string	否	数据项 ID。单选/多选字段由 description 中的 opId 指定；级联字段不需要传。	high
└id	int64	否	枚举项 ID。级联字段使用真实分类 ID；单选/多选字段查询枚举值时使用从 0 开始的序号。	100001
└name	string	否	枚举项名称	高意向
└children	object[]	否	子枚举项，仅级联字段可能返回	[{"id":100101,"name":"上海","disabled":false}]
└opId	string	否	数据项 ID。单选/多选字段由 description 中的 opId 指定；级联字段不需要传。	high
└id	int64	否	枚举项 ID。级联字段使用真实分类 ID；单选/多选字段查询枚举值时使用从 0 开始的序号。	100001
└name	string	否	枚举项名称	高意向
└children	object[]	否	子枚举项，仅级联字段可能返回	[{"id":100101,"name":"上海","disabled":false}]
└disabled	boolean	否	是否禁用；未返回时可按 false 处理。	false
└disabled	boolean	否	是否禁用；未返回时可按 false 处理。	false
description	string	否	单选/多选字段枚举定义的 JSON 数组字符串。数组元素格式为 {"text":"显示文案","opId":"数据项ID"}；如果任一元素有 opId，则所有元素 opId 都必须非空、不能重复，长度不能超过配置上限（默认 60）。	[{"text":"高意向","opId":"high"},{"text":"低意向","opId":"low"}]

返回参数

名称	类型	描述	示例值
code	int32	状态码，200 表示成功	200
data	object	自定义字段详情	{"id":10001,"name":"客户意向","type":1,"description":"[{\"text\":\"高意向\",\"opId\":\"high\"}]","updateTime":1739347200000,"status":0}
└id	int64	自定义字段 ID	10001
└name	string	自定义字段名称	客户意向
└type	int32	字段类型：1-单选，2-多选，6-级联。/queryCustomField 当前只返回这三类字段。	1
└description	string	字段描述。单选/多选字段通常是枚举项 JSON 数组字符串，元素包含 text 和可选 opId；级联字段可能为空。	[{"text":"高意向","opId":"high"},{"text":"低意向","opId":"low"}]
└updateTime	int64	字段更新时间，毫秒时间戳	1739347200000
└status	int32	字段状态：0-正常，1-删除	0
└categoryItem	object[]	级联字段枚举树；仅级联字段可能返回	[{"id":100001,"name":"华东","disabled":false,"children":[{"id":100101,"name":"上海","disabled":false}]}]
└opId	string	数据项 ID。单选/多选字段由 description 中的 opId 指定；级联字段不需要传。	high
└id	int64	枚举项 ID。级联字段使用真实分类 ID；单选/多选字段查询枚举值时使用从 0 开始的序号。	100001
└name	string	枚举项名称	高意向
└children	object[]	子枚举项，仅级联字段可能返回	[{"id":100101,"name":"上海","disabled":false}]
└opId	string	数据项 ID。单选/多选字段由 description 中的 opId 指定；级联字段不需要传。	high
└id	int64	枚举项 ID。级联字段使用真实分类 ID；单选/多选字段查询枚举值时使用从 0 开始的序号。	100001
└name	string	枚举项名称	高意向
└children	object[]	子枚举项，仅级联字段可能返回	[{"id":100101,"name":"上海","disabled":false}]
└disabled	boolean	是否禁用；未返回时可按 false 处理。	false
└disabled	boolean	是否禁用；未返回时可按 false 处理。	false

错误码

状态码	描述
14001	AppKey 不存在
14002	checksum 校验失败
14003	time 缺失，或请求时间戳与服务器时间误差超过 10 分钟
14004	请求体不是合法 JSON 对象；或 fieldId 缺失
14500	服务内部异常；字段不存在、请求字段类型不符合要求或服务处理失败
19100	字段同步中；字段为手动配置模式不允许回调更新；或其它自定义字段通用业务错误
19104	description 中存在 opId 时，某个数据项 opId 为空或长度超过配置上限
19106	description 中存在重复 opId

postEndpoint

/openapi/customfield/callback

curl -X POST "https://qiyukf.com/openapi/customfield/callback?appKey=9f1d7c2b8a6e4d3c&time=1739347200&checksum=a1b2c3d4e5f607182930abcdefabcdef&checksumAlgorithm=0" \  -H "Content-Type: application/json" \  -d '{    "fieldId": 10001  }'

{
  "code": 200,
  "data": {
    "id": 10001,
    "name": "客户意向",
    "type": 1,
    "description": "[{\"text\":\"高意向\",\"opId\":\"high\"}]",
    "updateTime": 1739347200000,
    "status": 0
  }
}

{
  "code": 14001,
  "message": "AppKey 不存在"
}

{
  "code": 14002,
  "message": "checksum 校验失败"
}

{
  "code": 14003,
  "message": "time 缺失，或请求时间戳与服务器时间误差超过 10 分钟"
}

{
  "code": 14004,
  "message": "请求体不是合法 JSON 对象；或 fieldId 缺失"
}

{
  "code": 14500,
  "message": "服务内部异常；字段不存在、请求字段类型不符合要求或服务处理失败"
}

{
  "code": 19100,
  "message": "字段同步中；字段为手动配置模式不允许回调更新；或其它自定义字段通用业务错误"
}

{
  "code": 19104,
  "message": "description 中存在 opId 时，某个数据项 opId 为空或长度超过配置上限"
}

{
  "code": 19106,
  "message": "description 中存在重复 opId"
}