monday.com 集成指南：使用 SkyPlanner APS 进行生产排程

monday.com 提供一个 GraphQL API，端点为 POST https://api.monday.com/v2。该 API 每季度发布版本，您可以通过 API-Version 请求头固定使用的版本。弃用公告至少提前六个月发布。（API 版本管理）

排程集成会用到以下对象：

• Boards 和 groups，通常用于按阶段或周组织数据。
• Items 和 subitems。一个 item 通常代表一个订单或生产任务，subitems 则用于存放工序。
• 列值：Status、Date、Timeline、Numbers、People、Dependency、Time Tracking、Connect Boards 和 Mirror。
• Webhooks，用于接收变更事件。

读取时，使用嵌套在 board 或 group 中的 items_page。默认每页返回 25 个条目，且 “the maximum is 500.”（最多为五百个）。使用 next_items_page 继续读取后续页面；注意，”each cursor will expire 60 minutes after the first request.”（每个游标都会在首次请求六十分钟后过期）。通过 query_params 筛选，即可只读取未结订单。（items_page）

写入使用 create_item、create_subitem、change_column_value 和 change_multiple_column_values。最后一个方法可以在一次调用中更新一个条目的多个列，正好满足排程回写的需要。

针对大批量数据加载，API 版本 2026-07 及后续版本新增了 ingest_items 和 backfill_items。将 CSV 文件上传到预签名 URL 后，轮询导入任务的状态即可。（批量导入）

使用 create_webhook(board_id, url, event, config) 创建订阅。排程集成需要以下事件：

• create_item 和 create_subitem，用于接收新增订单和工序的事件。
• change_column_value 或 change_specific_column_value，用于交期、数量或优先级变更。
• change_status_column_value，用于接收人工修改状态的事件。
• item_archived、item_deleted 和 item_moved_to_specific_group，用于已取消或已完成的订单。

创建 webhook 时，接收 URL 必须响应验证令牌。投递失败后会 “retry once a minute for 30 minutes,”（每分钟重试一次，持续三十分钟），随后停止。因此，集成服务还会定期使用 items_page 读取数据，并筛选最近更新的条目进行核对。（webhooks）

在反向同步中，SkyPlanner 会在状态或排程发生变化时发送 webhooks。集成服务接收后，将新的日期写入 monday.com，因此回写由事件驱动。

1. 首次加载主数据。使用 items_page 读取产品、物料和未结订单。在 SkyPlanner 中创建工作中心、班次和约束，或从 Excel 导入。尽早确定工序是存为子条目，还是存放在关联看板上。

2. 订单同步。生产看板上的 webhooks 将新增和修改的条目作为订单发送到 SkyPlanner。如果您在看板上跟踪采购订单，SkyPlanner 会将订购物料视为在交货日期可用，并在采购订单标记为已交付时更新库存。

3. 排程回写。对于排程引擎新安排或调整的每个订单，集成服务都会调用 change_multiple_column_values，将计划开始和结束时间写入 Timeline 列，并填写工作中心列。每个条目只调用一次，可减少请求数量。

4. 车间进度。操作人员通过 Mobile Confirmations、Production Timer 或 Quick Log Mode 记录作业。工时记录让排程保持最新，对应的 Status 标签则回写到看板，销售人员无需询问就能了解进度。

5. 数据归属与冲突处理规则。上线前应明确并记录以下规则：

冲突主要来自人工修改 Timeline 列。应约定仅由 SkyPlanner 写入该列，或将人工修改视为调整请求，再由 SkyPlanner 重新排程。生产情况变化时，Autopilot 会自动重新排程。

• 每个账户组织订单的方式都不同。有的为每位客户建立一个看板，有的将工序设为条目或子条目，有的用 People 或 Status 列表示设备。必须按账户映射列 ID，切勿按列标题映射。
• 套餐限制。Free、Basic 和 Standard 每天允许调用 API 1,000 次，Pro 为 10,000 次，Enterprise 为 25,000 次。通过 Webhook 接收变更，使用 change_multiple_column_values 批量回写。（调用频率限制）
• 关联看板的数量有上限。Basic 允许关联一个看板，Standard 允许关联五个，因此可关联的工序或产品看板数量会受到限制。（Connect Boards 限制）
• 固定 API 版本。版本每季度更新。在 2026-04 版本之前，默认的 boards 查询不包含多层级看板。
• 游标有效期。items_page 游标的有效期为 60 分钟。长时间运行的数据核对任务必须能够从头重新执行，不受上次运行残留状态的影响。
• Webhook 限制。URL 最长为 255 个字符，重试会在 30 分钟后停止。接收端必须具备幂等性。
• 单位与时长。Numbers 列不带单位。首次导入前，应约定时长采用分钟还是小时。