金蝶云·星空旗舰版 销售订单查询 接口字段手册权威教程
小满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,纯查询不写目标,适合做主数据分发前置环节。
典型字段映射
| 字段名 | 类型 | 含义 | 实战注意事项 |
|---|---|---|---|
| id | string | 销售订单主键 | 跨系统关联的稳定锚点,务必当作唯一标识 |
| number | string | 单据编号(metadata 映射为 billno) | 业务编码,对外对账都用它,注意和金蝶字段重命名 |
| name | string | 显示名称/标题 | 用于列表展示,不一定和客户名称一致 |
| status | string | 单据状态(暂存/提交/审核) | CRM 侧常用作筛选条件 |
| enable | string | 启用标志 | 过滤作废单据时使用 |
| createtime | string | 创建时间 | 增量同步的次要参考 |
| modifytime | string | 最后修改时间 | 增量同步首选字段,务必确认时区 |
| creator_id / modifier_id | string | 创建人/修改人 ID | 跨系统映射用户时使用 |
| createorg_number | string | 创建组织编码 | 金蝶多组织架构,必须带组织维度 |
| type | string | 单据类型 | 不同类型走不同业务流程 |
| masterid | string | 主表 ID | 主从表关联时使用 |
| ctrlstrategy | string | 控制策略标识 | 偶发字段,以实际返回为准 |
| supplier_status_number / name | string | 供货状态编码与名称 | 跟踪履约进度,取值需以 API 实际返回为准 |
在轻易云上如何配置
在轻易云里,这类金蝶销售订单查询接口通常采用「金蝶云·星空旗舰版适配器 + 写入空操作 Target」的组合。
- 适配器选择:轻易云适配器市场内置「金蝶云·星空旗舰版」连接器,自动处理鉴权、租户上下文与分页封装。
- 字段映射器:轻易云字段映射器会自动读取
id、number、name、status、createtime、modifytime等常用字段,无需手工拼装响应结构。 - 策略模板:Target 配置为「写入空操作」,意味着本策略只负责把销售订单拉进轻易云的中转层,留给后续写入 CRM 或数仓的策略消费。
- 调度配置:定时任务配置为
*/3 7-23 * * *,覆盖业务时段,凌晨留给备份与重跑窗口。
跨方案实战要点
- id 与 number 双锚点:多个客户方案里我们都坚持用
id做主键、number(billno)做业务编码,两者缺一不可。 - modifytime 是增量同步的生命线:分页 + 时间窗口是稳妥组合;纯页码分页容易漏单。
- 组织维度不能丢:金蝶多组织架构下,
createorg_number必须随单据一起同步,否则下游会跨组织串数据。 - 供货状态字段名要看实际返回:文档里写的是
supplier_status_number / name,但不同版本金蝶可能字段名不同,务必先抓样例响应再写映射。 - 纯查询策略要标 QUERY_ONLY:Target 设空操作,避免误把销售订单写回金蝶形成回环。
- 业务时段调度:凌晨不调度,降低与金蝶夜间批处理冲突的概率。
踩坑复盘
- 坑一:把 number 当 id 用。
number是业务编码,某些场景下会被调整,跨系统关联必须用id。 - 坑二:忽略时区。
modifytime不做时区转换会导致增量窗口偏移,出现重复拉取或漏拉。 - 坑三:供货状态字段名漂移。不同金蝶版本的供货状态字段命名不一致,稳妥的做法是先 dump 一份真实响应再固化映射。
- 坑四:分页默认值坑。
pageSize默认 10 偏小,在生产环境务必显式调大(例如 100)以减少请求次数。 - 坑五:组织串数据。未带
createorg_number就同步,导致 A 组织的单据落到 B 组织,排查极费时间。
何时选用
当你需要把金蝶云·星空旗舰版的销售订单同步到 CRM、数据中台或下游系统时,首选该查询接口做主数据拉取。如果需要写入金蝶,请改用保存类接口;若只需轻量校验,直接走金蝶自带报表更划算。
本文为原创内容,转载请注明出处:https://www.qeasy.cloud/insights/engineering/hb-p2-129-7840