金蝶星瀚销售订单查询接口字段手册权威教程
这个接口解决什么问题
在零售与全渠道场景里,电商前台(本案例对应旺店通)每天会产生海量销售订单,这些订单需要回流到金蝶星瀚供应链侧,用于审核、出库、开票及业财对账。本接口 /kapi/v2/a123/sm/sm_salorder/getOrder 用于从金蝶星瀚侧查询销售订单主数据,典型的价值是:为跨系统订单对照提供权威单据源、支撑增量同步已审核订单、为下游出库/开票提供就绪状态订单。
接口能力总览
- 认证方式:金蝶星瀚开放平台标准 OAuth/Token 模式,在轻易云中通过连接器统一托管凭证,无需在脚本里硬编码。
- 请求路径:
/kapi/v2/a123/sm/sm_salorder/getOrder,其中a123为租户/应用前缀,实际接入时按所在环境替换。 - 请求结构:
pageNo(默认 1)、pageSize(默认 20)、data(过滤条件对象,典型过滤维度包括billstatus、bizdate区间、modifytime区间)。 - 响应结构:列表型,每条记录即一整张单据;
billno与id分别在 metadata 中以number、id暴露,idCheck: true启用主键校验,autoFillResponse: true让返回字段自动对齐元数据。 - 分页与增量:分页通过
pageNo/pageSize推进;增量以modifytime作为时间戳游标,稳妥做法是每天执行多次(本案例 crontab 为0-59/5 7-22 * * *,每 5 分钟跑一次)以降低单次超时与漏单风险。 - 执行频率:每日 7–22 点每 5 分钟执行,业务高峰时段高频拉取,凌晨让出窗口给上游写操作。
典型字段映射
| 字段名 | 类型 | 含义 | 实战注意事项 |
|---|---|---|---|
| id | string | 金蝶系统主键 | 跨系统主键,用于去重与反查 |
| billno | string | 单据编号 | 跨系统关联主用键,常映射为电商侧订单号 |
| billstatus / billstatus_title | string | 单据状态/显示名 | 下游出库/开票只看 已审核 等值 |
| closestatus / closestatus_title | string | 关闭状态 | 关闭订单不再驱动出库 |
| cancelstatus / canceldate | string | 取消状态与日期 | 取消订单需在下游显式过滤 |
| auditdate | string | 审核日期 | 增量同步的常用锚点之一 |
| modifytime | string | 最后修改时间 | 增量同步首选锚点 |
| bizdate / biztime | string | 业务日期/时间 | 财务入账日凭据 |
| totalamount / totaltaxamount / totalallamount | string | 不含税金额/税额/价税合计 | 字符串传输,需转 decimal 后做对账 |
| curtotalamount / curtotalallamount | string | 本位币金额 | 多币种场景下必看 |
| exchangerate / exratedate / exchangetype | string | 汇率/适用日期/类型 | 外币订单核对成本 |
| receiveaddress / address | string | 收货地址/业务地址 | 物流对接的关键字段 |
| deliverlocation | string | 发货地点/仓库 | 决定仓库分配 |
| a123_textfield* / a123_datefield* / a123_decimalfield* / a123_combofield* | string | 租户自定义扩展字段 | 各租户含义不同,需按实际配置理解 |
在轻易云上如何配置
在轻易云数据集成平台中,该接口通常以金蝶星瀚连接器形式封装,典型配置路径:
- 新建策略 → 选择金蝶星瀚 → 选「销售订单查询」适配器,系统会预填请求路径与默认分页参数。
- 元数据对齐:
billno映射为number、id映射为id,开启idCheck,平台会自动按主键去重。 - 增量策略:在轻易云的时间戳调度里,把
modifytime作为增量游标;稳妥的做法是叠加bizdate作为兜底过滤,避免历史脏数据被重复拉出。 - Target 配置为空操作:本案例为纯查询策略,不写入目标系统,轻易云的字段映射器可关闭写动作,仅做数据落地或转发。
- 过滤条件:在
data参数中传入billstatus=A(已审核)或closestatus=,平台会自动把这些表达式翻译成金蝶侧的查询语义。 - 自定义字段:a123 前缀的扩展字段会被轻易云的字段映射器自动识别,无需手工补齐,直接拖到目标侧即可。
跨方案实战要点
billno是跨系统关联的命脉:金蝶与旺店通之间,订单编号(对应旺店通tid/oid)必须与billno精确对齐,否则会出现「同一订单双单」的对账黑洞。- 增量游标优先用
modifytime:相比auditdate,modifytime能捕获变更单、退回重审等所有写动作,稳妥的做法是把窗口设为「上次成功时间 − 1 分钟」防止漏单。 - 状态字段成对消费:
billstatus(审核)、closestatus(关闭)、cancelstatus(取消)必须联合判断,只看一个字段是常见翻车点,容易把已关闭订单继续下发出库。 - 金额字段全部转 decimal:金蝶侧金额以 string 返回,直接做减法会溢出,集成侧一定要显式解析。
- 高频时段加密执行:本案例把执行窗口压缩在 7–22 点每 5 分钟,既贴近业务节奏,又避开凌晨上游 ETL。
- 自定义字段按租户理解:a123 前缀的扩展字段是各租户按需配置的,接手陌生租户时务必先抓样例核对含义,不要照搬别家方案。
踩坑复盘
- 坑一:把
billstatus_title当判断条件。title是显示名,可能被本地化或文案调整;稳妥做法是只用billstatus这种编码字段做逻辑判断。 - 坑二:
pageSize设为 50/100 直接 OOM。金蝶单据体量大,大pageSize会让响应体撑爆内存;稳妥做法是 pageSize≤20,并配以高频重试。 - 坑三:增量起点用
createtime导致历史数据全量回灌。createtime不会反映后续变更;稳妥做法是modifytime作主、bizdate作辅。 - 坑四:汇率字段缺失导致财务侧金额对不平。外币订单的
exchangerate与exratedate必须同时落库,不能只取totalamount。 - 坑五:关闭/取消状态过滤缺失,出库重复触发。下游系统若不消费
closestatus与cancelstatus,会重复发货,这是实际项目里最常见的资金/履约事故来源。
何时选用
该接口适用于「电商前台 ↔ 金蝶星瀚供应链」场景下的订单主数据查询,尤其是跨系统订单对照、增量同步已审核订单、驱动下游出库/开票等链路。不适用于需要写入金蝶的写场景(那是 saveOrder 类接口的范畴),也不适合做实时单点查询(高频轮询场景请走变更通知)。
本文为原创内容,转载请注明出处:https://www.qeasy.cloud/insights/engineering/hb-p2-300-b4d0