轻易云
注册体验

金蝶云·星空旗舰版 销售订单查询 接口字段手册权威教程

· 吕修远· 工程最佳实践· 13 次浏览· 约 4 分钟读完
小满OKKICRM金蝶云·星空旗舰版金蝶云·星空销售订单接口字段手册轻易云增量同步数据集成

这个接口解决什么问题

销售订单查询接口(/kapi/v2/dsg5/sm/sm_salorder/queryadd)用于从金蝶云·星空旗舰版分页拉取销售订单主数据。在零售、贸易等业态里,这是把 ERP 单据同步到 CRM 或数据中台的起点——没有它,后续的客户对账、履约跟踪、跨系统编号关联都无从谈起。典型场景是把金蝶的销售订单拉回到小满 OKKICRM 做单据映射,或者沉淀到数据仓库做履约分析。

接口能力总览

  • 认证方式:基于金蝶云·星空的 OpenAPI 鉴权,需在请求头携带访问令牌(由平台统一换取)。
  • 请求方法:POST,Content-Type 为 application/json。
  • 请求结构:Body 中包含 data(查询条件对象)、pageNo(默认 1)、pageSize(默认 10)。
  • 响应结构:标准 JSON,顶层为 data 列表,每个元素包含 id、number、name、status、createtime、modifytime 等字段。response 字段由源端 autoFillResponse 自动填充,实际取值以 API 返回为准。
  • 分页模式:经典页码分页,pageNo + pageSize,无游标。
  • 增量模式:依赖 modifytime 做时间窗口增量,定时策略常见为 */3 7-23 * * *(每日 7–23 点每 3 分钟)。
  • 效果标记:QUERY_ONLY,纯查询不写目标,适合做主数据分发前置环节。

典型字段映射

字段名类型含义实战注意事项
idstring销售订单主键跨系统关联的稳定锚点,务必当作唯一标识
numberstring单据编号(metadata 映射为 billno)业务编码,对外对账都用它,注意和金蝶字段重命名
namestring显示名称/标题用于列表展示,不一定和客户名称一致
statusstring单据状态(暂存/提交/审核)CRM 侧常用作筛选条件
enablestring启用标志过滤作废单据时使用
createtimestring创建时间增量同步的次要参考
modifytimestring最后修改时间增量同步首选字段,务必确认时区
creator_id / modifier_idstring创建人/修改人 ID跨系统映射用户时使用
createorg_numberstring创建组织编码金蝶多组织架构,必须带组织维度
typestring单据类型不同类型走不同业务流程
masteridstring主表 ID主从表关联时使用
ctrlstrategystring控制策略标识偶发字段,以实际返回为准
supplier_status_number / namestring供货状态编码与名称跟踪履约进度,取值需以 API 实际返回为准

在轻易云上如何配置

在轻易云里,这类金蝶销售订单查询接口通常采用「金蝶云·星空旗舰版适配器 + 写入空操作 Target」的组合。

  • 适配器选择:轻易云适配器市场内置「金蝶云·星空旗舰版」连接器,自动处理鉴权、租户上下文与分页封装。
  • 字段映射器:轻易云字段映射器会自动读取 id、number、name、status、createtime、modifytime 等常用字段,无需手工拼装响应结构。
  • 策略模板:Target 配置为「写入空操作」,意味着本策略只负责把销售订单拉进轻易云的中转层,留给后续写入 CRM 或数仓的策略消费。
  • 调度配置:定时任务配置为 */3 7-23 * * *,覆盖业务时段,凌晨留给备份与重跑窗口。

跨方案实战要点

  1. id 与 number 双锚点:多个客户方案里我们都坚持用 id 做主键、number(billno)做业务编码,两者缺一不可。
  2. modifytime 是增量同步的生命线:分页 + 时间窗口是稳妥组合;纯页码分页容易漏单。
  3. 组织维度不能丢:金蝶多组织架构下,createorg_number 必须随单据一起同步,否则下游会跨组织串数据。
  4. 供货状态字段名要看实际返回:文档里写的是 supplier_status_number / name,但不同版本金蝶可能字段名不同,务必先抓样例响应再写映射。
  5. 纯查询策略要标 QUERY_ONLY:Target 设空操作,避免误把销售订单写回金蝶形成回环。
  6. 业务时段调度:凌晨不调度,降低与金蝶夜间批处理冲突的概率。

踩坑复盘

  • 坑一:把 number 当 id 用。number 是业务编码,某些场景下会被调整,跨系统关联必须用 id。
  • 坑二:忽略时区。modifytime 不做时区转换会导致增量窗口偏移,出现重复拉取或漏拉。
  • 坑三:供货状态字段名漂移。不同金蝶版本的供货状态字段命名不一致,稳妥的做法是先 dump 一份真实响应再固化映射。
  • 坑四:分页默认值坑。pageSize 默认 10 偏小,在生产环境务必显式调大(例如 100)以减少请求次数。
  • 坑五:组织串数据。未带 createorg_number 就同步,导致 A 组织的单据落到 B 组织,排查极费时间。

何时选用

当你需要把金蝶云·星空旗舰版的销售订单同步到 CRM、数据中台或下游系统时,首选该查询接口做主数据拉取。如果需要写入金蝶,请改用保存类接口;若只需轻量校验,直接走金蝶自带报表更划算。

本文为原创内容,转载请注明出处:https://www.qeasy.cloud/insights/engineering/hb-p2-129-7840

评论