集成 / ERP / QuickBooks Online

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

本指南面向 ProAdvisors、顾问和 IT 团队，介绍如何将 QuickBooks Online 与 SkyPlanner APS 对接。SkyPlanner 通过 Intuit 的 Accounting API 与 QuickBooks Online 实现双向集成：

导入客户、物料及其现有库存数量、已接受的报价单、未结采购订单和员工数据。
将计划完工时间回写到各报价单的发货日期。
将已完成的订单回写为与原报价单关联的发票，将已记录的工时回写为工时活动，将库存变动回写为库存调整。
QuickBooks 的 Webhook 传入数据变更通知，SkyPlanner 的 Webhook 则在排程发生变化时即时推送。

开始免费试用

预约演示

SkyPlanner APS 甘特图时间轴，显示各工作中心的作业安排，下方为订单列表。

QuickBooks Online 是会计软件，不存储设备、工艺路线或生产订单。工作中心、工序、班次和准备时间均在 SkyPlanner 中维护。SkyPlanner 团队在实施阶段为您的 QuickBooks 公司配置集成，并在上线后提供支持。本指南面向希望参与集成，或希望参照 SkyPlanner 的 REST API 文档（API 参考文档）自行开发的合作伙伴和开发人员。

QuickBooks Online Accounting API

QuickBooks Online 是一款多租户云产品，所有公司都使用同一套 Accounting API。这是一个 REST API，版本为 v3。每次调用通过 realm ID 指定一家公司：https://quickbooks.api.intuit.com/v3/company/{realmId}/{entity}，测试则使用单独的沙箱主机。请求和响应均采用 JSON 格式，并通过 minorversion 参数选择数据结构版本。（来源）

排程所需的实体包括：

主数据：Customer、Item（Inventory、NonInventory、Service）、Employee、Vendor。
需求：Estimate（TxnStatus 为 Accepted、明细行、ShipDate）；对于先开票的工厂，还包括 Invoice 或 SalesReceipt。
供应：PurchaseOrder（POStatus 为 Open、包含物料和数量的明细行）、Bill。
回写：Estimate、Invoice、TimeActivity、InventoryAdjustment。

读取数据使用查询端点，例如 select * from Estimate where MetaData.LastUpdatedTime > '2026-10-01'。API 支持局部更新，因此 SkyPlanner 只发送发生变化的字段。Accounting API 中没有销售订单、工艺路线、工作中心或生产订单实体。

身份验证与限制

Accounting API 使用 OAuth 2.0 授权码流程，授权范围为 com.intuit.quickbooks.accounting。QuickBooks 管理员只需登录一次并批准访问，应用即可获得短期有效的访问令牌，通过 Authorization: Bearer 发送，同时获得一个每次刷新时都会更新的刷新令牌。（来源）

Intuit 按公司限制每分钟和每秒的调用次数，应用超限时返回 HTTP 429。Intuit 的 App Partner Program 还会按合作伙伴等级，对部分 API 调用按月计量。这两类限制均在 Intuit 的限额与限流页面中说明。借助 Webhook、变更数据捕获和局部更新，排程集成的调用量可以保持在远低于限额的水平。

SkyPlanner 的 REST API 使用 Authorization-Token 请求头中的 API 令牌进行身份验证（SkyPlanner Settings > API），文档采用 Swagger/OpenAPI 格式。集成教程介绍了如何完成最初的几次调用。

Webhook 与变更数据捕获

已连接公司的数据发生变化时，QuickBooks 的 Webhook 会通知应用。”Webhooks automatically notify you whenever data changes in your end-user’s QuickBooks Online company files.”（每当最终用户的 QuickBooks Online 公司文件中的数据发生变化时，Webhook 都会自动通知您。）（来源）与排程相关的实体包括：

Customer、Item、Employee
Estimate、Invoice、SalesReceipt
PurchaseOrder、Bill
TimeActivity

操作类型包括 Create、Update、Delete、Merge 和 Void。通知仅包含实体名称、ID、操作类型和最后更新时间，不包含完整记录。接收方随后再读取该记录。

变更数据捕获（GET /cdc?entities=...&changedSince=...）可在近期回溯窗口内，返回指定时间戳之后发生的所有变更。SkyPlanner 每晚使用它进行核对，确保即使遗漏 Webhook 通知，也不会留下未更新的订单。变更数据捕获不涵盖 TimeActivity，因此需通过查询进行核对。（来源）

数据映射

QuickBooks Online 对象	SkyPlanner 对象	方向	频率
`Customer`	客户（`external_identifier`、`delivery_priority`）	QuickBooks → SkyPlanner	首次导入，之后由 Webhook 触发
`Item`（Inventory、NonInventory、Service），含 `QtyOnHand`	产品、物料及库存	QuickBooks → SkyPlanner	首次导入，之后由 Webhook 触发
`Estimate`（Accepted）、明细行、`ShipDate`	订单（`external_order_number`、`delivery_date`），各明细行对应的生产任务	QuickBooks → SkyPlanner	通过 Webhook 实时同步
`Invoice` 或 `SalesReceipt`（先开票的工厂）	订单和生产任务	QuickBooks → SkyPlanner	通过 Webhook 实时同步
`PurchaseOrder`（Open）、明细行	待到货物料（产品采购订单）	QuickBooks → SkyPlanner	通过 Webhook 实时同步
`Employee`	人员	QuickBooks → SkyPlanner	首次导入，之后由 Webhook 触发
`Estimate.ShipDate`（局部更新）	计划完工时间	SkyPlanner → QuickBooks	排程变更时
`Invoice`，通过 `LinkedTxn` 关联 Estimate	已完成的订单	SkyPlanner → QuickBooks	订单完成时
`TimeActivity`（`EmployeeRef`、`CustomerRef`、`ItemRef`、工时）	Mobile Confirmations、工时记录	SkyPlanner → QuickBooks	记录作业时
`InventoryAdjustment`	成品入库、物料消耗	SkyPlanner → QuickBooks	订单完成时
QuickBooks 中无此数据	工作中心、工序、班次、缺勤、准备时间矩阵、工具、操作人员数量、备选工作中心	在 SkyPlanner 中维护	在实施阶段设置

集成模式

1. 首次导入主数据。通过查询端点分页读取客户、物料、员工和未结采购订单。在 SkyPlanner 中创建客户时，将 QuickBooks ID 用作 external_identifier；创建产品和物料时，将物料 ID 用作键值。然后建立 QuickBooks 中没有的数据：工作中心、各产品的工序、班次、休假和准备时间。导入工序最快的方式是使用 CSV 或 Excel。

2. 订单同步。订阅 Estimate、Invoice、Item 和 PurchaseOrder 的 Webhook。当报价单状态变为 Accepted 时，SkyPlanner 会读取报价单并创建订单，将报价单号用作 external_order_number，将发货日期用作 delivery_date。每个明细行都会按产品的工序生成生产任务。未结采购订单的明细行会转为待到货物料，因此相关生产任务会等待物料到货。每晚的变更数据捕获会补齐所有遗漏的事件。

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

对 Estimate 执行局部更新，写入 ShipDate，使 QuickBooks 中的承诺日期与排程保持一致。
订单完成后，通过 POST /invoice 创建发票，包含报价单的明细行，并通过 LinkedTxn 关联原报价单。Intuit 只允许每份报价单关联一张发票，因此需要在范围评估阶段商定分批交付的处理方式。
通过 POST /timeactivity 记录每位操作人员填报的工时，并关联员工、客户和服务项目。之后可在 QuickBooks 中将可计费工时添加到发票。
通过 POST /inventoryadjustment 增加成品库存，并扣减已消耗的物料。Intuit 在美国的 QuickBooks Online Plus 和 Advanced 中提供此实体。（来源）

4. 车间报工。操作人员使用 SkyPlanner Mobile Confirmations、Production Timer 或 Quick Log Mode 记录作业。作业进度会立即更新排程，Autopilot 则对剩余工作重新排程。工时作为工时活动传入 QuickBooks。如果工厂继续使用 QuickBooks Time 核算薪资，应在范围评估阶段选定一个生产任务工时记录渠道。

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

数据	归属系统
客户、物料、价格、报价单、采购订单、发票、会计数据	QuickBooks Online
工作中心、工序、班次、缺勤、准备时间矩阵、工具、备选资源	SkyPlanner
生产任务顺序、起止时间、各生产任务使用的工作中心	SkyPlanner
报价单发货日期	由 SkyPlanner 管理，写入 QuickBooks
已完工订单的发票、任务工时、成品库存调整	由 SkyPlanner 创建，过账后由 QuickBooks 管理

典型项目步骤

实施工作通常在启动后的数周内完成。在此之前，您可以先从 QuickBooks 导出客户、产品和未结报价单，使用自己的数据进行 30 天免费试用。

项目包括以下步骤：

建立连接。QuickBooks 管理员通过 Intuit 的 OAuth 2.0 页面为 SkyPlanner 授权。
确定需求对象。商定由已接受的报价单、发票还是销售收据触发生产。
确定映射。明确映射表、项目标识键、用于记录人工的服务项目，以及数据归属规则。
首次导入。导入客户、项目、员工和未结采购订单。
建立生产模型。在 SkyPlanner 中设置工作中心、各产品的工序、班次、准备时间矩阵、工具和操作人员数量。
事件同步。为报价单、项目和采购订单配置 webhook，并在每晚执行变更数据捕获。
数据回写。先回写发货日期，再回写发票、工时记录和库存调整。
并行测试与上线。将 SkyPlanner 的日期与当前计划进行比较，请会计核查首批发票和调整记录，然后启用回写。

规划 QuickBooks Online 集成时需要考虑什么

销售订单仍在 QuickBooks 界面中管理。Plus 和 Advanced 在应用内提供销售订单，而集成读取的是已接受的报价单；对于先开票的工厂，则读取发票。请统一采用一种触发方式，让所有订单通过相同方式进入生产。
QuickBooks 不存储工艺路线。请在 SkyPlanner 中维护各产品的工序，并通过标识键关联 QuickBooks 项目。
每份报价单仅关联一张发票。分批交付需要明确规则，例如每次交付对应一份报价单。
库存调整取决于套餐和地区。美国版 Plus 和 Advanced 支持库存调整。其他地区则需与会计商定如何将成品记入 QuickBooks。
Intuit Enterprise Suite 制造订单。如果使用此类订单，请明确由哪个系统管理组装和组件预留。
API 只能读取组合项目。无法通过 API 创建 Group 项目，因此请在 QuickBooks 中维护组合项目。
刷新令牌轮换。每次刷新后都要保存最新的刷新令牌，否则连接会中断。

QuickBooks Online 集成由谁配置和支持

集成工作涵盖您的项目、报价单、采购订单，以及完工后如何转入开票流程。同时还需补充 QuickBooks 中没有的数据：工作中心、工序、班次、准备时间矩阵、工具、操作人员数量和替代资源。

SkyPlanner 团队在实施阶段完成配置，并在上线后提供支持。各家工厂在 QuickBooks 中设置项目、报价单和库存的方式各不相同，这些实施经验正好能在此发挥作用。
您的 QuickBooks ProAdvisor 或集成合作伙伴可以开发集成。SkyPlanner 提供 REST API、Swagger/OpenAPI 文档和 webhook。
您自己的开发人员也可以使用 API 令牌开展开发。只需一个 API 令牌即可开始，SkyPlanner 团队会在需要时提供协助。采购订单、产品与物料 API 等产品文档均可在 SkyPlanner 文档中查阅。

SkyPlanner 每月 199 € 起，包含 5 个工作中心，按月付费。集成费用会根据您的流程和需求预先报价，并与套餐费用一并列明，让您在开始前了解全部成本。查看价格和功能，或阅读《QuickBooks 是否具备生产排程功能？》，了解 QuickBooks 自身的功能范围。概览见 QuickBooks Online 页面，其他系统请参阅全部集成。

开始免费试用

预约演示