金蝶云星瀚销售价目表查询接口字段手册权威教程

这个接口解决什么问题

在零售与分销场景里,价格是订单与库存之外最敏感的字段。旺店通作为前端零售系统,金蝶星瀚作为后端供应链/财务系统,二者必须在「物料×客户×日期」三个维度上对齐定价。销售价目表接口正是把金蝶星瀚这一侧的价目表数据(主表+明细行)按需拉取出来,用于:① 同步销售定价规则;② 旺店通货品售价与金蝶价目表逐项对照;④ 订单报价时拉取标准售价;⑤ 客户级价格策略映射。

接口能力总览

• 接口路径:/kapi/v2/a123/sm/sm_salepricelist/sale_price
• 请求方式:HTTP POST(查询接口),Body 以 JSON 传递分页与过滤条件
• 认证方式:租户级 token(Header 鉴权),token 由轻易云调度层统一托管与刷新
• 请求参数:pageNo(默认 1)、pageSize(默认 20)、data(可选过滤对象,支持物料/客户/日期等条件)
• 响应结构:数组型列表,每条记录为价目表+明细行复合对象,含主表字段与 priceentryentity_* 明细字段
• 分页模式:标准 pageNo/pageSize 分页,不支持游标
• 增量模式:依赖 modifytime(修改时间)做增量,主键 id 实际由 {{modifytime}}{{id}}{{priceentryentity_id}} 拼接生成,实现主表+明细行的唯一去重
• 执行频次:crontab 1-59/5 7-22 * * *,每 5 分钟一次,仅在营业时段高频运行
• 写入策略:Target 为「空操作」,属纯查询策略,数据落库到轻易云中台

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里,这个接口的接入通常采用「金蝶星瀚适配器 + 字段映射器 + 写入空操作 Target」三件套:

1. 适配器选型:轻易云内置金蝶星瀚(kapi v2)适配器,只需填入租户编码、账套号(token 由平台托管,无需手动维护)与目标接口路径即可。
2. 分页与过滤:pageNo/pageSize 直接在适配器面板配置,data 过滤条件支持可视化拖拽字段生成。
3. 字段映射器:轻易云的字段映射器会自动读取接口元数据,把上表中的字段一键映射到目标中台模型;idCheck 默认开启,主键拼接规则可在元数据里直接写 {{modifytime}}{{id}}{{priceentryentity_id}}。
4. 增量水位:平台自动按 modifytime 维护增量游标,无需人工写 SQL 记录水位,断点续跑也由平台兜底。
5. 空操作 Target:Target 选「写入空操作」,数据落库到轻易云中台即视为成功,不向金蝶写入,避免误操作。

跨方案实战要点

在多个客户项目里,我们反复遇到以下共性问题,稳妥的做法是:

1. 主键必须复合:价目表是「主表+明细行」两层结构,单用 id 必然撞键,务必用 modifytime+id+priceentryentity_id 拼接。
2. 状态前置过滤:status=A(已审核)与 enable=1(启用)要在请求侧或映射器前置过滤,不然下游会被暂存/停用记录污染。
3. 有效期校验:effectdate ≤ now ≤ expirydate 一定要在落地后再校验一次,接口侧只给原始值,不替你做判断。
4. 含税价拆分:istax 决定价格字段是否含税,落库时建议拆成「含税价」「不含税价」「税率」三列,后端财务模块才不会报错。
5. 阶梯价要展开:isstair=1 时,价格信息藏在 priceentryentity_* 子表里,必须把明细行循环展开后再定价。
6. 客户级映射:把 applycustomer 与旺店通客户/会员等级建一张映射表,定价时按客户命中优先级匹配,比硬编码可靠得多。

踩坑复盘

• 坑 1:主键撞车导致丢数。只取 id 当主键,同一价目表的多个物料明细会被覆盖。应对:开启 idCheck,按拼接规则生成主键。
• 坑 2:增量水位被回溯修改打断。金蝶端支持反审核改价,modifytime 会回退,增量游标会「漏拉」。应对:加一个 audittime > 上次水位 的补偿条件,或每日做一次全量对账。
• 坑 3:含税价直接当不含税价用。下单环节取价正常,到开票环节价税金额对不上。应对:落库时按 istax 拆分,下游按需取数。
• 坑 4:暂存记录污染下游。没过滤 status,把暂存价目表也同步到了前端。应对:请求侧加状态过滤,或在映射器里加分支。
• 坑 5:阶梯价只取第一条。明细行有多条数量区间,只取第一条导致量大价低。应对:按数量区间循环匹配,轻易云映射器支持脚本扩展。

何时选用

该接口适用于「需要把金蝶星瀚价目表作为定价唯一来源」的零售/分销场景,尤其是旺店通与金蝶混合部署、前端要按物料+客户+日期精细报价、且对含税/阶梯价有强诉求的项目。边界在于:仅适合纯查询场景,如需把外部价格反写回金蝶,需另配写入类接口。