Visma Net 集成指南：使用 SkyPlanner APS 进行生产排程

• Visma Net ERP API。采用 REST，OpenAPI 规范仍以“Visma.net ERP API v1”为标题，包含 v1 和 v2 路径。基础 URL 为 https://api.finance.visma.net。旧域名 integration.visma.net 自 2026 年 2 月 1 日起限流，并将关闭（通知）。
• SalesOrder service v3 的地址为 https://salesorder.visma.net。v1 和 v2 销售订单端点已终止支持。
• 通过 Visma Developer Portal 提供的 webhooks。
• Background API。使用 erp-api-background 请求头可将耗时较长的调用加入队列，返回状态码 202 和任务 ID，并在结果就绪时发出通知。
• Visma Net 中的导入和导出方案，通过 CSV、Excel 或 SQL 数据提供程序一次性导入主数据。

该 API 不提供生产订单、工艺路线或工作中心端点，因为 Visma Net 中没有这些对象。排程数据来自物料、套件、订单和库存：

• GET /v1/inventory：库存物料和非库存物料，包括套件标志和物料类别
• GET /v1/KitSpecifications/{kitInventoryID}/{revisionID}：各修订版本的组件明细行
• GET /v1/kitassembly：现有装配单，可按类型和状态筛选
• SalesOrder service v3：需求及其要求日期和明细行
• GET /v1/inventorysummary/{inventoryNumber}：各仓库的现有库存量和可用库存量
• GET /v1/purchaseorder 和 GET /v2/PurchaseReceipt：在途物料和收货记录

所有列表端点均支持配合使用 lastModifiedDateTime 和 lastModifiedDateTimeCondition，以及 pageNumber 和 pageSize，因此每次同步都可以采用增量方式。

Visma Developer Portal 的 webhooks 涵盖了与排程相关的事件：

• Inventory Item Created、Updated 和 Changed
• Purchase Order Changed 和 Status Changed
• Sales Order Changed 和 Status Changed，正迁移至 SalesOrderService 发布方

Kit assembly 和 Kit specifications 不提供事件。SkyPlanner 使用 lastModifiedDateTime 筛选条件轮询这些数据，并在运行排程时轮询库存量。反向同步时，状态或排程发生变化，SkyPlanner 就会发送 webhook 通知。

1. 首次导入主数据。读取库存物料、物料类别，以及每个套件最新修订版本的 Kit specification。将每条组件明细映射为 SkyPlanner 中的物料。然后补齐 Visma Net 中没有的数据：工作中心、班次、含准备时间和运行时间的工序、准备时间矩阵以及工具需求。通过 CSV 或 Excel 导入这些数据。这是项目中工作量最大的部分。

2. 订单同步。选择一种需求模型：

• 销售订单驱动。套件物料尚未完成的销售订单行转为 SkyPlanner 订单，并以要求日期作为交期。
• 装配单驱动。在 Visma Net 中创建、状态为 On hold 的 Kit assemblies 转为 SkyPlanner 生产任务。

未结采购订单及其日期一并导入。SkyPlanner 将已订购物料视为在采购订单交货日期可用，并在采购订单标记为 Delivered 时更新库存。排程结合库存汇总数据，同时检查现有库存和待到货采购物料。

3. 排程回写。采用销售订单驱动模式时，SkyPlanner 会为每项已排程的生产任务创建一张类型为 Production 的 Kit assembly，设置套件物料、修订版本、仓库、数量和组件，并将装配单关联到销售订单行。装配日期设为计划完工日期。当 Autopilot 调整任务时间时，通过 PUT 在过账前更新日期。

Kit assembly 只有一个 Date 字段，因此各工序的具体时间保留在 SkyPlanner 中，Visma Net 则接收与销售和库存相关的日期。

4. 车间报工。操作员通过 Mobile Confirmations 或 Production Timer 记录作业，工时记录使排程保持最新。最后一道工序完成后，SkyPlanner 会调用 Kit assembly 的 release 操作进行过账。过账时记录产出和组件消耗，随后生成总账批次。工时按周汇总至 Employee time cards；对于项目驱动的作业，则汇总至项目交易。

5. 数据归属与冲突处理规则。上线前将这些规则明确记录下来：

修改 Kit specification 会生成新的修订版本。由于只有最新版本可用于组装，因此需要重新读取最新版本并更新映射。在装配单上手动修改的组件在 Visma Net 中仍然有效，因此 SkyPlanner 会在过账前回读装配单。

• 没有可导入的工艺路线。所有工序、准备时间和运行时间都需要在 SkyPlanner 中建立。请提前预估工作量并确定负责人。
• Advanced logistics。使用 Kit assembly 需要启用 Advanced logistics 功能组。如果使用 Standard logistics，则通过 Inventory receipt 和 Inventory issue 对产出过账。
• 修订版本锁定。已使用的 Kit specification 修订版本无法编辑，且只有最新版本可用于组装。
• 计量单位。Kit assembly 有自己的计量单位。导入时，需确保 SkyPlanner 中的数量采用与之匹配的计量单位。
• 无事件通知时采用轮询。套件不支持 webhook。请根据 lastModifiedDateTime 增量获取数据，不要全量重载，以免超出每小时请求限额。
• 使用当前端点。仅基于 api.finance.visma.net 和 SalesOrder service v3 开发集成。
• 租户审批。租户管理员批准应用之前，客户端凭据无法用于认证。请尽早安排这一步。
• 每周工时卡。工时卡需要 Advanced financials，按周记录。请按周汇总操作人员的工时，或将工时过账至项目交易。