道一云·七巧 回款计划（收款明细）接口字段手册权威教程

这个接口解决什么问题

道一云·七巧的「回款计划（收款明细）」接口,用于按合同维度拉取客户的计划回款与实际回款金额。典型场景是把回款明细同步到小满 OKKICRM,做财务对账、回款进度跟踪与业绩核算。我们做多个客户项目时发现,只要把这一个接口摸透,跨系统的回款数据闭环就稳了一大半。

接口能力总览

• 认证方式:采用道一云·七巧开放平台的 Access Token 机制,通过应用接口密钥换取 token 后,作为请求头(通常是 Authorization 或自定义头)带入查询请求。
• 请求结构:以合同或客户为查询条件,常见的入参包括 number(合同编号)、id(合同主键)、时间区间等,支持按条件组合过滤。
• 响应结构:返回 JSON 对象,主体为表单记录数组,每条记录包含客户名称、合同编号、金额字段以及一个 extend 扩展对象,扩展对象里通常藏着表单自定义字段。
• 分页/增量模式:道一云·七巧表单类接口普遍使用页码+每页大小(pageNo/pageSize 或类似命名)的传统分页,增量拉取需要依赖业务时间字段(如修改时间)做游标式过滤,在轻易云里通常被封装成「按时间窗口滚动拉取」的策略模板。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里,这个接口通常被封装为一个「表单查询」类型的适配器,挂在源端「道一云·七巧」节点下。配置时只需要三步:第一,在适配器里填入应用接口凭证,平台会自动维护 token 的获取与刷新;第二,选择「回款计划(收款明细)」这张表单,设置查询条件(如按合同编号或时间区间);第三,在字段映射器里,把道一云字段与 CRM 字段做一一对应,平台默认会用「小满回款单编号」做幂等键,保证重复拉取不会产生重复回款单。

跨方案实战要点

1. 以合同为主键组织数据:道一云的回款明细天然按合同维度组织,合同编号既承担业务主键,也常被当作查询入参,做主数据关联时非常顺手。
2. 金额字段全部按字符串处理:源端一律是 string,无论下游是 CRM、ERP 还是 BI,都不要忘记类型转换,否则会出现科学计数法或精度丢失。
3. 回款金额与实际回款金额分别落库:两者之差就是「未回款余额」,建议在轻易云里通过计算字段直接产出,下游消费方会非常省事。
4. extend 对象谨慎展开:扩展字段里经常藏表单自定义项,稳妥的做法是先用轻易云的可视化解析器展开预览,再选择性入库,不要直接整块 JSON 落到下游。
5. 增量靠时间窗口,不靠页码:表单类接口页码容易错位,真实场景里我们更倾向于按修改时间滚动拉取,轻易云支持配置「按时间窗口增量」的拉取策略。
6. 幂等键必须落到回款单编号:同一笔回款可能被多次推送,只要「小满回款单编号」一致,轻易云会自动覆盖更新,避免对账时多出脏数据。

踩坑复盘

• 金额字符串被当成数字直接相加:某零售企业集成时,直接把「回款金额」当 number 入库,导致带小数的金额精度丢失。稳妥做法是显式 CAST/CONVERT 为 decimal,或者在轻易云的字段映射器里指定数值类型。
• extend 整体入库导致下游字段爆炸:曾有项目把整个 extend 对象原样落库,下游系统表结构被冲乱。建议只解析需要的自定义字段,其余忽略。
• 页码分页漏数据:表单接口在并发场景下可能出现「同一条记录出现在两页」的边界问题。稳妥的做法是改用时间窗口增量,或者在轻易云里开启「按主键去重」开关。
• 合同编号两边编码不一致:CRM 里的合同编号和道一云里的合同编号格式不同(一个带前缀、一个不带),没有做归一化就会导致关联失败。建议在轻易云里加一个「合同编号标准化」的清洗步骤。
• token 过期导致批量任务中断:批量回款同步跑一半 token 失效,后续全部 401。在轻易云里,平台会自动做 token 刷新与失败重试,基本可以规避此类中断。

何时选用

只要业务涉及「按合同维度同步回款明细到 CRM 或 BI」,并且源端是道一云·七巧的自定义表单,就应该直接选这个接口;但如果是逐笔银行流水对账、需要按账户维度组织数据,那它并不合适,应当改用银行流水接口或三方支付接口。