乐檬到钉钉基础资料同步接口字段手册权威教程
这个接口解决什么问题
在供应链与 OA 协同场景中,业务侧的供应商主数据与供应商结算单往往分散在业务系统与审批系统两侧。我们要把乐檬里的供应商档案和结算单据,按规则同步到钉钉的 OA 审批与导出单流程,统一审批入口并沉淀审计轨迹,避免线下重复录入与口径不一致。
接口能力总览
认证方式:源端乐檬采用 API 密钥/账套凭证,目标端钉钉采用应用 AccessToken(通过 AppKey/AppSecret 换取),凭证统一由密钥管理服务托管,不在脚本里硬编码。
请求/响应结构:源端乐檬返回分页 JSON 列表(含 body 对象,字段如 supplier_num、supplier_bank、supplier_bank_account 等);目标端钉钉接收 processInstances 或 OA 审批参数,核心负载为 form_component_values 数组,每项 {name, value} 对应一个表单控件。
分页/增量模式:乐檬侧通过 page_no、page_size 分页,通过 date_type(审核时间/制单时间)+date_from/date_to 做时间窗口增量;供应商主数据可按 last_edit_time 或 supplier_num 自增列增量。平台侧维护 LAST_SYNC_TIME,成功后滚动更新。
典型字段映射
| 字段名 | 类型 | 含义 | 实战注意事项 |
|---|---|---|---|
| supplier_settlement_no / supplier_num | 字符串 | 结算单号/供应商编码 | 主键,空值需脚本兜底(如 date('Ymd').'00001') |
| supplier_name / supplier_bank_account_name | 字符串 | 供应商名称 | 乐檬侧可能以银行户名为主,实施时按 API 实测为准 |
| settlement_date | 日期 | 结算日期 | 注意时区,统一按业务日 |
| settlement_total_money | 数值 | 结算总金额 | 也可备选 settlement_payment_money,优先取总额 |
| settlement_bank / supplier_bank | 字符串 | 开户行/银行名称 | 经脚本统一为「XX银行」格式 |
| settlement_bank_account / supplier_bank_account | 字符串 | 银行账号 | 敏感字段,建议传输加密、存储脱敏 |
| 大额行号类字段 | 字符串 | 大额行号 | 值为字符串 'null' 时必须置空,否则下游报错 |
| 是否农行 | 布尔 | 是否农业银行 | 通过银行名称包含「农业银行」判定 |
| 银行类别 | 字符串 | 规范化银行名 | 脚本:strstr(value,'银行',true).'银行' |
| processCode / process_code | 常量 | 钉钉审批流程 ID | 由配置或环境变量注入,不硬编码 |
| originatorUserId / deptId | 常量 | 发起人/部门 ID | 根部门传 -1,便于多门店参数化 |
| formComponentValues | 数组 | 表单控件值列表 | 由源端单条记录构建为 [{name, value}, ...] |
在轻易云上如何配置
在轻易云数据集成平台里,这个接口的调用通常采用「源系统适配器 + 目标系统适配器」的双适配器模式:源端用乐檬适配器配置增量时间窗与分页,目标端用钉钉审批适配器配置 processCode 与 form_component_values 模板。轻易云的字段映射器会自动把源字段按控件名落到目标数组;AfterTargetGenerate 钩子用于银行名称规范化、大额行号空值处理、是否农行判定等后处理。凭证、流程 ID、发起人 ID 通过轻易云的「环境变量 / 配置中心」注入,避免硬编码;调度中心可直接设置每 15 分钟增量、凌晨全量,并启用错峰队列。
跨方案实战要点
- 先供应商、后结算单:供应商是基础资料,先建立钉钉侧的供应商档案,结算单再按编码关联,避免审批单找不到对应供应商。
- 错峰 2–5 分钟:两条策略无强依赖,但同时并发会触发钉钉限流,稳妥的做法是错峰触发。
- 银行字段是重灾区:开户行、支行、银行类别三字段在不同客户里命名差异大(
supplier_bank/account_bank等),实施时必须按 API 实测确认路径,并统一脚本规范化。 - 大额行号
'null'字符串:乐檬侧常把空值返回为字符串'null',直接传给钉钉会触发校验,必须前置置空。 - 幂等写入:目标端按
supplier_settlement_no、supplier_num主键去重,避免重跑产生重复审批实例。 - 多门店参数化:
branch_num走参数,适配连锁零售的多门店场景。
踩坑复盘
- 银行名称脚本崩了导致整批失败:单条脚本异常会中断循环。稳妥的做法是 try/catch 隔离,失败回退原始值并记录日志,不让一条脏数据拖垮整批。
- 钉钉 429 限流:并发高时频繁触发。配置等待 60s、最多 5 次的重试,并启用轻易云的分流队列。
processCode写死:不同门店、不同业务线共用一个流程会导致数据串台。必须按业务线配置多套processCode,由配置中心注入。- 增量窗口过窄漏数据:按制单时间增量,若上游回填或补单会漏。建议主用审核时间,辅以
last_edit_time兜底。 - 敏感字段明文落库:银行账号、开户名未脱敏。传输层 HTTPS + 存储层脱敏是底线,轻易云的字段级脱敏规则可直接开启。
何时选用
适用于「业务系统为主、OA 审批为流程入口」的中大型连锁与供应链企业:供应商主数据需在 OA 中审批留痕、结算单需走钉钉导出单流程的场景。若企业 OA 已统一为其他平台,或无需将基础资料同步进审批流,本方案不适用,可改为单向的数据下发或 BI 取数。