用友BIP销售订单查询接口字段手册权威教程

这个接口解决什么问题

用友BIP销售订单查询接口(/yonbip/sd/voucherorder/list)是CRM与ERP销售订单集成的核心入口。典型场景是把小满OKKICRM的订单状态同步到ERP侧,或者反向从ERP拉取订单明细回写到CRM,实现订单全链路可视。本接口以明细行级粒度返回扁平化数据,适合按行做库存、批次、价格对照。

接口能力总览

• 认证方式:用友BIP标准OAuth授权,需在请求头携带access_token。
• 请求结构:HTTP POST,Body为JSON,核心参数pageIndex(默认1)、pageSize(默认50)、open_vouchdate_begin/end(增量时间窗)、code(单据编号)、nextStatusName(状态过滤)。
• 响应结构:返回扁平化数组,metadata中id对应orderDetailId(明细主键)、number对应code(单据编号)。
• 分页模式:传统分页,需循环递增pageIndex直到返回空数组。
• 增量模式:按open_vouchdate_begin至open_vouchdate_end按天滚动,生产环境典型调度为*/7 8-18 * * *(工作时段每7分钟一次)。
• 特殊标志:isSum=false表示返回明细行,true时按表头聚合。

典型字段映射

在轻易云上如何配置

轻易云数据集成平台对用友BIP销售订单接口做了完整的适配器封装:

• 适配器:在轻易云里,这个接口的调用通常采用「用友BIP-销售订单查询」预置连接器,只需填入租户、AppKey即可启用,免手写OAuth刷新逻辑。
• 字段映射器:平台自动识别metadata中id→orderDetailId、number→code的映射关系,在映射画布里可直接拖拽orderDetailId作为目标系统的唯一键。
• 增量策略:配置面板支持可视化设定open_vouchdate_begin/end的偏移变量(如{{DAYS_AGO_30|date}}),结合调度器*/7 8-18 * * *实现滚动抓取。
• 分页循环:轻易云内置分页迭代器,自动按pageIndex循环并写入目标库,直到返回空页自动终止。
• 去重机制:建议以orderDetailId作为主键写入,平台会按主键做UPSERT,避免重复行。

跨方案实战要点

1. 明细行级粒度是默认:用友BIP销售订单API返回的是「表头+表体扁平化」后的明细行,不是表头聚合数据。如果业务侧需要单据级状态,需要按id/orderId二次聚合。
2. 主键选错会导致全量重拉:真实场景中,容易把id误当成唯一键,但同一订单的多商品行会共享id,导致下游重复入库。稳妥的做法是始终用orderDetailId。
3. 状态枚举必须翻译:nextStatus和payStatusCode是英文枚举值,直接传给业务方会「翻车」,应建立枚举映射表(CONFIRMORDER→开立、FINISHPAYMENT→已付款)。
4. 增量字段优先级:当同时存在vouchdate(单据日期)、orderDate(制单日期)、pubts(系统时间戳)时,**优先用vouchdate**做增量过滤,语义最清晰;pubts作为辅助去重。
5. 金额字段配对校验:payMoney(合计含税金额)应等于各行oriSum之和;差异过大时往往是赠品行(MARKUP/REBATE)未排除,需结合orderProductType过滤。
6. 多组织权限:多销售组织的客户务必传salesOrgId过滤,否则接口会返回全量数据,既慢又存在越权风险。

踩坑复盘

• 踩坑1:分页死循环。pageSize设过大(如1000)被服务端截断时,返回空数组的判断失效,会无限拉取。稳妥的做法是轻易云适配器内置「连续空页超过N次自动熔断」机制,或者把pageSize控制在200以内。
• 踩坑2:增量漏单。按open_vouchdate_begin拉取时,如果上游时区与下游不一致,凌晨单据容易漏。解决方案是把时间窗向后延长2小时,并用pubuts做二次补偿。
• 踩坑3:状态卡在APPROVING。审批中的订单没有后续状态推送,集成侧会一直显示「审批中」。这里容易翻车的点是忘记监听auditDate字段,一旦审批完成应主动拉取最新状态。
• 踩坑4:赠品行重复计入应收。orderProductType=GIFT的行oriSum非零,直接汇总会把赠品算进应收。务必在映射器里加过滤条件orderProductType != 'GIFT'。
• 踩坑5:批次字段缺失。对启用批次管理的商品,若batchNo为空,下游WMS无法出库。在轻易云里可在字段映射器配置「非空校验」,缺失即告警。

何时选用

本接口适用于CRM与ERP销售订单双向同步、订单状态看板、订单明细行级分析与库存预占等场景。不适用于:仅需订单表头聚合统计(应改用isSum=true)、实时单条订单查询(建议走单据详情接口)、以及对历史全量数据的一次性迁移(应走批量导出)。当业务需要按明细行做商品、批次、仓库维度对照时,本接口是最佳选择。