Katana 集成指南：使用 SkyPlanner APS 进行生产排程
本指南面向顾问和 IT 团队，介绍如何将 Katana Cloud Inventory (Katana MRP) 连接到 SkyPlanner APS。SkyPlanner 通过公开的 Katana API 与 Katana 进行双向集成：
- 将制造订单、工序行、产品配方、生产工序、资源、库存和采购订单导入 SkyPlanner。
- 将排程顺序回写到 Katana 的 Schedule 选项卡，并为每份制造订单写入生产截止日期。
- 将工序状态和实际用时回写到工序行。
- Katana Webhook 向 SkyPlanner 通报数据变更，SkyPlanner Webhook 则在排程发生变化时即时推送。
在实施阶段，SkyPlanner 团队会根据您的 Katana 配置设置集成，并在上线后提供支持。本指南面向希望参与集成，或希望参照 SkyPlanner 的 REST API 文档（API 参考）自行开发的顾问和开发人员。
Katana API
Katana 是一款多租户云产品，因此所有客户使用的 API 都相同。这是一套 v1 版本的 REST API，地址为 https://api.katanamrp.com/v1，OpenAPI 3.0 规范位于 https://api.katanamrp.com/v1/openapi.json。相关文档见 Katana Developer Hub。
排程所需的端点如下：
- 主数据：
/products、/materials、/variants、/recipe_rows、/bom_rows、/product_operation_rows。 - 订单：
/manufacturing_orders、/manufacturing_order_operation_rows、/manufacturing_order_recipe_rows、/manufacturing_order_productions。 - 排序：
/manufacturing_order_rerank。 - 供需：
/inventory、/purchase_orders、/purchase_order_rows、/sales_orders、/sales_order_rows。
API 不提供 /resources 端点。资源以 resource_id 和 resource_name 字段的形式出现在产品工序行和制造订单工序行中。
身份验证与限制
身份验证使用 API 密钥作为 Bearer 令牌：Authorization: Bearer <api key>。在 Settings > API > Add new API key 中创建密钥。（来源）
设计同步方案时需考虑以下限制：
- 默认情况下，Katana API 每 60 秒允许 60 次请求（来源）
- 超过此限制时，API 会返回 429，并附带
Retry-After。X-Ratelimit-Remaining表示剩余可用请求数。 - 列表端点会分页返回结果，并支持按更新日期筛选，从而保持较小的增量同步数据量。
SkyPlanner 的 REST API 使用 API 令牌进行身份验证（SkyPlanner Settings > API），并提供 Swagger/OpenAPI 文档。集成教程会引导您完成最初的 API 调用。
Webhook
通过 POST /webhooks 注册 Webhook，提供一个 HTTPS URL 和需要订阅的事件。（来源）排程相关的实用事件包括：
manufacturing_order.created、.updated、.deleted、.in_progress、.blocked、.donemanufacturing_order_operation_row.created、.updated、.in_progress、.paused、.completedcurrent_inventory.material_updated、.material_out_of_stockpurchase_order.*和purchase_order_row.*，包括收货事件product.*、product_recipe_row.*和sales_order.*
事件载荷很精简：仅包含资源类型、动作和一个 href。接收端通过 href 获取完整对象。每次投递都带有用于验证的 x-sha2-signature 请求头（HMAC SHA-256）。您的端点必须在 10 秒内返回 20X 响应；Katana 会重试三次，分别在 30 秒、2 分钟和 15 分钟时进行。
数据映射
| Katana 对象（端点） | SkyPlanner 对象 | 方向 | 频率 |
|---|---|---|---|
产品、物料、变体（/products、/materials、/variants） | 产品和物料 | Katana → SkyPlanner | 首次加载，之后由 Webhook 触发 |
产品配方 / BOM（/recipe_rows、/bom_rows） | 产品结构、子产品 | Katana → SkyPlanner | 首次加载，之后由 Webhook 触发 |
生产工序（/product_operation_rows）：类型、资源、用时 | 工艺步骤及其工时、准备时间 | Katana → SkyPlanner | 首次加载，之后在变更时更新 |
资源（工序行中的 resource_id、resource_name） | 工作中心、工作中心组 | Katana → SkyPlanner | 首次加载及新增资源时 |
制造订单及其工序行（/manufacturing_orders、/manufacturing_order_operation_rows） | 订单和生产任务 | Katana → SkyPlanner | 通过 Webhook 实时同步 |
制造订单用料（/manufacturing_order_recipe_rows） | 各生产任务的物料 | Katana → SkyPlanner | 通过 Webhook 实时同步 |
库存、含到货日期的采购订单（/inventory、/purchase_order_rows） | 现有库存和待到货物料 | Katana → SkyPlanner | 通过 Webhook 实时同步 |
销售订单的 delivery_date（/sales_orders） | 订单交期、客户优先级 | Katana → SkyPlanner | 通过 Webhook 实时同步 |
制造订单顺序（POST /manufacturing_order_rerank） | 未结制造订单的排程顺序 | SkyPlanner → Katana | 排程变更时 |
制造订单的 production_deadline_date（PATCH /manufacturing_orders/{id}） | 计划完成时间 | SkyPlanner → Katana | 排程变更时 |
工序行的 status、total_actual_time（PATCH /manufacturing_order_operation_rows/{id}） | Mobile Confirmations、工时记录 | SkyPlanner → Katana | 记录作业时 |
| Katana 中无对应数据 | 班次、缺勤、准备时间矩阵、工具、操作人员数量、备选工作中心 | 在 SkyPlanner 中维护 | 实施阶段设置 |
集成模式
1. 首次加载主数据。分页读取产品、物料、变体、配方行和产品工序行，并控制请求频率，确保不超过限流阈值。根据工序行中去重后的资源创建 SkyPlanner 工作中心，并保持 1:1 的键值映射。由于 Katana 没有资源日历，需在 SkyPlanner 中为每个工作中心设置班次、休假和加班。
2. 订单同步。订阅制造订单、工序行、库存和采购订单事件。每次收到事件后，通过其 href 获取对象并更新生产任务。SkyPlanner 将已订购物料视为在采购订单交货日期可用，并在采购订单收货时更新库存。每晚按更新日期筛选数据并进行核对，以补齐遗漏的事件。
3. 排程回写。通过两次调用将计划写入 Katana：
- POST
/manufacturing_order_rerank“moves one or more manufacturing orders to an exact place in the production schedule”（将一份或多份制造订单移至生产排程中的指定位置）。每次请求最多接受 250 份未结制造订单，可将其放在最前、最后，或指定制造订单的前面或后面。（来源） - PATCH
/manufacturing_orders/{id}用于设置production_deadline_date。只有关闭该工厂地点的截止日期自动计算功能后，Katana 才接受这一设置。（来源）
重排顺序的影响不止于列表显示。在 Katana 中，”higher-priority MOs reserve required materials and subassemblies first”（优先级较高的制造订单会优先预留所需物料和子装配件），因此 SkyPlanner 的排程顺序也决定了 Katana 中哪份制造订单优先获得库存。
4. 车间报工。操作人员通过 SkyPlanner Mobile Confirmations、Production Timer 或 Quick Log Mode 记录作业。SkyPlanner 将状态和实际用时写入制造订单工序行。如果工厂选择继续使用 Katana Shop Floor App，SkyPlanner 则读取工序行事件。每家工厂应选定一种报工渠道。
5. 数据归属与冲突处理规则。上线前应书面明确以下规则：
| 数据 | 主管系统 |
|---|---|
| 产品、配方、生产工序、库存、采购、销售订单 | Katana |
| 工序顺序、开始和结束时间、各工序的工作中心 | SkyPlanner |
| Schedule 选项卡中的制造订单排序及生产截止日期 | SkyPlanner，回写至 Katana |
| 班次、缺勤、准备时间矩阵、工具、备选资源 | SkyPlanner |
| 工序状态及已记录工时 | 仅用一个通道，在范围评估时确定 |
典型项目步骤
实施通常在开始进行上线配置后数周内完成。在此之前，您可以使用从 Katana 导出的自有 CSV 数据进行 30 天免费试用，例如 Make 页面上的 Tasks 列表。
项目本身包括以下步骤：
- 套餐与密钥。确认 Katana 套餐包含 API 和 Manufacturing Management，并创建 API 密钥。
- 截止日期模式。商定关闭该工厂地点的自动截止日期功能，由 SkyPlanner 统一管理生产截止日期。
- 映射。确定映射表、资源键、数据管理权规则及报工通道。
- 初始导入。导入产品、产品变体、配方、生产工序及资源。
- 事件同步。为订单、工序、库存和采购订单配置 Webhook，并在每晚核对数据。
- 在 SkyPlanner 中设置约束。配置班次、准备时间矩阵、工具、操作人员数量及备选工作中心。
- 回写。先回写排序和截止日期，再回写工序状态及工时。
- 并行测试与上线。将 SkyPlanner 中的日期与当前 Schedule 选项卡中的日期进行比较，修正主数据，然后启用回写。
Katana 集成需要提前考虑什么
- 截止日期模式会覆盖已有日期。“Once automatic mode is enabled, all manual deadlines will be overwritten and cannot be restored.”（一旦启用自动模式，所有手动设置的截止日期都将被覆盖，且无法恢复。）在项目启动时一次性确定模式。
- 没有资源日历。不要根据单一的 Weekly throughput 值推算班次。请在 SkyPlanner 中为每个工作中心分别设置班次。
- 资源仅出现在工序行中。保持 Katana 中的资源名称不变，因为这些名称是关联 SkyPlanner 工作中心的键。
- 时间单位。
planned_time_parameter的单位为秒：对于 per-unit 工序，它表示单件用时；对于 process、setup 和 fixed 类型，它表示总用时。必须正确映射类型，否则时长会出现与数量成倍数关系的偏差。 - 按订单生产的分组。重新排序时，关联同一销售订单的制造订单（MO）会保持在一起，因此应将其作为一组安排顺序。
- 重新排序的行为已变更。自 2026 年 10 月 7 日起，rerank 端点会将订单准确放到请求指定的位置。按旧行为开发的集成需要重新测试。（来源）
Katana 集成由谁配置和支持
配置工作涵盖您的资源、生产工序、订单流程和截止日期模式，还会补充 Katana 中没有的信息：班次、准备时间矩阵、工具、操作人员数量及备选资源。
- SkyPlanner 团队在上线配置阶段负责配置集成，并在上线后提供支持。每家工厂在 Katana 中设置资源和工序的方式都不同，这些具体经验会融入集成配置。
- 您的 Katana 顾问或集成合作伙伴也可以开发集成。SkyPlanner 提供 REST API、Swagger/OpenAPI 文档及 Webhook。
- 您自己的开发人员也可以使用 API 令牌在此基础上开发。有 API 令牌即可开始，SkyPlanner 团队会在需要时协助。有关采购订单、产品与物料 API 等内容的产品文档，请参阅 SkyPlanner 文档。
SkyPlanner 每月 199 € 起，包含 5 个工作中心，按月计费。我们会根据您的流程和需求，提前为集成及所选套餐一并报价，让您在开始前了解全部费用。您可以查看价格和功能，并在 Katana 生产排程页面了解它与 Katana 自带排程功能的区别。集成概览见 Katana 页面，其他 ERP 的集成请参阅 ERP 集成中心。
制造企业对 SkyPlanner 的评价
2 小时每周节省的时间
“SkyPlanner 让我们的生产计划告别了 Excel 表格，实现了实时生产优化。”
Kalle Kalliomäki，供应链专员
UTU · 配电盘与开关设备
生产计划工作每周节省 2 小时，新的工作队列只需数秒即可下达到产线。
+90%生产效率提升
“生产效率提高了 90%。”
Abdul Rucyinga，IT 负责人
Laboratory & Allied · 制药
生产效率提高了 90%，为所有工作中心制定覆盖三个月的优化计划，用时不到 30 分钟。
减少缺料造成的停工
“SkyPlanner 为我们带来的价值在于，它是一款在日常工作中真正实用的工具，尤其是在确定交货日期方面。”
Tommi Männistö，生产计划经理
Eskomatic · 机械加工承包
自动负荷排程让交货日期更准确，因缺料造成的停工也大幅减少。
数千张自动完成排程的工单
“我们对生产的掌控与以往大不相同，对产能的了解也达到了全新的水平。”
Hannu Ryynänen，首席执行官
Mamec · 工业搅拌机、泵及高科技产品代工
数千张工单自动完成排程，全公司都能实时了解生产情况。
常见问题
Katana 有 API 吗？需要哪个套餐？
有。Katana 提供公开的 REST API v1，并附有 OpenAPI 3.0 规范。其定价页面列明，Free 和 Advantage 套餐包含 API 访问权限。身份验证使用从 Settings > API 获取的 API 密钥，以 Bearer 方式传递。
SkyPlanner 能将排程回写到 Katana 吗？
可以。SkyPlanner 通过 /manufacturing_order_rerank，在 Katana 的 Schedule 选项卡中将未结制造订单调整为 SkyPlanner 排定的顺序，并写入每张制造订单（MO）的 production_deadline_date。工序状态和实际工时会写入制造订单的工序行。各工作中心具体到时间的排程保留在 SkyPlanner 中，操作人员按其中的工作队列开展工作。
Katana 会实时推送变更吗？
会。Katana 的 Webhook 涵盖制造订单、工序行、库存、采购订单和销售订单。SkyPlanner 会获取每个发生变更的对象，并在每晚核对数据，因此即使漏掉事件，也不会让生产任务数据一直处于过期状态。
Katana 资源如何转换为 SkyPlanner 工作中心？
Katana 工序行中的每个不同资源都会成为一个 SkyPlanner 工作中心，通过键建立 1:1 对应关系。随后在 SkyPlanner 中设置班次、缺勤及备选工作中心。
