这个接口解决什么问题

在某零售/制造企业的 CRM-ERP 一体化场景中,销售订单需要在 CRM(小满OKKICRM)与 ERP(鼎捷T100)之间双向贯通:CRM 是订单入口与客户运营阵地,ERP 承担物料、库存与财务履约。把订单、客户、产品三大基础单据打通,可避免重复录入、编码错位与履约延迟,支撑业财一体化。

接口能力总览

认证方式:鼎捷T100 采用 ERP 账套 + 用户口令的会话认证,小满 OKKICRM 采用开放平台 AppID/Secret 的 OAuth 模式;两者在集成平台侧统一收敛为连接器凭据。
请求/响应结构:鼎捷 T100 销售订单主表+明细行的嵌套 JSON 结构(so_master 为数组);小满 OKKICRM 订单为 product_list 明细行数组,响应均为分页 JSON。
分页模式:两端均支持 pageNo/pageSize 分页,推荐每页 100-200 条;增量同步按 modifyDate(产品)、start_time~end_time(客户/订单)窗口拉取。
幂等键:产品 product_no、客户 customerNo、订单 order_no/number 作为业务键做幂等回写。

典型字段映射

产品同步(策略 2:鼎捷→小满)

源字段	目标字段	类型	实战注意事项
itemNo	product_no	DIRECT	跨系统物料对照键,务必保证唯一
itemName / itemSpec	name	DIRECT	优先 itemName,空则回退 itemSpec
itemNo	product_id	COLLECTION	更新场景需通过集线器反查 product_id
itemSpec	model	DIRECT	规格型号
unitNo	unit	DIRECT	计量单位,注意单位字典一致性

客户同步(策略 6:小满→鼎捷)

源字段	目标字段	类型	实战注意事项
serial_id	customerNo / number	DIRECT	客户编号主键,跨系统对照
基本信息公司名称 / name	customerName	DIRECT	优先基本信息公司名称,空则 name
基本信息税号	taxNo	DIRECT	税号,影响开票
serial_id	id	COLLECTION	更新场景需联查鼎捷客户 id
—	status	CONSTANT	新增默认 1(启用)

订单同步(策略 3:小满→鼎捷)

源字段	目标字段	类型	实战注意事项
order_no	number	DIRECT	订单编号幂等键
account_date	order_date	DIRECT	日期格式转换
company.serial_id	customerNo	COLLECTION	需先有客户映射
currency	currency	DIRECT	币种
exchange_rate	exchange_rate	TRANSFORM	若为百分比需 ÷100
amount	amount	DIRECT	订单总金额
product_list	so_detail(明细行)	ARRAY	按鼎捷 API 规范封装
product_list.sku_no/goods_no/product_no	itemNo	DIRECT	需物料编码已对齐
product_list.quantity	qty	DIRECT	数量
product_list.price	price	DIRECT	单价

在轻易云上如何配置

在轻易云数据集成平台里,小满与鼎捷分别预置了官方适配器,订单同步通常采用「策略编排器 + 字段映射器」组合:通过 QUERY_ONLY 策略先建立产品/客户集线器,再用 SYNC 策略驱动订单写入,平台维护 LAST_SYNC_TIME 窗口并自动重试。轻易云的字段映射器支持 DIRECT、COLLECTION、TRANSFORM、CONSTANT、ARRAY 五类规则,可直接复用上文表格;明细行通过数组展开器按 product_list→so_detail 一一映射,idCheck 与幂等键由平台自动注入。

跨方案实战要点

先建集线器再同步:多个客户项目里,我们都先跑「查询小满产品」「查询鼎捷客户」两条 QUERY_ONLY 策略,把编码对照表落到集线器,后续同步策略才能稳定联查。
物料编码必须先对齐:小满订单→鼎捷订单强依赖物料编码一致,务必先执行鼎捷产品→小满产品同步,或在两系统维护同一编码规则。
客户主键双字段:鼎捷客户主键是 customerNo 与 id 共同存在,同步场景务必 idCheck 启用,新增走 customerNo,更新需回写 id。
订单筛选已审批:小满订单建议过滤 approval=1,避免把草稿/作废单据推到 ERP 引发库存预占。
窗口时间错峰:多策略同时拉取会撞 API 限流,Cron 偏移建议 1-2 分钟,如 1-59/5、3-59/5、5-59/10。
消息推送与清理独立:企微/飞书推送、30天日志清理建议独立调度,与业务策略错开,避免相互阻塞。

踩坑复盘

这里容易翻车:鼎捷 itemName 与 itemSpec 同时存在但语义重叠,直接拼接会导致小满产品名称过长;稳妥的做法是按优先级取其一。
汇率单位陷阱:小满 exchange_rate 有时是百分数(如 685 表示 6.85),直接透传到鼎捷会导致金额放大 100 倍,务必在 TRANSFORM 里除以 100。
明细行数组封装:鼎捷 so_master 必须是数组结构,部分工程师误传对象导致整单被拒;实施时一定要走平台数组展开器。
联查失败不重试:编码映射缺失若重试只是浪费配额,正确做法是写入失败表 + 触发告警,人工补齐编码后再手动重跑。
删除策略误清空:30 天清理若时间窗口配置错误可能误删活跃数据,稳妥做法是先 dry-run 统计,再执行删除。

何时选用

适用于 CRM-ERP 一体化、需要订单/客户/产品三中心打通的中大型企业;若仅有单一方向(如仅 CRM→ERP)或单据类型极简,可裁剪集线器策略;若涉及财务总账、发票等深度场景,建议叠加财务模块单独设计。

小满OKKICRM与鼎捷T100订单同步接口字段手册权威教程