金蝶云星空供应商接口字段手册权威教程:从查询到转正解禁全链路实战
这个接口解决什么问题
在风险供应商管理场景中,供应商被标记为「风险」后存在 60–92 天的转正窗口,逾期会被自动禁用。业务需要把金蝶云星空的供应商主数据与钉钉审批流打通:窗口期内通过钉钉机器人发送转正提醒,审批通过后再回流金蝶执行转正与解禁。本文将围绕这一闭环,把金蝶供应商查询/写入接口与钉钉审批流详情接口的实战要点系统化。
接口能力总览
认证方式:金蝶云星空走 WebAPI 授权(Login 后携带 Token 调用 Save/ExecuteOperation);钉钉审批与机器人走开放平台 AccessToken(企业内部应用 AppKey/AppSecret 换取)。
请求/响应结构:金蝶侧 BD_Supplier 的查询接口入参包含 FormId、FilterString、FieldKeys、Limit 等;批量写入用 batchSave(JSONArray 模型集合)。钉钉侧 topapi/processinstance/get 入参为 process_instance_id,出参含表单 value 列表;oToMessages/batchSend 入参为 robotCode + userIds + msgKey + msgParam。
分页/增量模式:金蝶通过 FilterString 限定时间窗与组织实现增量;钉钉上游按 start_time 增量拉取 processInstanceId 列表,本策略按 process_instance_id_strategy 逐条拉取详情,天然支持幂等去重。
典型字段映射
| 字段名 | 类型 | 含义 | 实战注意事项 |
|---|---|---|---|
| FNumber / value | string | 供应商编码(源端与目标端共有语义键) | 钉钉审批表单 value 与金蝶 FNumber 一一对应,作为联查 FSupplierId 的依据 |
| FSupplierId | string | 金蝶供应商内码 | 写入/解禁操作的真正定位符,必须通过 _findCollection 联查得到 |
| F_PUROrgId | string | 下单组织 | 用于映射钉钉接收人 userIds,case-when 分支需在配置层维护 |
| FCreateDate | date | 风险供应商创建日期 | 转正窗口计算基准,做 DATEDIFF 算剩余天数 |
| FAuditDate | date | 审核日期 | 提醒正文展示字段 |
| FUseOrgId.fnumber | string | 使用组织 | FilterString 中硬编码(如 'T00'),实施时按实际组织替换 |
| FSupplierClassify.fnumber | string | 供应商分类 | 风险供应商固定值 '03',作为筛选必备条件 |
| FDocumentStatus | string | 单据状态 | 'C' 表示已审核,过滤未审核单据 |
| FForbidStatus | string | 禁用状态 | 'A' 表示未禁用 |
| FormId | string | 业务对象表单 ID | 供应商固定为 'BD_Supplier' |
| Operation | string | 操作类型 | 转正用 'batchSave',解禁用 'Enable' |
| IsVerifyBaseDataField | bool | 是否校验基础资料 | 建议 true,避免脏数据落库 |
| IsAutoSubmitAndAudit | bool | 是否自动提交并审核 | 转正建议 false,由人工触发审核 |
| robotCode | string | 钉钉机器人编码 | 配置层维护,不可硬编码到方案 |
| msgKey | string | 消息模板键 | Markdown 模板固定为 'sampleMarkdown' |
| process_instance_id | string | 钉钉审批实例 ID | 上游策略预拉取,本策略作为入参引用 |
在轻易云上如何配置
在轻易云数据集成平台里,金蝶云星空走「金蝶云星空适配器」,钉钉走「钉钉开放平台适配器」。金蝶侧:适配器封装了 Login 与 Token 维护,字段映射器里把钉钉审批 value 拖入「供应商集线器联查」节点,自动生成 _findCollection 表达式;批量写入选择 BD_Supplier 的 batchSave 模型,平台会把 FormId、IsVerifyBaseDataField 等常量自动补齐。钉钉侧:适配器内置 topapi/processinstance/get 与 oToMessages/batchSend 两个动作,审批流详情可一键启用「按 process_instance_id 策略逐条拉取」;提醒消息的 msgParam 用 CONCAT 表达式拼装,平台字段映射器会提示 FCreateDate、FAuditDate 的日期格式化函数。调度:轻易云的调度器支持源端/目标端分别配置 crontab,自动处理依赖关系与上下游顺序。
跨方案实战要点
- 编码与内码必须解耦:钉钉表单只承载业务编码,真正写入金蝶靠 FSupplierId 联查,不要试图把编码直接当主键写。
- 窗口期分两段提醒:60–80 天每周一提醒一次、80–92 天每天提醒一次,频次差异既能降低打扰,又能在末期避免漏转正。
- 转正与解禁严格分步:batchSave 转正后必须留出 3 分钟以上间隔再 Enable 解禁,金蝶内部状态机不允许并发。
- 集线器联查是关键枢纽:供应商编码→FSupplierId 的查询集线器是多个策略共享的依赖,务必保证集线器数据每日刷新。
- 增量靠时间戳 + 业务状态双过滤:金蝶侧 FilterString 同时按 FCreateDate 与 FDocumentStatus='C'、FForbidStatus='A' 过滤,避免重复推送。
- 审批实例按 ID 幂等:策略 1 与策略 4 共用同一上游 processInstanceId 列表,平台按 ID 去重,同一审批不会触发两次转正。
踩坑复盘
- 供应商编码在金蝶查不到:
_findCollection返回空,转正与解禁都会失败。稳妥的做法是配置层补一条「单次失败 >5 条即告警」的阈值,人工介入核查。 - 钉钉限流 429:批量拉取审批详情容易触发。指数退避 30s/60s/120s 不够,建议把 429 的重试次数单独提到 5 次、间隔 60s。
- 转正窗口边界误判:
DATEDIFF(date(now()), date(FCreateDate))在跨天调度时容易把刚满 92 天的也拉进来,需要 FilterString 严格用「60–79 天前」「80–91 天前」分段,不要依赖表达式端过滤。 - 机器人收不到消息:userIds 列表为空是高频原因,组织→用户 ID 映射表必须随组织调整同步更新,配置层要加版本号校验。
- 批量写入 IsVerifyBaseDataField=false:有人图省事关掉校验,导致脏 FSupplierId 落库后无法解禁,反而要花更多时间清理,这里容易翻车。
何时选用
适用于「带审批流的主数据生命周期管理」场景,尤其是风险供应商、试用客户、临时账号等有时效门槛的业务对象。若审批完全在金蝶内部完成,无需引入钉钉;若只是单向提醒,直接用金蝶工作流消息即可,不必搭建双侧集成。