管易云与金蝶云星空供应链集成接口字段手册权威教程
这个接口解决什么问题
在电商零售企业的实际业务里，管易云负责前端电商交易与库存流水，金蝶云星空负责后端财务与生产计划；两者之间的供应链单据如果不打通，就会出现库存账实不符、预测缺料、收付款重复入账等问题。本文聚焦的接口集，正是要把采购单、发货单、退货单、盘点单、费用流水等 23 类单据在两套 ERP 之间双向贯通，形成可观测、可重放、可分流的稳定集成链路。
接口能力总览
源端管易云/管易云·奇门以 gy.erp.*.get 风格的 API 暴露单据（采购单、调拨单、盘点单、发货单、退货单、费用流水等），按 approve_date/delivery_date/create_date 等时间字段做增量拉取；首次部署或历史回填走全量。目标端金蝶云星空通过开放平台写入 PLN_FORECAST、SAL_OUTSTOCK、SAL_RETURNNOTICE、STK_TransferDirect、STK_MISCELLANEOUS、收款单、付款单等业务对象。认证采用 AppKey/AppSecret + 租户标识的 OAuth 风格签名；请求体以 Form/JSON 为主，响应统一返回 result 码 + data 列表；分页通过 page_no/page_size 控制，单页建议 50-200 条。增量游标可基于「最后修改时间」落库到轻易云的调度上下文里。
典型字段映射
| 字段名 | 类型 | 含义 | 实战注意事项 |
|---|---|---|---|
| code / FBillNo | 字符串 | 单据编号 | 跨系统透传时建议加货主后缀，避免同号冲突 |
| approve_date / FDate | 日期 | 业务日期 | 增量游标字段，必须统一时区与格式 |
| shop_code | 字符串 | 店铺代码 | 需与仓库联合映射成销售组织，单字段会撞码 |
| warehouse_code | 字符串 | 仓库编码 | 映射到 FStockId/FStockOrgId，差仓位要补全 |
| sku_code / FMaterialId | 字符串 | 物料编码 | 必须建物料映射表，未映射的行要进死信队列 |
| qty / FQty / FRealQty / FReturnQty | 数值 | 数量 | 明细行数量，注意源单位与目标单位换算 |
| post_cost | 数值 | 物流成本 | 通过自定义字段 _qtr 写入，避免污染标准字段 |
| express_no | 字符串 | 物流单号 | 一对多行时合并写入 FLogisticsNos |
| supplier_code | 字符串 | 供应商编码 | 内采采购单需 CASE 映射到 FForeOrgId |
| category_name | 字符串 | 商品分类 | 用于 owner_org 货主判断（硬箱/配件 vs 软箱/包类） |
在轻易云上如何配置
在轻易云数据集成平台里，源端「管易云」与目标端「金蝶云星空」已经封装为标准适配器，调用 gy.erp.*.get 与 SAL_OUTSTOCK/Save 等接口时不需要手写签名与分页逻辑。字段映射器支持 DIRECT（直接透传）、TRANSFORM（函数/日期/CASE 转换）、COLLECTION（明细数组引用）、CONSTANT（常量）、SCRIPT（脚本，如 FTransferBizType 的调拨类型判断）五种类型；分流逻辑可以在策略的「过滤条件」里直接配置店铺+仓库组合的 CASE 表达式，或通过 Groovy/JS 脚本判断渠道（京东自营 vs 非京东自营）。商品同步到轻易云的空操作策略，本质是把商品分类预加载为货主联查数据源，供调拨单、退货单在 AfterSourceInvoke 钩子里跨策略查询。调度层面，轻易云允许为每个策略独立设置 Cron 与增量游标字段；异常处理上，单条失败默认进死信队列并触发告警，不会阻塞后续数据。
跨方案实战要点
- 商品主数据先行：管易商品→轻易云空操作策略必须先于调拨单、退货单运行，因为它承担了「分类→货主」的联查数据源角色。
- 店铺+仓库组合分流：发货单不能只按店铺分流，真实场景里同一店铺在不同仓库要走不同目标单据（如香港真诚仓库走直接调拨单，其他仓库走销售出库单）。
- 渠道分流要前置：京东自营的退货单走直接调拨单，非京东自营走销售退货单，过滤条件务必在源端拉取时就下发，避免下游做反向纠正。
- 增量字段按单据选：采购单用 approve_date，发货单用 delivery_date，商品用修改时间；不要全用 create_date，否则漏单率会很高。
- 财务策略分层调度：费用流水的历史与日常分两条策略，币别查询要先于财务策略运行做金额校验。
- 单据编号加货主后缀：同一张源单据落到多组织目标时，code 后拼
-owner_org可避免金蝶端报「单据编号重复」。
踩坑复盘
- 坑 1：商品货主没预加载：调拨单同步时 owner_org 取不到，直接走默认货主导致库存组织错位。稳妥的做法是先跑商品空操作策略 1-2 个周期，确认分类→货主映射表有数据再开启业务单据。
- 坑 2：店铺+仓库映射写成单条件 CASE：只写 shop_code→FSaleOrgId，结果同一店铺下不同仓库被错误归并。一定要用多条件 CASE 表达式或脚本判断。
- 坑 3：差仓位漏补全：京东自营退货单走调拨单时，调入仓库存在仓位差，没在映射层补全导致金蝶抛错。建议在 COLLECTION 映射后再加一层 TRANSFORM 兜底。
- 坑 4：增量游标用了 create_date：新增但未审核的单据被忽略，第二天被审核后下游账期对不上。应改用 approve_date 或 delivery_date。
- 坑 5：配件类 SKU 进入销售出库明细：发货单明细里的配件被一并同步，污染了销售出库的数量汇总。在 AfterSourceInvoke 里加配件 SKU 过滤即可。
何时选用
这套接口集适用于电商零售企业（多店铺、多仓库、多货主）做管易云与金蝶云星空的供应链打通场景，典型如：内采采购→预测计划、销售出库与退货按渠道分流、盘点盘盈盘亏自动生成其他出入库单、费用流水与销售收付款进入财务总账。不适用于纯生产制造、纯分销批发的轻量集成，也不建议在缺少主数据治理能力的组织里直接上线。