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

Xero 是一款多租户云产品，所有组织使用同一套 API。Accounting API 是 REST API，地址为 https://api.xero.com/api.xro/2.0/，支持 JSON 或 XML。每次调用都通过 Xero-tenant-id 请求头指定组织。（来源）

排程所需的端点：

• 主数据：/Contacts（客户和供应商）、/Items（Code、IsTrackedAsInventory、QuantityOnHand）。
• 需求：/Quotes（Status 为 ACCEPTED，含 LineItems）；对于先开票再生产的车间，还需使用 Type 为 ACCREC 的 /Invoices。
• 供应：/PurchaseOrders（DeliveryDate、ExpectedArrivalDate，以及含 ItemCode 的 LineItems）。
• 回写：/Quotes/{QuoteID}/History、/Invoices、/Quotes，以及 Projects API 的 https://api.xero.com/projects.xro/2.0/projects/{projectId}/time。

所有列表端点都支持 If-Modified-Since 请求头，因此每次同步只读取发生变更的数据。创建和更新操作均采用批量方式。Xero 不提供物料清单、工艺路线或生产订单端点。

“Webhooks allow you to subscribe to certain events that happen in Xero.”（网络钩子让您订阅 Xero 中发生的特定事件。）（来源）与排程相关的事件包括 Contact 和 Invoice，两者均支持 CREATE 和 UPDATE。

工作方式如下：

• 每个应用只需一个网络钩子，即可覆盖所有已连接的组织。
• 每次推送都包含一个 events 数组，其中带有资源 ID 和事件类型。接收端随后再读取对应资源。
• 每次推送均通过 x-xero-signature 请求头携带签名，签名根据应用的网络钩子密钥生成。Xero 在开始推送前会发送 “Intent to receive”（接收意向）检查。
• 推送失败时，Xero 会重试；如果持续失败，则会停用该网络钩子。因此，接收端应先快速响应，再处理实际工作。

报价单、物料和采购订单没有网络钩子事件。SkyPlanner 以较短间隔轮询，通过 If-Modified-Since 读取这些数据。在没有变更的情况下，每类实体只需一次调用。

1. 首次加载主数据。先分页读取联系人和物料，再读取未结采购订单及已接受的报价单。在 SkyPlanner 中创建客户，以 Xero ContactID 作为 external_identifier；创建产品和物料时，以物料编码作为键。然后建立 Xero 中没有的数据：工作中心、各产品的工序、班次、休假及准备时间。导入工序最快的方式是使用 CSV 或 Excel。

2. 订单同步。通过 If-Modified-Since 轮询报价单。报价单状态变为 ACCEPTED 时，SkyPlanner 会创建订单，并将报价单号用作 external_order_number。delivery_date 取自车间用于记录承诺交期的字段，该映射在实施导入阶段配置。每个明细行会按产品工序生成生产任务。采购订单明细行则按预计到货日期形成待到货物料，生产任务因此会等待物料到货。每晚完整读取未结报价单和采购订单，以补齐遗漏的数据。

3. 回写排程和完工结果。通过三次调用将结果写入 Xero：

• PUT /Quotes/{QuoteID}/History 添加一条含计划完工日期的备注。已接受的报价单只允许修改联系人和备注，因此日期存放在历史备注中。（来源）
• 订单完成时，POST /Invoices 创建销售发票，将 Type 设为 ACCREC、Status 设为 DRAFT，沿用报价单的联系人和明细行，并将报价单号用作 Reference。记账人员随后在 Xero 中审核并发送发票。
• 通过 POST /Quotes 提交 QuoteID 及 Status INVOICED，关闭报价单。Accounting API 允许将状态从 Accepted 更改为 Invoiced。

4. 车间报工与项目工时。操作人员使用 SkyPlanner Mobile Confirmations、Production Timer 或 Quick Log Mode 记录工作。进度会立即更新到排程中，Autopilot 随即重新安排剩余工作。对于项目工作，SkyPlanner 会将工时作为工时记录提交到对应项目任务，记录中包含 Xero 用户、日期和时长。（来源）

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

• Xero 中没有生产对象。各产品的工序应保存在 SkyPlanner 中，并以 Xero 物料编码关联。物料编码应保持稳定。
• 报价单不支持 webhook。使用 If-Modified-Since 进行短周期轮询，同时遵守每分钟和每日的调用限额。
• 报价单接受后会锁定。接受后只能更改联系人信息和备注，因此承诺日期仅在接受时读取一次，计划日期则以历史备注的形式写入。
• 库存随销售发票和采购账单变动。对于跟踪库存的物料，Xero 通过销售发票、采购账单和贷项通知单调整现有库存数量。请与记账人员商定成品和已耗用物料的核算方式。
• 项目工时需要关联 Xero 用户。每条工时记录都归属于一个 Xero 用户。请确定哪些操作人员需要向 Xero Projects 提交工时，其余人员的工时则保留在 SkyPlanner 中。
• 细粒度权限范围。应从一开始就申请细粒度权限范围，因为宽泛的权限范围正在逐步停用。
• 应用等级。合作伙伴等级决定了应用可连接的组织数量和每日调用次数。请根据工厂数量规划所需等级。