轻易云
注册体验

金蝶星瀚销售订单查询接口字段手册权威教程

· 许创贵· 工程最佳实践· 50 次浏览· 约 5 分钟读完

这个接口解决什么问题

在零售与全渠道场景里,电商前台(本案例对应旺店通)每天会产生海量销售订单,这些订单需要回流到金蝶星瀚供应链侧,用于审核、出库、开票及业财对账。本接口 /kapi/v2/a123/sm/sm_salorder/getOrder 用于从金蝶星瀚侧查询销售订单主数据,典型的价值是:为跨系统订单对照提供权威单据源、支撑增量同步已审核订单、为下游出库/开票提供就绪状态订单。

请求调度者配置 - date_type 字段详情面板(元数据视图)

接口能力总览

  • 认证方式:金蝶星瀚开放平台标准 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 分钟执行,业务高峰时段高频拉取,凌晨让出窗口给上游写操作。

典型字段映射

字段名类型含义实战注意事项
idstring金蝶系统主键跨系统主键,用于去重与反查
billnostring单据编号跨系统关联主用键,常映射为电商侧订单号
billstatus / billstatus_titlestring单据状态/显示名下游出库/开票只看 已审核 等值
closestatus / closestatus_titlestring关闭状态关闭订单不再驱动出库
cancelstatus / canceldatestring取消状态与日期取消订单需在下游显式过滤
auditdatestring审核日期增量同步的常用锚点之一
modifytimestring最后修改时间增量同步首选锚点
bizdate / biztimestring业务日期/时间财务入账日凭据
totalamount / totaltaxamount / totalallamountstring不含税金额/税额/价税合计字符串传输,需转 decimal 后做对账
curtotalamount / curtotalallamountstring本位币金额多币种场景下必看
exchangerate / exratedate / exchangetypestring汇率/适用日期/类型外币订单核对成本
receiveaddress / addressstring收货地址/业务地址物流对接的关键字段
deliverlocationstring发货地点/仓库决定仓库分配
a123_textfield* / a123_datefield* / a123_decimalfield* / a123_combofield*string租户自定义扩展字段各租户含义不同,需按实际配置理解

在轻易云上如何配置

在轻易云数据集成平台中,该接口通常以金蝶星瀚连接器形式封装,典型配置路径:

  1. 新建策略 → 选择金蝶星瀚 → 选「销售订单查询」适配器,系统会预填请求路径与默认分页参数。
  2. 元数据对齐:billno 映射为 number、id 映射为 id,开启 idCheck,平台会自动按主键去重。
  3. 增量策略:在轻易云的时间戳调度里,把 modifytime 作为增量游标;稳妥的做法是叠加 bizdate 作为兜底过滤,避免历史脏数据被重复拉出。
  4. Target 配置为空操作:本案例为纯查询策略,不写入目标系统,轻易云的字段映射器可关闭写动作,仅做数据落地或转发。
  5. 过滤条件:在 data 参数中传入 billstatus=A(已审核)或 closestatus=,平台会自动把这些表达式翻译成金蝶侧的查询语义。
  6. 自定义字段:a123 前缀的扩展字段会被轻易云的字段映射器自动识别,无需手工补齐,直接拖到目标侧即可。

跨方案实战要点

  1. billno 是跨系统关联的命脉:金蝶与旺店通之间,订单编号(对应旺店通 tid/oid)必须与 billno 精确对齐,否则会出现「同一订单双单」的对账黑洞。
  2. 增量游标优先用 modifytime:相比 auditdate,modifytime 能捕获变更单、退回重审等所有写动作,稳妥的做法是把窗口设为「上次成功时间 − 1 分钟」防止漏单。
  3. 状态字段成对消费:billstatus(审核)、closestatus(关闭)、cancelstatus(取消)必须联合判断,只看一个字段是常见翻车点,容易把已关闭订单继续下发出库。
  4. 金额字段全部转 decimal:金蝶侧金额以 string 返回,直接做减法会溢出,集成侧一定要显式解析。
  5. 高频时段加密执行:本案例把执行窗口压缩在 7–22 点每 5 分钟,既贴近业务节奏,又避开凌晨上游 ETL。
  6. 自定义字段按租户理解: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

评论