用友YS查询库存价格接口字段手册权威教程

这个接口解决什么问题

在用友BIP与用友YS的库存同步链路里，「查询库存价格」承担了价格主数据的拉取职责。它按「组织 + 物料」维度返回某核算主体下物料的库存/销售价格，供BIP侧做价格比对、库存估值与主数据同步。该接口策略类型为QUERY，仅做查询不下写，是典型的「拉取型」数据对象。

接口能力总览

• 认证方式：用友YS开放平台WebAPI，租户级应用凭证（client_id/client_secret），通过OAuth换取access_token后调用。
• 请求方法：POST，Content-Type为application/json。
• 请求体：以查询条件为主，通常包含组织编码、物料编码、生效日期范围等过滤参数。
• 响应结构：返回物料价格列表，每条记录包含id、material、accentity、price、mainunit、busitime等字段；metadata中以id为主键。
• 分页/增量：支持按条件分页查询；增量判断字段为pubts（发布时间戳）或busitime（业务时间），建议落地端按pubts去重与按busitime做窗口过滤。
• 调度：典型crontab为13 2 * * *，每日凌晨执行一次。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里，该接口通常以「源系统适配器 + 字段映射器」的方式接入。

• 适配器层：选择用友YS的查询接口模板，配置应用凭证与目标组织清单。
• 字段映射器：会自动按本手册的通用概念映射（如accentity→org_id、price→unit_price、mainunit→base_unit_id）做默认映射，工程师只需补充目标侧BIP物料主键的匹配规则。
• 调度配置：轻易云内置crontab编辑器，直接填入13 2 * * *即可，亦可改用「上次成功时间 + 间隔」的触发式调度。
• 落地策略：Target为「写入空操作」，平台只做中转缓存，便于下游BI或BIP侧按需消费。

跨方案实战要点

1. 务必按组织过滤：价格是组织维度的，不传accentity_code会拉回全量数据，体量与权限风险都很大。
2. price是字符串：直接落库为数值会出现精度丢失，建议在映射器里配置Decimal转换，截位规则按mainunit_Precision。
3. id是唯一主键：去重与幂等键首选id，pubts仅做增量辅助，不要把pubts当主键。
4. 主键与编码并存：material内码是系统键，material_code是业务键，跨系统同步时双键都要落，便于后续维基。
5. 增量建议按pubts：相比busitime，pubts更稳定，不易因业务时间回写出现漏拉。
6. 凌晨调度要错峰：02:13这个时间点会与上游其他库存同步任务撞车，建议根据任务链路整体错峰调度。

踩坑复盘

• 踩坑一：price直接当数值使用，导致8位以上金额被截断。应对：在轻易云字段映射器里强制转Decimal并按精度截位。
• 踩坑二：未传组织过滤条件，一次性拉回全集团价格，触发上游限流。应对：先在metadata里固化组织白名单。
• 踩坑三：用material_name做匹配键，重名导致一对多错配。应对：永远用material_code或material做键。
• 踩坑四：把busitime当作增量游标，业务时间回写后漏拉整批数据。应对：增量游标改用pubts。
• 踩坑五：忽略mainunit_Precision，价目表价格与库存数量精度对不上。应对：字段映射器里挂精度转换脚本。

何时选用

适用于「用友BIP与用友YS库存同步」场景下需要拉取物料价格的拉取型集成，尤其是做价格比对、库存估值与价格主数据同步。若需要把价格写回下游ERP或价目表系统，请选择支持写入的策略类型，而非QUERY_ONLY。