SAP Business One 集成指南：对接 SkyPlanner APS 生产排程

SAP Business One 提供三种集成接口。对于云端排程系统，默认使用 Service Layer。

集成方式	说明	APS 集成适用性
Service Layer	REST/OData API。/b1s/v1 使用 OData v3，/b1s/v2 使用 OData v4。可在基于 SAP HANA 的 SAP Business One 上运行；从 10.0 PL01 起，也支持 Microsoft SQL Server。	首选方式。使用 HTTP 和 JSON，可从云服务调用。
DI API	Windows COM 库。生产订单对应 ProductionOrders 对象，存储在 OWOR 表中（对象类型为 202）。	适用于旧有中间件或本地部署的中间件。需要 Windows 主机。
Integration Framework (B1if)	SAP 用于单据级集成场景的中间件。	如果合作伙伴已在运行 B1if 集成场景，可采用此方式。

身份验证

Service Layer 采用会话认证。通过 POST /b1s/v1/Login 提交 CompanyDB、UserName 和 Password，即可获得 B1SESSION cookie（负载均衡部署还可选用 ROUTEID）。默认 SessionTimeout 为空闲 30 分钟。每次同步结束后，应显式调用 Logout。请创建专用的 B1 集成用户，确保从 SkyPlanner 写入的每项变更都能在变更日志中追溯。

用于生产排程的 Service Layer 实体

数据	Service Layer 实体
物料及计划数据	Items
物料清单和工艺路线阶段	ProductTrees（Lines、Stages）
设备、人工及其他资源	Resources, ResourceGroups
生产订单	ProductionOrders（Lines、Stages）
各仓库库存	Items 库存数据、Warehouses
未结采购订单及交货日期	PurchaseOrders（DocumentLines：未清数量、ShipDate）
基于采购订单的收货	PurchaseDeliveryNotes（采购收货单，对象类型为 20）
生产发料	InventoryGenExits
生产收货	InventoryGenEntries
Webhook 配置	EventSubscriptions, EventNotifications

默认每页返回 20 条记录。可通过 Prefer: odata.maxpagesize 请求头（或 PageSize 配置项，该配置项位于 b1s.conf 中）增大每页记录数，并按 odata.nextLink 继续读取。使用 $expand 可在一次调用中获取生产订单的明细行和阶段；批量回写时使用批处理请求。

事件与 webhook

从 SAP Business One 10.0 FP 2602 起，Service Layer 支持 webhook，默认关闭。需通过 CompanyService_UpdateAdminInfo（EnableWebhook = tYES）为各公司分别启用。随后调用 POST EventSubscriptions，提交以下三部分内容：

• 一个 WebhookURL
• 一个 AuthenticationType：可选 None、Basic、HMAC 或 OAuth，默认为 HMAC
• 一个包含业务对象和事务类型的 EventCollection

WebhookURL 必须使用 HTTPS，且证书须与主机匹配。EventSubscriptionsService_GetEventCatalog 可列出可订阅的事件。Webhook Messenger Service 必须处于运行状态。

旧版本需采用定时轮询（参见下文关于 UpdateDate 的注意事项）。SBO_SP_TransactionNotification 是数据库级校验钩子，并非事件投递通道。

1. 首次加载主数据。读取 Resources、ResourceGroups、Procurement Method 为 Make 的 Items，以及对应的、包含阶段信息的 ProductTrees。将每个设备资源映射到 SkyPlanner 中的一个工作中心。在首次同步订单前，与计划员一起核对清单。

2. 订单同步。读取状态为 Planned 和 Released 的 ProductionOrders，通过 $expand 展开明细行和阶段。B1 生产订单包含从 BOM 获取的工艺路线阶段，计划员可以在订单创建后修改订单。因此，应使用订单中的阶段，而不是 BOM 中的阶段。一张生产订单只生产一种产品，因此多层级产品的每个层级都对应一张生产订单。将这些订单关联起来，让 SkyPlanner 先安排子件生产，再安排父件生产。

同时，将未结 PurchaseOrders 明细行及其未清数量、交货日期同步到 SkyPlanner 的采购订单端点。SkyPlanner 将已订购物料视为在采购订单交货日期可用。在 B1 中，采购收货单（PurchaseDeliveryNotes）过账后才会产生库存变动。集成程序读取这些收货单，在 SkyPlanner 中将已收货数量标记为已交付，并保留剩余未交付数量。分批收货只计入一次，物料检查同时考虑现有库存和待到货供应。

3. 排程回写。排程发生变更时，SkyPlanner 的 webhook 会触发通知。集成程序通过 PATCH /b1s/v1/ProductionOrders({DocEntry}) 写入新的 StartDate 和 DueDate，并更新订单资源行上的 StartDate 和 EndDate（资源行为 ProductionOrderLines），使每个阶段都有排定的时间区间。请求体只包含由 SkyPlanner 负责维护的字段，多张订单合并到一个 $batch 请求中。随后，B1 用户即可在生产订单和 Resource Capacity 窗口中看到排定的日期。对于无法使用 Service Layer 的部署，可由本地服务通过 DI API 的 ProductionOrders 对象执行相同更新（调用 GetByKey、设置日期、调用 Update）。

4. 车间报工。操作员通过移动端报工或生产计时器在 SkyPlanner 中记录作业。每条工时记录都会转换为一次 POST /b1s/v1/InventoryGenEntries，用于记录完工数量（生产收货），以及一次 POST /b1s/v1/InventoryGenExits，用于记录组件消耗和资源工时（生产发料）。

每个单据行的 BaseType 均为 202，BaseEntry 设置为生产订单的 DocEntry；发料行还需填写对应组件行或资源行的 BaseLine。分批完成的数量在记录时即过账，启用批次或序列号管理的物料需填写相应号码，且订单必须处于 Released 状态。

SkyPlanner 工时记录的 ID 会保存在 B1 单据上，因此事件重试不会导致重复过账。过账失败时，系统会重试并报告错误，而不是直接丢弃。

5. 数据管理权与冲突处理规则。编码前先约定以下规则：

• B1 负责管理物料、BOM、数量和仓库，以及创建订单。
• SkyPlanner 负责管理生产顺序、开始和结束时间，以及工作中心分配。
• 如果两边都修改了订单日期，则以 SkyPlanner 下一次运行的结果为准，除非计划员已在 SkyPlanner 中锁定该生产任务。
• B1 中的订单关闭或取消后，对应生产任务会从排程中移除。