Business Central 集成指南：使用 SkyPlanner APS 进行生产排程

集成使用 Business Central 自带的两个接口：

1. API v2.0 用于业务和库存数据，提供 items、itemVariants、itemLedgerEntries、locations、unitsOfMeasure、salesOrders、salesOrderLines、purchaseOrders、purchaseOrderLines、vendors、customers 和 employees。该接口不包含制造实体，因此生产数据通过第二个接口获取。
2. OData v4 Web 服务用于制造数据。在 Web Services 页面上，可以将任何 Business Central 页面发布为 OData v4 Web 服务。选择对象类型 Page、页面 ID 和服务名称，然后勾选 Published。端点随即生效，无需编写 AL 代码，也无需部署扩展。集成会发布已下达生产订单、Prod. Order Routing Lines、工作中心、机器中心和工艺路线的标准页面，通过 /ODataV4/Company('{name}')/{ServiceName} 提供访问。

发布的页面支持读写。Microsoft 文档指出：”If an editable page is exposed as a web service, the data in the underlying table can be accessed and modified by an OData call,”（如果将可编辑页面作为 Web 服务公开，就可以通过 OData 调用访问和修改底层表中的数据），更新则使用 PATCH。计划日期正是通过这种方式写回 Business Central，使用的页面和校验逻辑与计划员手动操作时相同。

不要使用 SOAP。Microsoft 已弃用 SOAP Web 服务，并在 2026 年第 2 波发布（v29）中移除了将 Microsoft UI 页面发布为 SOAP 服务的功能。

Business Central 支持通过 POST /api/v2.0/subscriptions 为 items 和 salesOrders 等 API v2.0 实体创建 Webhook 订阅。规则如下：

• 创建订阅需要完成握手：您的端点必须返回 validationToken，并使用 200 OK 状态码。
• 订阅在三天后到期。使用 PATCH 续订时，会再次执行握手。
• 通知包含资源路径、changeType 和您设置的 clientState，不包含完整记录。收到通知后，需再读取记录。
• 通知存在延迟：Business Central 在线版会在首次变更后等待 30 秒；如果这段时间内发生变更的记录超过 1,000 条，则会合并为一条 collection 通知。
• 在线版每个环境最多支持 200 个 webhook 订阅。

每隔几分钟，通过已发布的页面和 purchaseOrders 轮询生产订单、工艺路线行和采购订单。仅筛选未结订单并使用分页，可使请求数量远低于 Business Central 的限制。

状态或排程发生变化时，SkyPlanner 会发送 webhook，因此回写采用事件驱动方式。

1. 首次加载主数据。从已发布的页面读取状态为 Certified 的工艺路线和生产 BOM，以及工作中心和机器中心；从 API v2.0 读取物料和计量单位。将各个工作中心或机器中心映射到 SkyPlanner 工作中心时，需要明确建模方式：例如，一个下设三个机器中心的工作中心，是映射为一个工作中心组，还是三个工作中心。

2. 订单同步。从已发布的页面读取状态为 Released 的生产订单及其工艺路线行和组件；如果也对 Firm Planned 订单进行排程，则一并读取。从 API v2.0 读取未结采购订单行。SkyPlanner 将已订购物料视为在采购订单交货日期可用，并在采购订单标记为 Delivered 时更新库存，因此排程时会同时检查现有库存和在途采购。

切勿对状态为 Planned 的生产订单进行排程。Microsoft 指出，Business Central 会 “deletes them the next time you run planning.”（在下次运行计划时将其删除）。Planning Worksheet 继续生成供应建议，SkyPlanner 则根据实际产能对已确定的订单进行排程。

3. 排程回写。将标准 Prod. Order Routing 页面发布为 OData v4 Web 服务。对于引擎安排或调整过的每道工序，SkyPlanner 都会向对应的工艺路线行发送 PATCH 请求，并携带 If-Match ETag。请求会设置 Starting Date-Time 和 Ending Date-Time；如果工序转移到了备选机器，还会设置 Type 和 No.。

PATCH 会执行页面和表的触发器，因此 Business Central 会用自身逻辑校验字段，与计划员编辑 Prod. Order Routing 页面时完全一致。生产订单行的 Starting and Ending Date-Time 随之更新。数量、状态和成本仍由 Business Central 管理。

4. 车间报工。操作人员通过 SkyPlanner Mobile Confirmations 或 Production Timer 记录工作，工时记录使排程保持最新。产出仍可像以往一样，在 Business Central 中通过 Production Journal 或 Output Journal 申报。

如果希望全自动过账产出和消耗，则会添加一个标准 Business Central API 页面，用于产出日记账过账。之后，SkyPlanner 会按工序过账准备时间、运行时间和产出数量。过账会更新 Capacity Ledger Entries，最后一道工序的产出过账后，物料计入库存。

产出过账只能选择一个渠道。同时从 SkyPlanner 和 Business Central 的 Production Journal 过账会造成重复记录。

5. 数据归属与冲突处理规则。上线前应以书面形式明确以下规则：

冲突主要来自生产订单上的 Refresh 和 Replan 操作。Microsoft 文档指出：”If you use the Refresh action to recalculate production order lines, Business Central deletes the existing production order lines and calculates new lines.”（使用 Refresh 操作重新计算生产订单行时，Business Central 会删除现有行并计算生成新行。）Replan 也可能改变产能需求，而重新计算组件会 “deletes previous changes in the components.”（删除此前对组件所做的更改）。

将刷新后的订单视为新版本，重新同步，再由 SkyPlanner 重新排程。启用 Autopilot 后，SkyPlanner 会在生产发生变化时自动重新排程。

• 工艺路线中的单位。Setup Time 按每张生产订单计算，Run Time 按每件产出物料计算，两者各有自己的 Unit of Measure Code。Wait Time 和 Move Time 不占用工作中心产能。如果工作中心的单位为 Days，一天表示 24 小时，而不是八小时的班次。必须在导入时换算，否则所有时长都会出错。
• 日历未及时更新。只有针对计划期运行 Calculate Work Center Calendar 后，才会生成产能数据。首次加载前，请检查 Calendar Entries Available Until 字段。
• 机器中心产能未被计入。关闭 Consolidated Calendar 时，计划只考虑工作中心自身的产能：”The machine center capacity is excluded.”（不包括机器中心产能。）应直接读取机器中心产能，而不是依赖工作中心的汇总值。
• Capacity 和 Efficiency。Business Central 按 Run Time / Efficiency / Capacity 计算时长，计算生成的日历条目已包含这两个因素。将 Efficiency 映射到 SkyPlanner 工作中心效率时，只能应用一次，不要重复计算。
• Alternate Work Center 仅供参考。Microsoft 指出，它 “isn’t automatically included in planning processes.”（不会自动纳入计划流程）。请在 SkyPlanner 中明确将这些替代选项建模为替代工作中心。
• 限流。在线版按用户实施限制，一个服务主体计为一个用户：在 5 分钟的滑动窗口内最多允许 6,000 次 OData 请求，同时最多允许 5 个并发请求。每页最多 20,000 条记录，每个 $batch 最多包含 100 项操作，单项操作超过 8 分钟即超时。请求速率超限会返回 429。应使用批处理、分页和增量轮询，而不是每次重新加载全部数据。
• 许可证。制造功能仅在 Premium 体验中提供。Essentials 用户无法登录设置为 Premium 的公司。