Comarch ERP XL 集成指南：使用 SkyPlanner APS 进行生产排程
本指南面向合作伙伴和 IT 团队，介绍如何将 Comarch ERP XL 与 SkyPlanner APS 连接。SkyPlanner 通过 Comarch 自身的接口与 Comarch ERP XL 实现双向集成：
- 导入生产订单（zlecenia produkcyjne）及其流程和工序，以及工艺、工作中心、资源、物料、库存和采购订单。
- 通过 XL API，将计划开始和结束时间回写至生产订单的各道工序。
- 如有需要，可将操作人员的工时记录作为工序执行记录回写。
- 排程发生变化时，SkyPlanner webhook 会即时推送。
在实施导入阶段，SkyPlanner 团队会根据您的 Comarch ERP XL 配置设置集成，并在上线后继续提供支持。本指南面向希望参与集成，或自行基于 SkyPlanner 已有文档的 REST API（API 参考文档）进行开发的合作伙伴和开发人员。
Comarch ERP XL 的集成接口
Comarch 列出了与 ERP XL 通信的三种方式：”DCOM, direct database connection (SQL Client), REST API”（DCOM、直接数据库连接（SQL Client）、REST API）（Comarch，译文）。对于排程系统，主要使用其中两种：
- XL API (CDN_API.DLL). “These functions are collected in the CDN_API.DLL library, installed together with the whole Comarch ERP XL system.”（这些函数集中在 CDN_API.DLL 库中，该库随整个 Comarch ERP XL 系统一同安装。）（Comarch 帮助文档，译文）外部程序通过 XLLogin 登录，调用共享同一会话的函数，再通过 XLLogout 退出。每个结构都有一个 Wersja 字段，用于选择与您的 ERP XL 版本相匹配的参数集版本。
- ERP XL Web REST API. Comarch ERP XL Web 2026.0 提供 REST 微服务：”Each RestAPI microservice exposes its own interactive documentation at the /swagger endpoint.”（每个 RestAPI 微服务都在 /swagger 端点提供各自的交互式文档。）（Comarch 帮助文档，译文）
经您的 IT 团队和 Comarch 合作伙伴同意后，可通过 SQL Client 直连 ERP XL 数据库，读取主数据和订单。
XL API 的生产相关函数
Comarch 文档介绍了以下生产相关函数（XL128）：
| 业务范围 | 函数 | 功能说明 |
|---|---|---|
| 工艺 | XLNowaTechnologia, XLNowaCzynnoscTechnologia, XLNowaFunkcjaCzynnoscTechnologia, XLNowyZasobCzynnoscTechnologia | 新建工艺、工序，为工序添加工作中心、物料或产品 |
| 生产订单 | XLNoweZlecenieProd | 新建生产订单 |
| 生产订单 | XLZamknijZlecenieProd | 根据操作代码，对生产订单进行计划、重新计划、结算或关闭 |
| 工序 | XLDodajCzynnoscDoProcesuProd, XLDodajZasobDoProcesuProd | 向生产流程添加工序或资源 |
| 排程 | XLDodajTerminDoProcesuProd | 为工序添加日期范围：IdCzynnosci、TerminOd、TerminDo |
| 执行记录 | XLDodajRealizacjeOperacjiProd, XLProdZmienIloscRealizacji | 向订单添加工序执行记录，修改实际完成数量 |
| 单据 | XLProdObiektyDoDokumentow, XLProdGenerujDokumentyDlaObiektow | 为生产对象生成 RW 和 PW 单据 |
身份验证与访问
- XL API. 集成程序以 ERP XL 操作员身份，通过 XLLogin 登录数据库，获取用于后续调用的会话。DLL 在安装了 ERP XL 的 Windows 主机上运行，因此回写服务部署在您的网络内，与 ERP XL 就近运行。
- REST API. 每套 ERP XL Web 实例分别配置访问权限；各微服务的 Swagger 页面提供相应的调用文档。
- SQL 读取。 使用经您的 IT 团队批准的只读数据库账户。
在 SkyPlanner 端，REST API 通过 Authorization-Token 请求头中的 API 令牌进行身份验证（SkyPlanner Settings > API），并提供 Swagger/OpenAPI 文档。集成教程将引导您完成初次调用。
事件与轮询
在已查阅的文档中，Comarch ERP XL 未公布任何出站 Webhook。Comarch 自家的 APS 在计划员点击“Aktualizuj dane z ERP”（从 ERP 更新数据）时拉取数据（Comarch APS 帮助文档）。
因此，ERP XL 端采用轮询方式。读取时筛选未结生产订单和近期变更，以获取新增生产任务。轮询频率按工厂设置，例如每隔几分钟读取一次生产订单，每小时读取一次库存。
当状态或排程发生变化时，SkyPlanner 会发送 Webhook，因此回写端采用事件驱动方式。
数据映射
| Comarch ERP XL 对象（接口） | SkyPlanner 对象 | 传输方向 | 同步频率 |
|---|---|---|---|
| Karty towarów、计量单位（通过 REST 或 SQL 读取） | 产品和物料 | ERP XL → SkyPlanner | 首次加载，之后轮询 |
| Technologia：工序、物料、半成品及各工序的产品 | 产品结构、子产品及各工序的物料 | ERP XL → SkyPlanner | 首次加载，之后在数据变更时同步 |
| Technologia 工序：工作中心、资源、工时 | 工序及其持续时间、准备时间和拆卸时间 | ERP XL → SkyPlanner | 首次加载，之后在数据变更时同步 |
| Gniazda robocze 和 zasoby（机器、工具、员工） | 工作中心、工作中心组、工具、人员 | ERP XL → SkyPlanner | 首次加载，之后很少同步 |
| Kalendarze i okresy、przestoje i awarie | 班次、非工作时间和停机时间 | ERP XL → SkyPlanner | 每天同步，或在 SkyPlanner 中单独维护班次 |
| Zlecenia produkcyjne (ZP)，含流程、工序、物料、交期和优先级 | 订单和生产任务，含交期及物料需求 | ERP XL → SkyPlanner | 每隔几分钟轮询 |
| 各仓库的库存 | 库存结余 | ERP XL → SkyPlanner | 每小时或运行排程时轮询 |
| Zamówienia zakupu (ZZ)，含交货日期 | 采购订单、按交货日期安排的到货物料 | ERP XL → SkyPlanner | 每小时或运行排程时轮询 |
| 工序起止时间：TerminOd、TerminDo (XLDodajTerminDoProcesuProd) | 各生产任务的计划开始和结束时间 | SkyPlanner → ERP XL | 排程变更时，通过 SkyPlanner webhook 触发 |
| Realizacja operacji (XLDodajRealizacjeOperacjiProd) | 工时记录和操作员报工确认 | SkyPlanner → ERP XL | 如选用此项，则在每次报工确认时或按班次同步 |
| ERP XL 中无对应项 | 准备及切换时间矩阵、作为有限资源的工具、多人协作的生产任务、可替代机器和人员 | 在 SkyPlanner 中维护 | 在实施导入阶段设置 |
集成模式
1. 首次加载主数据。读取物料、工艺、工作中心、资源和日历。将工作中心映射到 SkyPlanner 时，需要明确划分方式：包含四台机器的工作中心可以映射为一个工作中心组，也可以映射为四个工作中心。ERP XL 资源中的工具在 SkyPlanner 中作为有限资源管理，员工则映射为带有班次安排的人员。
2. 同步订单。读取生产订单及其工序和物料，同时读取未结采购订单。SkyPlanner 将已订购物料视为在采购订单交货日期可用，并在采购订单标记为 Delivered 时更新库存。
3. 排程回写。当引擎安排或移动工序时，SkyPlanner webhook 会触发回写服务。该服务使用工序的 TerminOd 和 TerminDo 调用 XLDodajTerminDoProcesuProd，让每道 ZP 工序都记录 SkyPlanner 计划的开始和结束时间。
4. 车间报工。操作人员通过 SkyPlanner Mobile Confirmations 或 Production Timer 记录工作，工时记录会让排程保持更新。您可以选择是否回传实际工时。如果选择回传，服务会通过 XLDodajRealizacjeOperacjiProd 添加实绩记录，RW 和 PW 单据则遵循您的 ERP XL 规则。如果部分工位使用 Comarch MES，请确保每道工序只有一个报工来源。
5. 数据归属与冲突处理规则。上线前请以书面形式明确以下规则：
| 数据 | 负责系统 |
|---|---|
| 物料、工艺、数量、ZP 状态、成本核算 | Comarch ERP XL |
| 工序顺序、开始和结束时间、资源分配 | SkyPlanner |
| 准备及切换时间矩阵、工具和操作人员要求、替代资源 | SkyPlanner |
| 班次、日历和停机时间 | 由一个系统负责，在范围评估时确定 |
| 实绩记录、RW 和 PW 单据 | Comarch ERP XL，可直接录入，也可由 SkyPlanner 工时记录回传 |
工序日期只能由一个系统写入。如果 ERP XL 自动重排或 Comarch APS 仍在向同一批生产订单写入日期，请针对由 SkyPlanner 排程的订单关闭该功能。
典型项目步骤
实施通常在导入服务开始后的数周内完成。在此之前，可以将 ERP XL 中的工作中心、工艺和未结生产订单导出为 CSV 或 Excel，在 30 天免费试用期间验证排程。
- 映射。确定映射表、数据归属规则、同步频率，以及是否回传实绩记录。
- ERP XL 访问配置。创建集成专用操作员账号，配置读取连接，并将回写服务部署在已安装 ERP XL 的主机上。先在数据库副本中测试。
- 首次加载。导入物料、工艺、工作中心、资源和日历。
- 生产订单与采购订单同步。采用带筛选和重试机制的轮询。
- 在 SkyPlanner 中配置约束。设置准备及切换时间矩阵、工具、每项生产任务所需的操作人员数量，以及可替代的机器或人员。
- 排程回写。通过 SkyPlanner webhook 触发 XLDodajTerminDoProcesuProd 调用；如已选择回传实绩记录，也一并配置。
- 并行测试。将 SkyPlanner 与现有计划并行运行，对比日期，修正主数据。
- 上线。数据核对一致后，启用回写。
Comarch ERP XL 集成需要提前考虑什么
- 手动设定的产能。ERP XL 中的工作中心产能由用户输入数值，并设置允许的负荷百分比。SkyPlanner 则根据实际班次和资源计算产能，因此需要仔细设置班次，不再沿用该百分比。
- 无限产能资源。在 ERP XL 中，标记为无限产能的资源会跳过占用检查。请逐一确定这些资源是否应在 SkyPlanner 中设为产能有限的工作中心。
- 已下达订单。除非勾选“Przesuń na zwolnionych”，否则 ERP XL 重排时不会处理已下达到生产的工序。请约定 SkyPlanner 的计划日期如何应用于已下达订单，并使用 Running Time Lock 冻结接下来数小时内的生产任务。
- 结构体版本。XL API 结构体包含 Wersja 字段。请将其设置为与您的 ERP XL 版本匹配，并在每次年度升级后重新测试。
- 波兰本地的单位和时间。导入时必须准确换算工序时间和日历单位，否则所有时长都会出错。
谁负责 Comarch ERP XL 集成的配置与支持
- SkyPlanner 团队在导入阶段负责配置，上线后继续提供支持，范围涵盖双方约定的数据读取和 XL API 调用。每家工厂使用 Comarch ERP XL 的方式都不同，配置时会充分运用这些实践经验。
- 您的 Comarch 合作伙伴也可以参与。合作伙伴熟悉您的配置、许可和 XL API，可以与 SkyPlanner 团队一起配置操作员账号、读取连接和回写主机。
- 您的开发人员也可以在此基础上扩展开发，使用 API 令牌调用 SkyPlanner 的 REST API。只需一个 API 令牌即可开始，SkyPlanner 团队会在需要时提供协助。集成文档请参阅SkyPlanner 集成文档。
SkyPlanner 每月 199 € 起，包含 5 个工作中心，按月计费。集成费用会根据您的流程和需求，与订阅方案一起提前报价。请参阅价格、Comarch ERP XL 生产排程、Comarch ERP XL 页面和ERP 集成中心。
制造企业对 SkyPlanner 的评价
2 小时每周节省的时间
“SkyPlanner 让我们的生产计划从 Excel 表格走向了实时生产优化。”
Kalle Kalliomäki，供应链专员
UTU · 配电盘与开关设备
生产计划工作每周节省 2 小时，新的任务队列只需几秒就能传达到产线。
+90%生产效率提升
“生产效率提高了 90%。”
Abdul Rucyinga，IT 负责人
Laboratory & Allied · 制药
生产效率提高了 90%，为所有工作中心制定覆盖三个月的优化计划，只需不到 30 分钟。
6 个月销售可提前查看的空闲产能
“SkyPlanner 为所有生产计划工作奠定了基础，提供了可靠保障。”
Anu Järvinen，生产经理
Fredman Operations · 食品级包装纸
销售人员可以提前六个月查看空闲产能。过去需要一小时或更久才能答复的排程变更请求，现在几秒内就能得到回应。
100%自 2021 年以来的准时交付率
“SkyPlanner 让我们看清产能情况，让计划工作更可预测。”
Dan Berglund，COO/CFO
Opes Corporation · 化工与食品制造
自 2021 年开始使用 SkyPlanner 以来，准时交付率始终保持在 100%。
常见问题
Comarch ERP XL 是否提供生产订单 API？
是的。XL API（CDN_API.DLL）可创建生产订单，通过 XLZamknijZlecenieProd 对其进行计划和重排，通过 XLDodajTerminDoProcesuProd 添加工序日期，并通过 XLDodajRealizacjeOperacjiProd 提交实绩记录。Comarch ERP XL Web 还提供 REST 微服务，其文档通过 Swagger 发布。
计划日期如何回写到 Comarch ERP XL？
通过 XLDodajTerminDoProcesuProd，为生产订单的每道工序添加日期范围（TerminOd、TerminDo）。每当排程发生变化，SkyPlanner webhook 就会触发该调用。
Comarch ERP XL 是否支持 webhook？
文档中没有对外发送 webhook 的说明，因此集成会按各工厂设定的周期轮询 ERP XL。SkyPlanner 自身的 webhook 则会在排程变化时即时推送。
Comarch 合作伙伴应该推荐 Comarch APS 还是 SkyPlanner？
如果客户希望在数周内获得符合实际产能约束、且能自动保持更新的生产排程，应推荐 SkyPlanner。Comarch APS 是独立应用，拥有自己的 PostgreSQL 数据库、集成程序和许可密钥；需要计划员点击才会同步，且每道工序的准备时间只有一个固定值（Comarch APS 帮助）。SkyPlanner 是云软件，可自动重排，并对换型、工具、班组和物料进行计划，每月 199 € 起。
