金蝶云星空采购入库单对接积加ERP：跨方案实战字段手册

这个接口解决什么问题

在跨境电商与ERP的供应链集成中，金蝶云星空的采购入库单（PUR_ReceiveBill） 与积加ERP的其他入库/其他出库单之间的双向同步是库存一致性的核心环节。真实场景里，某跨境零售企业需要把金蝶作为财务与总仓枢纽，积加作为多渠道（亚马逊、美客多、独立站）订单与履约中心——采购入库、调拨差异、盘盈盘亏必须实时回流，否则账实差异会直接体现在结算报告与应收单上。

接口能力总览

• 认证方式：金蝶侧通常为 OAuth2 + 账套令牌（业务租户维度），积加侧多为 AppKey + 签名或自建网关 Token；调用前需在轻易云中预先配置好凭证并按业务租户隔离。
• 请求结构：金蝶查询接口（QueryBill / ExecuteBillQuery）基于 FormId + FilterString + FieldKeys；写入接口（Save / Submit / Audit）走标准单据体。积加侧多为 RESTful JSON 风格，支持 /api/inventory/otherIn、/api/inventory/otherOut 等端点。
• 分页/增量模式：金蝶靠 Limit + StartRow 分页，增量通常以 FApproveDate、FDate、FModifyDate 作为水位字段；积加侧按 last_update_time 游标分页，全量用于首期与对账修复。
• 响应结构：金蝶返回 Result.Result（单据集合） + Result.Status；积加返回 { code, data, message }，需关注 code≠0 时的部分成功情况。

典型字段映射

以「金蝶采购入库单 → 积加其他入库单」为主线，附调拨与查询类接口要点：

在轻易云上如何配置

在轻易云数据集成平台里，这个接口的封装走的是金蝶云星空适配器 + 积加ERP适配器双适配器组合：

1. 数据源/目标源：分别选择「金蝶云星空」与「积加ERP」，填入凭证。
2. 策略模板：轻易云内置「金蝶采购入库单 → 积加其他入库单」「调拨双向」「仓库/客户查询」等模板，可一键派生 30 条策略的雏形。
3. 字段映射器：通过可视化拖拽完成上述映射，编码映射表（物料、仓库、客户、单位）在「主数据管理」模块集中维护；平台支持变更后自动同步到所有引用策略。
4. 调度与水位：基础资料类策略默认 30 分钟一跑，业务单据类 10 分钟一跑；增量水位在轻易云里通过 LAST_SYNC_TIME 全局变量自动注入 FilterString。
5. 异常与告警：单条失败 → 死信队列 + 重试 N 次；策略级异常走钉钉告警（对应策略30）。

跨方案实战要点

从多个跨境电商客户的方案里，我们提炼出以下共性经验：

1. 基础资料先行：金蝶物料、仓库、客户必须先于业务单据同步；否则采购入库单里 FMaterialId.FNumber 会找不到对应 sku，整张单据直接失败。
2. 增量水位选 FApproveDate 而非 FCreateDate：跨境场景下补单、驳回再审很常见，按审核日期取增量能保证最终一致性。
3. 编码映射集中维护：物料、仓库、客户、店铺→金蝶客户四套映射表一定要放在平台主数据模块统一管理，散落在每个策略里后期维护是灾难。
4. 区分入库与退货场景：同一张 PUR_ReceiveBill 在跨境业务里可能产生「其他入库」与「其他出库」（红字）两条流向，需要按单据类型/状态过滤，否则库存会被虚增。
5. 店铺→客户映射：亚马逊各站点、美客多、独立站每个都要建独立的金蝶客户档案，否则销售出库、收款单、其他应收单全部串户。
6. 调度错峰：基础资料 30 分钟、业务单据 10 分钟，但日期范围报告相关策略（销售出库、收款、其他应收）务必在结算报告生成完成后再跑，否则会漏数据。

踩坑复盘

1. 数量精度漂移：金蝶支持 4 位小数，积加某些老版本只接受 2 位——某客户出现过 0.0001 件被四舍五入掉导致账实差。稳妥的做法是在轻易云字段映射器里配置显式 ROUND(qty, 2) 清洗。
2. 仓库编码空值：调拨单的调出/调入仓库任一为空时，金蝶写入会返回成功但实际单据无库存影响——很容易翻车。建议在源端过滤 FStockOutOrgId 与 FStockOrgId 非空的策略再同步。
3. 店铺编码串户：把美客多店铺误映射到亚马逊金蝶客户，导致整月收款单全部进了错误组织。这里容易翻车，稳妥的做法是映射表里强制要求「平台+店铺」组合作为唯一键。
4. 幂等失败重复跑批：增量任务并发触发时，同一 FBillNo 被推送两次。轻易云的幂等键机制默认以单据号为主键，但跨系统主键大小写不一致会失效——务必开启严格匹配模式。
5. 日期范围报告延迟：亚马逊结算报告通常在交易完成后 7-14 天才生成，过早拉取会漏单。建议在调度里加入「报告可用性检测」环节，未生成则跳过而非报错。

何时选用

适用场景：跨境电商 ERP（积加）与国内总账 ERP（金蝶云星空）之间的库存与销售单据双向同步，特别是多渠道、多店铺、多币种的零售业务。不适用：纯生产制造场景（应走 MES 路线）、无金蝶/积加系统的企业、仅有单边数据流向的轻量同步需求。