表单字段回填
外部数据源介绍
你在什么情况下能用到？
可以帮你解决什么问题？
使用指南
事前准备
配置API
1.
2. 填入对接项名称，名称应保持可读，并点击编辑按钮
3. 第二步执行完成后，将会弹出数据源配置：
3.1 设置触发时机
| 填入项 | 作用 | 详情描述 |
|---|---|---|
| 触发时机 | 指定在何时调用外部，当触发时机满足配置时，才会调用API | - 表单字段变化时：监听当前表单中某些字段，当字段的内容发生变化时 - 鼠标点击字段时：指定字段被点击时 |
| 监听字段 | 和触发时机配合使用 | 举个例子，如下配置表示：当“合同名称”这个字段发生变化时，就去调用API |
3.2 数据源获取
| 填入项 | 作用 | 详情描述 |
|---|---|---|
| 请选择 | 指定HTTP请求方法 | 目前支持HTTP常用的请求方法 |
| 请输入Url | 指定API的请求地址 | - |
| Token | Token主要是为了确保数据安全，防止接口被恶意调用 | token会以名为“token”的header传输 |
| 动态Token | 允许调用一个API，从而获取Token | 详见技术文档一节 |
| 请求头 | 这部分请求会放在HTTP header中传输 | - 入参名称：待传递的header名称 - 请选择：支持如下选项 - 表单字段：从表单字段中取值 - 固定值：你可以填写一个任意的值 - 表达式：可以编写表达式。目前表达式只是初步支持，功能不够完善，不建议使用，近期会增强 - “选择表单字段”： - 当选择“表单字段”时，可以将表单字段绑定到参数上； - 当选择“固定值”时，可将用户填写的值绑定到参数上； - 当选择“表达式”时，可将表达式解析后的值绑定到参数上 例如： 那么，调用API时，传输的header如下： param1=当前合同名称的值 param2=123 |
| 请求体 | 这部分请求会序列化成JSON结构体，放在HTTP请求体中传输 | - 入参名称：待传递的请求体 名称 - 请选择：支持如下选项 - 表单字段：从表单字段中取值 - 固定值：你可以填写一个任意的值 - 表达式：可以编写表达式。目前表达式只是初步支持，功能不够完善，不建议使用，近期会增强 - “选择表单字段”： - 当选择“表单字段”时，可以将表单字段绑定到参数上； - 当选择“固定值”时，可将用户填写的值绑定到参数上； - 当选择“表达式”时，可将表达式解析后的值绑定到参数上 下面举几个例子： - 对于普通的字段类型，例如： 那么在调用API时，将传输如下的请求体： { "param1": "当前合同名称的值", "param2": 3 } - 对于人员、部门类型，例如： 那么在调用API时，将传输如下的请求体： { "employeeExtraInfo": [ { "openId": "智书openId", "userId": "智书userId", "employeeId": "员工id", "employeeCode": "员工编码", "name": "员工名称" } ], "partmentExtraInfo": [ { "departmentId": "部门id", "openDepartmentId": "部门openId", "realDepartmentId": "部门department_id，示例值：D096", "code": "部门编码", "name": "部门名称" } ] } 目前审批人回填功能还未支持上述的人员、部门请求体的格式构造，请求格式如下： { "partment": "员工的employeeId" } - 对于交易方字段、我方字段，例如： 那么在调用API时，将传输如下的请求体： { "legalEntity": [ { "legalEntityName": "我方-名称", "legalEntityCode": "我方-编码" } ], "tradingParty": [ { "tradingPartyCode": "交易方-编码", "partyName": "交易方-名称" } ] } 目前审批人回填功能还未支持上述交易方字段、我方字段的格式构造，请求格式如下： { "legalEntity": "我方-编码", "tradingParty": "交易方-编码" } - 对于相关单据，例如： 那么在调用API时，将传输如下的请求体： { "param": [ { "serialId": "10001" } ] } |
| Query参数 | 这部分会作为HTTP Query String传输 | 配置方式类似请求头、请求体 例如： 那么，传输的参数如下： ?param1=合同名称的值¶m2=123 |
| 路径参数 | 这部分会作为HTTP路径参数传输 | 路径参数用于应对Url中路径存在占位符的场景。 例如： 如图，一些Url是动态的，{{path}}需要动态取值。路径参数可解决问题。 - Url中的占位符使用{{名称}}的形式占位，例如{{path}} - 路径参数名称需要和{{}}中的内容相同，例如path 这样，在请求时，将会构造如下地址： http://www.foo.bar/some-path/合同名称的值 |
3.3 数据源回填
这块比较简单，举个例子，API的响应如下：
{
"param1": "aaaaa",
"param2": "bbbbb"
}这表示将“aaaaa”绑定到字段收支类型上；“bbbbb”绑定到字段计价方式上。
4.
数据源配置完成后，用户可进行模拟，调用API，从而验证接口配置是否正确。
如果正确，点击保存按钮即可添加该数据源。
技术文档
请求
请求头 - 静态token认证
如图配置，会传递一个名为token，值为 a-test-token 的header。
TIPS：发送请求时，Token的默认名称为token，如果希望以其他名称发送，请发起oncall，并联系我们的技术同学修改
请求头 - 动态token认证
API调用过程中会获取上面的 URL (https://example.com/getToken)来获取token，并将从接口获得的值，放到header中传递。
暂时无法在飞书文档外展示此内容
TIPS：
请求体
那么在调用API时，将传输如下的请求体：
{
"param1": "当前合同名称的值",
"param2": 3
}{
"employeeExtraInfo": [
{
"openId": "智书openId",
"userId": "智书userId",
"employeeId": "员工id",
"employeeCode": "员工编码",
"name": "员工名称"
}
],
"partmentExtraInfo": [
{
"departmentId": "部门id",
"openDepartmentId": "部门openId",
"realDepartmentId": "部门department_id，示例值：D096",
"code": "部门编码",
"name": "部门名称"
}
]
}{
"legalEntity": [
{
"legalEntityName": "我方-名称",
"legalEntityCode": "我方-编码"
}
],
"tradingParty": [
{
"tradingPartyCode": "交易方-编码",
"partyName": "交易方-名称"
}
]
}{
"param": [
{
"serialId": "10001"
}
]
}默认传递字段
| 字段名称 | 含义 | 传输位置 |
|---|---|---|
| contractId | 合同id | 请求体 |
| contractNumber | 合同编号 | 请求体 |
| belongedDepartmentId | 合同所属部门id | 请求体 |
| applier | 申请人id | 请求体 |
| submitterUserId | 提交人id | - 请求体 - query参数 - 路径参数 - header参数 |
| submitterEmployeeCode | 提交人工号 | - 请求体 - query参数 - 路径参数 - header参数 |
响应
响应字段类型
WARNING
响应结果必须符合示例要求，否则前端组件将无法渲染。
响应字段类型说明
| 字段类型 | 值类型 | 示例 | 说明 |
|---|---|---|---|
| 数字字段 | number | 123456 | 整数 |
| 单行/多行文本字段 | string | "文本值" | 字符串 |
| 日期区间字段 | array | ["2021-10-13","2021-10-22"] | 字符串数组 |
| 日期字段 | string | 2021-10-01 | 字符串 |
| 金额 | json | {"amount": "33545", "currency": 1} amount为字符串，currency为整数 | 常见币种类型国际编码： CNY(1, "人民币元", "CNY", "¥"), USD(2, "美元", "USD", ""), THB(7, "泰铢", "THB", "฿"), HKD(10, "港币", "HKD", "HK$"), KRW(8,"韩元","KRW","₩") |
| 链接 | object | { "url": "https://www.bytedance.com/", "title": "字节跳动" } url为字符串，title为字符串 | - |
| 单选/多选字段 | object/array | Case 1仅回填选项： [ { "label": "自定义1", "labelCn":"自定义1 - 中文", "labelEn":"自定义1 - 英文", "labelJp":"自定义1 - 日文", "value": "v1" }, { "label": "自定义2", "labelCn":"自定义2 - 中文", "labelEn":"自定义2 - 英文", "labelJp":"自定义2 - 日文", "value": "v2" } ] [ { "label": "自定义1", "value": "v1" }, { "label": "自定义2", "value": "v2" }] Case 2回填选项 + 选中默认值： - 单选 { "value": "v2", //选中的默认值 "options": [ { "label": "自定义1", "value": "v1" // value必须为字符串 }, { "label": "自定义2", "value": "v2" }] } - 多选 { "value": ["v2"], //选中的默认值 "options": [ { "label": "自定义1", "value": "v1" // value必须为字符串 }, { "label": "自定义2", "value": "v2" }] } - value类型是字符串 - value为空则清空用户选中值 - 如果选中的默认值在新列表中不存在则清空用户选中的值 - 列表不支持回填options | - |
| 明细字段 | object[] | [{ "numberType": 123456, "textType": "asdfads", "stringType": "第一行", "dateType": [ "2021-10-13", "2021-10-22" ], "singleDateType": "2021-10-01", "amountType": { "amount": "33545", "currency": 4 }, "selectType": "1" }] 数组中的值参考其他类型的格式 | - |
| 树形字段 | object/array | [{ "label": "人力成本", "value": "MDBS00000005", "children": [ { "label": "人力成本 - 保险", "value": "MDBS00000196", "children": null }, { "label": "人力成本 - 补偿金", "value": "MDBS00000197", "children": null } ] }, { "label": "市场费", "value": "MDBS00000181", "children": [ { "label": "品牌市场费", "value": "MDBS00000003", "children": null }, { "label": "拉新市场费", "value": "MDBS00000004", "children": null } ] }] 树形中的所有字段的value不能相同，否则组件将无法渲染 | - |
| 对方/我方字段 | object/array | [ { "type": "trading_party", "code": "V00225001" }, { "type": "legal_entity", "code": "L00178002" } ] type - 字段类型： - trading_party：对方字段类型 - legal_entity：我方字段类型 code - 主数据编码 | - |
| 人员类型/人员多选类型 | object/array | [ { "type": "userId", "userId": "12345678" }, { "type": "employeeId", "employeeId": "87654321" }, { "type": "larkId", "larkId":"56781234" } ] - type: Id类型 - userId、employeeId、larkId: Id值 | - |
| 审批人回填 | array | { "userId":["1111","2222"] } 对象，userId字段是字符串数组 | - |
| 付款计划 / 收款计划 - 付款时间 / 收款时间 | object | { "reminderDate": "2023-07-31", "reminderDateTypeCode": 2, "intervalDays": 1, "intervalDayTypeCode": 1 } reminderDateTypeCode： - 0 - 固定时间，1 - 不固定时间，2 - 履约条件完成后， 默认值为0，固定时间 reminderDate： - 付款时间类型=固定时间（reminderDateTypeCode = 0），必填 - 付款时间类型=不固定时间、履约条件完成后（reminderDateTypeCode = 1，2），不可填，如果传入则自动清空 intervalDayTypeCode： - 间隔日的天数单位：1 - 工作日， 2 - 自然日 - 付款时间类型=履约条件完成后（payment_date_type_code = 2），必填 - 付款时间类型=固定时间、不固定时间（payment_date_type_code = 0，1），不可填，如果传入则自动清空 intervalDays： - 履约条件完成到付款日之间的间隔时间，单位为 (自然日/工作日)，单位由interval_day_type_code字段决定 - 付款时间类型=履约条件完成后（payment_date_type_code = 2），必填 - 付款时间类型=固定时间、不固定时间（payment_date_type_code = 0，1），不可填，如果传入则自动清空 | - |
| 履约类型 | number | 0或1 - 0 - 需付款，1 - 无需付款 | - |
| 履约事项 | string | "文本值" | 字符串 |
| 有无发票 | bool | true或false - true - 有发票，false - 无发票 | - |
| 付款金额 / 收款金额 | json | {"amount": "33545", "currency": 1} 同上述金额字段。当履约类型为无需付款时，该字段不可填 | - |
| 付款说明 / 收款说明 | string | "文本值" | 字符串 |
| 银行账户 | number | 123456 | 整数 |
| 付款对象 / 收款对象 | 不支持回填 | - | |
| 部门 | 不支持回填 | - |
示例
错误码
| 错误码 | 说明 |
|---|---|
| 0 | 正确 |
| 110345 | token校验失败 |
| 110343 | 数据不存在 |
| 110342 | 系统异常 |
修改于 2026-05-28 02:33:22