金蝶云星空「其他出库单」查询接口字段手册权威教程(P2-342)

这个接口解决什么问题

在零售与电商供应链集成场景里,「其他出库单」(调拨、领用、报废、样品出库等非销售类出库)是连接金蝶云星空 ERP 与前端电商/OMS 系统的关键凭证。借助本接口,可逐行拉取金蝶侧出库明细,与管易云的销售订单、退货单、平台单号精准对账与回写,实现「单据级」可追溯。它解决了三个痛点:① 非销售出库如何纳入统一对账;② 退货出库与销售订单如何双向关联;③ 多组织、多货主下的过滤与增量。

接口能力总览

• 认证方式:金蝶云星空私有化部署下的 OAuth/Session 鉴权,轻易云适配器封装后,只需配置租户与账套即可调用,无需手动管理 token。
• 请求方式:POST /kapi/v2/bill/query,底层 API 为 executeBillQuery。
• FormId:固定为 STK_MisDelivery(其他出库单)。
• 请求结构:otherRequest 包含 Limit、StartRow、TopRowCount、FilterString、FieldKeys 五大关键参数。
• 分页模式:基于 Limit/StartRow 的传统分页,平台变量 {{PAGINATION_PAGE_SIZE}} 与 {{PAGINATION_START_ROW}} 自动注入。
• 增量模式:默认过滤 FApproveDate>='{{MINUTE_AGO_20|datetime}}' AND FStockDirect='GENERAL',按审核日期滚动并限定库存方向,定时任务 */6 * * * * 每 6 分钟拉取。
• 响应结构:逐行返回,FID 为主键、FEntity_FEntryID 为行主键、FBillNo 为业务单据号;autoFillResponse:true 由平台自动补全。

典型字段映射

在轻易云上如何配置

在轻易云数据集成平台里,该接口被封装为「金蝶云星空查询适配器」。

1. 选择数据源:源系统选 Kingdee Cloud,目标系统留空(Target = 写入空操作,纯查询策略)。
2. 配置 FormId:在适配器表单中填写 STK_MisDelivery,平台自动加载字段元数据。
3. 设置过滤条件:FilterString 直接写 FApproveDate>='{{MINUTE_AGO_20|datetime}}' AND FStockDirect='GENERAL',平台变量会自动按执行时刻计算。
4. 配置分页:Limit 取 {{PAGINATION_PAGE_SIZE}}(默认 2000),StartRow 取 {{PAGINATION_START_ROW}},轻易云的字段映射器会自动维护游标。
5. 元数据声明:在 metadata.json 中声明 number=FBillNo、id=FEntity_FEntryID、idCheck=true、autoFillResponse=true。
6. 定时调度:Cron */6 * * * *,搭配增量窗口 MINUTE_AGO_20,留出 20 分钟审核时延容错。

跨方案实战要点

1. 逐行查询 vs 逐单查询:逐行粒度更细,适配多行退货、组合出库,但数据量会膨胀 5-10 倍,务必评估存储与下游消费能力。
2. 审核日期 > 业务日期:增量字段必须用 FApproveDate,而非 FDate,否则会出现「漏单」。
3. 库存方向过滤不可省:FStockDirect='GENERAL' 是金蝶侧的硬性业务约定,缺少会导致调拨、寄售等干扰数据混入。
4. 业务单据号是跨系统锚点:在轻易云的字段映射器里,优先用 FBillNo 做幂等键,而非 FID,因为业务侧更习惯用单据号对账。
5. 多组织隔离:若客户有多个库存组织,务必在 FilterString 追加 FStockOrgId IN (...),否则会拉错组织数据。
6. 外部码优先:管易侧物料、仓库编码通常存放在 F_UQRW_BaseProperty*,用它们做映射,比 FMaterialId.FNumber 更直接、更稳。

踩坑复盘

• 坑 1:增量「漏单」——用 FDate 做增量窗口,导致审核延迟的单据被跳过。稳妥的做法是统一用 FApproveDate,并保留 MINUTE_AGO_20 的时延缓冲。
• 坑 2:单据类型编码误读——XSCKD01_SYS 到 XSCKD08_SYS 含义重叠(标准出库出现多次),若按字符串前缀过滤极易漏单。建议在轻易云的字段映射器里维护一张枚举表,显式列出允许的类型。
• 坑 3:嵌套字段取错——FMaterialId 是对象,必须写 FMaterialId.FNumber 才能拿到编码。轻易云的字段映射器会自动展开嵌套,但手写脚本时要小心。
• 坑 4:游标不递增——StartRow 写成固定值会导致分页死循环,这里容易翻车。务必使用平台变量 {{PAGINATION_START_ROW}}。
• 坑 5:退货场景对不上——退货出库必须带 F_UQRW_THDH,若客户业务侧退货单先于其他出库单审核,会出现「孤儿单」,需要在下游做容错关联。

何时选用

适用场景:管易/OMS 与金蝶云星空的供应链集成,需要逐行级出库明细做对账、退货关联、平台单号匹配、库存方向与组织维度过滤的纯查询场景。不适用:需要实时推送(秒级延迟)、写回金蝶、或非 STK_MisDelivery 单据(如销售出库单、调拨单)的场景。