这个接口解决什么问题

金蝶云星空 SAL_OUTSTOCK 销售出库单接口是供应链集成中最常用的出库类接口之一。在零售、贸易、电商等业态里,流量成交表、v2 仓库调拨单、其他出库单常常需要在简道云与金蝶之间双向流动。该接口负责把销售出库业务以标准单据形态写入金蝶,衔接库存、成本核算与财务记账,直接决定库存数据的准确性。

接口能力总览

认证方式:金蝶云星空采用基于应用 ID 与应用密钥的 OAuth2 风格签名鉴权,通过 /k3cloud/ 入口调用 WebAPI,接口标识 SAL_OUTSTOCK。

请求结构:JSON 封装的 Model 对象,内含 FBillTypeID、FBillNo、FDate、FSaleOrgId、FCustomerID、FStockId、FEntity(明细数组)等字段。

响应结构:Response 包含 Result 与 Status 等字段;成功时返回 Result.ResponseStatus.IsSuccess=true 及单据内码 FID,失败时返回 Errors 数组。

分页/增量模式:查询接口支持 Limit + Offset 分页;增量同步通常以 updateTime 或单据日期为游标,首次部署用全量,后续走增量。

字段名	类型	含义	实战注意事项
FBillNo	String	单据编号	业务主键,建议加前缀避免重号
FBillTypeID	String	单据类型	销售出库默认 XSCKD01_SYS
FDate	Date	出库日期	日期时间格式化为 yyyy-MM-dd
FSaleOrgId	String	销售组织	用组织编码 FNumber 传值
FCustomerID	String	客户	走客户编码映射表
FStockId	String	出库仓库	走仓库编码映射表
FOwnerTypeIdHead	String	货主类型	固定常量 BD_OwnerOrg
FOwnerIdHead	String	货主	通常与销售组织一致
FEntity	Array	明细行	子表单整体映射
FMaterialId	String	物料	必须先建物料编码映射
FRealQty	Number	实发数量	与库存单位保持一致
FStockUnitId	String	库存单位	一般取物料基本单位
FNote	String	备注	单据级说明,行级用 FEntryNote

在轻易云数据集成平台里,金蝶云星空销售出库单已有成熟适配器,通常这样配置:

数据源选择:源端选简道云(流量成交表、v2 调拨单或其他出库单),目标端选金蝶云星空的 SAL_OUTSTOCK Save 接口。
字段映射器:在轻易云的字段映射画布里,把源端子表单字段拖到 FEntity 数组下,平台会自动按数组下标展开。FMaterialId、FCustomerID、FStockId 这些外键字段,映射器会调用轻易云自带的编码映射函数,根据编码对照表自动替换。
调度编排:基础资料策略建议 30 分钟轮询,业务单据 10 分钟轮询;轻易云的调度器原生支持按 updateTime 增量。
异常处理:开启轻易云的重试与死信队列,单据失败不会阻塞后续批次,失败原因会在轻易云的运行日志里完整保留。

基础资料先行:供应商、客户、仓库、币别必须先于业务单据同步,否则外键映射会空值报错。
多源单据统一出口:流量成交表、调拨单、其他出库单都可能生成销售出库,务必通过路由字段(是否退货、单据类型、调拨类型)分流入仓。
编码映射三件套:物料、客户、仓库的编码映射表是生命线,轻易云里通常用一张独立的对照表来维护。
常量与组织分支:结算币别 PRE001、货主类型 BD_OwnerOrg、单据类型 XSCKD01_SYS 这些常量要在轻易云的常量池里集中管理;客户/部门字段常常需要按销售组织做条件分支。
审核状态过滤:简道云源单必须勾选"已审核"才允许下发,这是减少金蝶侧脏数据的关键。
日期与单据号约定:日期统一格式化为 yyyy-MM-dd;单据号建议加业务前缀(如 XSO-、DB-),避免与金蝶自有单据撞号。

空指针 FK 报错:客户编码未建映射就下发,金蝶返回 FMaterialId/FStockId 不能为空。稳妥做法是轻易云里给每个外键字段挂一个"空值兜底"处理器,缺值直接进死信队列。
单据号重复:简道云与金蝶同时生成同一单号导致提交失败。建议在轻易云里启用单据号前缀规则,把来源系统作为前缀的一部分。
明细行数量不一致:源端子表单有 5 行,目标只入了 3 行,通常是 FEntity 数组映射时下标错位。在轻易云里要明确选择"数组整体映射"而非按行号逐条映射。
日期时区偏差:简道云返回的 updateTime 带了 8 小时时区,直接写入金蝶导致单据日期偏移一天。轻易云的日期格式化器默认会做时区归一化,但要确认源端时区设置。
审核未通过脏数据:简道云端未审核的单据也下发到金蝶,导致金蝶出现大量未审核单据。务必在轻易云的源端过滤条件里加"审核状态=已通过"。

销售出库单接口适合零售、电商、贸易等业态的销售履约与库存出库场景,流量成交、调拨出库、赠品出库都可收敛到该接口;不适合纯生产领料、纯调拨(无客户维度)等场景,后者请走其他出库单或直接调拨单接口。