钉钉与金蝶云星空审批报销自动化接入操作指南

一、环境准备

1.1 系统权限配置

• 钉钉端：需具备企业管理员权限，进入钉钉开放平台（open.dingtalk.com）创建企业内部应用，获取 AppKey 和 AppSecret。
• 金蝶端：需金蝶云星空管理员账号，确保财务模块已启用付款单功能，并获取数据中心ID、用户账号及API授权密钥。
• 轻易云平台：注册企业账号并完成实名认证，确保具备创建集成方案的权限。

1.2 网络环境检查

• 确认钉钉服务器域名 oapi.dingtalk.com 和 api.dingtalk.com 可访问。
• 确认金蝶云星空服务地址可访问，建议使用HTTPS协议确保传输安全。
• 在轻易云平台完成网络连通性测试（平台提供内置诊断工具）。

二、配置说明

2.1 创建集成方案

在轻易云平台创建集成方案，选择钉钉作为数据源，配置 获取审批实例详情 接口；绑定金蝶云星空目标系统，设置 新增付款单 接口；完成字段映射与转换规则配置。(https://www.qeasy.cloud/dataintegration/31121319-d589-400b-aa50-374335250b90)

1. 进入「集成方案」→「新建方案」→ 命名方案（如：钉钉报销-金蝶付款单对接）。
2. 源系统选择「钉钉」，连接器类型选择「钉钉审批实例查询」。
3. 目标系统选择「金蝶云星空」，连接器类型选择「金蝶付款单写入」。

2.2 钉钉端API配置

• 接口路径：topapi/processinstance/get
• 请求方法：POST
• 关键参数：
  • process_code：审批流唯一码（在钉钉后台「审批」→「流程设计」中获取，格式如 PROC-A37CB912-0424-4584-AB8B-70F8D17DDFBC）
  • start_time / end_time：时间范围（毫秒时间戳，建议配置为最近96小时）
  • size：分页大小（建议设置为20条/次，避免触发限流）

轻易云平台支持智能字段映射，自动识别相似字段匹配准确率达92%，同时支持增量同步和断点续传机制。(https://www.qliang.cloud/dataintegration/3facb0d4-8ba2-48fe-a956-7740a29f3051)

2.3 金蝶端API配置

• 接口路径：batchSave
• 请求方法：POST
• 业务对象表单Id：AP_PAYBILL（付款单）
• 执行操作：BatchSave
• 自动提交与审核：设置为 true 实现全自动处理

2.4 核心字段映射配置

智能字段映射支持自动识别支付宝/银行卡账户类型，通过公式 CASE LOCATE('ALIPAY_ACCOUNT','{{收款账户.identityType}}') WHEN 0 THEN '{{收款账户.cardNo}}' ELSE '{{收款账户.logonId}}' END 实现分流处理。(https://www.qliang.cloud/dataintegration/cfdf6543-f55a-40d1-bb6a-6b8472156cbd)

三、代码示例

3.1 钉钉数据获取配置（JSON元数据）

{
  "api": "topapi/processinstance/get",
  "effect": "QUERY",
  "method": "POST",
  "number": "number",
  "id": "id",
  "name": "number",
  "idCheck": true,
  "autoFillResponse": true,
  "request": {
    "process_code": "PROC-A37CB912-0424-4584-AB8B-70F8D17DDFBC",
    "start_time": "{{LAST_96HOURS_TIMESTAMP}}",
    "end_time": "{{CURRENT_TIMESTAMP}}",
    "size": 20,
    "cursor": "{{PAGINATION_CURSOR}}"
  }
}

3.2 金蝶数据写入配置（JSON元数据）

{
  "api": "batchSave",
  "method": "POST",
  "operation": {
    "method": "batchArraySave",
    "rows": 1,
    "rowsKey": "array"
  },
  "request": {
    "Creator": "Administrator",
    "NeedUpDateFields": [],
    "Model": {
      "FBillNo": "{{extend.business_id}}",
      "FDATE": "{{费用发生_DATE_FORMAT}}",
      "FPAYORGID": "{{费用归属组织_FNumber}}",
      "FPAYBILLENTRY": [
        {
          "FPAYTOTALAMOUNTFOR": "{{报销金额}}",
          "FOPPOSITEBANKACCOUNT": "{{收款账户}}",
          "FOPPOSITEBANKACCOUNTNAME": "{{收款人姓名}}",
          "FOPPOSITEBANKNAME": "{{开户行}}"
        }
      ],
      "FREMARK": "{{报销明细_拼接}}",
      "IsAutoSubmitAndAudit": true
    }
  }
}

3.3 数据转换脚本示例（轻易云脚本引擎）

// 收款账户智能识别处理
function transformPaymentAccount(rawData) {
    const identityType = rawData.identityType || '';
    const cardNo = rawData.cardNo || '';
    const logonId = rawData.logonId || '';
    
    // 判断是否支付宝账户
    if (identityType.includes('ALIPAY_ACCOUNT')) {
        return logonId;  // 返回支付宝账号
    } else {
        return cardNo;   // 返回银行卡号
    }
}

// 报销明细多字段拼接
function mergeExpenseDetails(items) {
    return items.map(item => {
        return `${item.expense_type}: ${item.amount}元 (${item.remark})`;
    }).join('; ');
}

四、调试方法

4.1 单步调试流程

1. 接口连通性测试：在轻易云平台「调试工具」中，单独测试钉钉接口返回数据结构，确认字段完整性。
2. 数据模拟测试：使用平台「数据模拟」功能，构造典型报销单数据（含支付宝/银行卡两种收款方式），验证转换逻辑正确性。
3. 端到端联调：触发真实钉钉审批流程，在轻易云「监控中心」查看全链路数据流转状态。

4.2 关键验证点

• 金额精度验证：确保钉钉端输入 1000.50 元，金蝶端准确接收 1000.50 而非 1000.5 或 100050。
• 日期格式验证：钉钉返回毫秒时间戳 1658800800000，经转换后金蝶接收 2022-07-26 格式。
• 特殊字符处理：验证报销明细中包含换行符、引号等特殊字符时的转义处理。

轻易云平台提供实时监控与告警系统，实时跟踪每个数据集成任务的状态和性能，一旦发现异常情况立即发出告警并启动错误重试机制。(https://modelers.csdn.net/680ee32ba5baf817cf4979cb.html)

五、常见问题

5.1 数据获取类问题

• 排查步骤：
  1. 检查 process_code 是否正确（需与钉钉后台审批流程编码完全一致）
  2. 确认时间范围参数是否包含已完成的审批实例（注意时区转换，钉钉使用毫秒时间戳）
  3. 验证钉钉应用是否具备「审批实例读取」权限（需在钉钉后台「权限管理」中开启）

• 解决方案：在轻易云平台配置分页策略，设置合理的 size 值（建议20-50条/次），启用「断点续传」功能确保网络中断后自动恢复。

5.2 数据写入类问题

• 解决方案：在轻易云字段映射中，对 FBillNo 字段添加前缀或后缀规则，如 DD{{extend.business_id}}，避免与手工录入单据冲突。

• 检查点：确认金蝶端 IsAutoSubmitAndAudit 参数设置为 true，且金蝶用户账号具备付款单审核权限。

5.3 字段映射类问题

• 解决方案：在轻易云平台「数据映射表」功能中，上传钉钉部门ID与金蝶组织编码的对应关系表，实现自动转换。

• 原因：金蝶部分金额字段要求「分」为单位，而钉钉传递「元」。
• 修复：在轻易云配置数值转换公式 {{报销金额}} * 100 或 {{报销金额}} / 100 根据实际接口要求调整。

5.4 性能与稳定性问题

• 优化建议：
  • 在轻易云平台启用「集群模式」，利用平台单节点60MB/S的处理能力扩展至多节点。(https://www.qeasy.cloud/dataintegration/60ee47b3-a7d6-4eff-882d-3adf02c966f4)
  • 调整同步频率为每15分钟批量处理，而非实时触发，降低系统负载。

• 保障机制：轻易云平台内置异常处理与重试机制，支持自动识别网络故障并进行相应处理，最大程度减少数据丢失风险。(https://qliang.cloud/dataintegration/3c0bfc51-da8d-3707-b00b-43b50f9117a2)

六、上线 checklist

• [ ] 钉钉开放平台应用已发布并上线
• [ ] 金蝶云星空API授权密钥已配置且未过期
• [ ] 轻易云集成方案已完成全字段映射
• [ ] 测试环境完成至少10笔真实审批数据端到端验证
• [ ] 生产环境启用「异常告警」通知（建议配置企业微信/钉钉群机器人）
• [ ] 制定数据核对机制（初期建议每日比对钉钉与金蝶单据数量一致性）