道一云·七巧「委外下单明细（产品）」接口字段手册与实战教程

这个接口解决什么问题

在制造与委外加工场景里,业务系统之间需要把「委外下单的产品明细」对齐到 CRM 或下游 ERP。该接口用于从道一云·七巧表单应用按时间窗口分页查询委外加工订单的产品行项,典型用途是为某零售/制造企业的 CRM 与道一云集成提供明细数据源,支撑成本核算、生产排程与订单追溯。

接口能力总览

• 认证方式:道一云·七巧开放平台标准的应用级鉴权,集成时配置 applicationId 作为目标应用身份。
• 请求结构:GET /plus/cgi-bin/open/applications/{applicationId}/forms/{formModelId},必传 applicationId 与 formModelId,可选 startTime/endTime 做增量窗口,orderField 默认 createDate、isAsc 默认 false(降序),page/pageSize 默认 1/50,joinFormModelIds 用于联表查询。
• 响应结构:JSON,业务数据位于 data.list,每条记录通过 extend.id(32 位)唯一标识;表单自定义字段统一收纳在 extend 对象内。
• 分页/增量模式:基于 createDate 排序的页码分页,配合 {{LAST_SYNC_TIME}}000 与 {{CURRENT_TIME}}000 的毫秒时间戳做增量拉取,典型调度为 */4 8-23 * * *,即 8–23 点每 4 分钟一轮。
• 策略类型:纯查询(Target 配置为「写入空操作」),不向任何目标系统落库。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里,这个接口通常用「表单查询适配器」封装:录入 applicationId 与 formModelId 后,平台自动生成请求模板,响应里 data.list 会被展开成标准化行结构,extend 内的动态字段会自动透出到字段映射器,无需手写 schema。

增量方面,轻易云的「时间窗口组件」会把 {{LAST_SYNC_TIME}}000/{{CURRENT_TIME}}000 拼到 startTime/endTime,并按 createDate 降序拉取;分页参数 page/pageSize 也由平台按 pageSize=50 循环驱动,直到返回空列表或命中上限。

由于该策略 Target 是「写入空操作」,在轻易云的画布里只需配置源端 Source 与调度,不需要挂目标 Adapter;但仍可把结果投递到轻易云的数据服务,供其他委外订单同步策略作为明细数据源二次消费。

跨方案实战要点

1. 产品名称要做二次解析:真实返回常是引用 ID,务必配置 _mongoQuery 反查物料表补出标准名称,否则下游会拿到「ID 当名称」的脏数据。
2. 数值字段全是字符串:成本单价、模费、生产数量都以字符串返回,聚合或对账前必须显式 toNumber,并处理空串与「-」等占位符。
3. extend.id 是唯一锚点:去重、幂等、关联更新都靠它,任何下游写入场景都应把它作为业务主键透传。
4. 增量时间戳要对齐到毫秒:道一云接口要的是 13 位毫秒时间戳,轻易云用 000 拼接是稳妥做法;若漏写后缀,容易拉空或重复。
5. 降序+分页组合要谨慎:createDate 降序时,新增数据出现在第一页,务必用 extend.id 去重,避免同一窗口重复入库。
6. 自由文本字段不宜做强校验:尺寸、规格、颜色、配件包装要求等字段值五花八门,做展示型映射即可,校验会引发大量误报。

踩坑复盘

• 踩坑 1:产品名称直接当名称用——某次集成里把产品名称当成展示名推到 CRM,结果下游全是 ID。这里稳妥的做法是配置 产品名称2 的反查链路,保证业务侧看到的是物料标准名称。
• 踩坑 2:数值字段字符串相加——成本单价用「+」拼接做合计,出现「12.0010.00」这种拼接串;务必在映射器里强制 toNumber 并做空值兜底。
• 踩坑 3:增量窗口跨天漏数——startTime 用了 yyyy-MM-dd 而非毫秒戳,夜里那批 23:xx 的数据被吃掉;改成毫秒戳并配合 4 分钟轮询即可。
• 踩坑 4:Target 误配导致空写入——忘了这是 QUERY_ONLY 策略,把 Target 也挂上了 Adapter,调度报错;Target 保持「写入空操作」最稳。
• 踩坑 5:extend 新增字段没透出——表单升级后下游字段缺失;轻易云的字段映射器对 extend 容器是动态感知的,只需在映射面板刷新一次即可看到新增列。

何时选用

适合「需要按时间窗口增量拉取委外加工订单产品明细、且只做查询不落库」的场景,如 CRM 侧的委外订单对照、成本反查与生产排程前置准备;不适合需要强实时双向写入或需要复杂聚合下钻的场景,这类场景建议改用专用同步策略。