接 QuickBooks Online：订单、客户、发票、收款与库存

在 QuickBooks 里点齿轮图标 → Account and settings → Billing & subscription 取 Realm ID（Company ID），在 Intuit Developer 您应用的 OAuth2 playground 里取 access token，两者填进 Integration，测试、配 Mapping、激活。token 1 小时就过期，测试失败通常只是需要一份新 token。

QuickBooks Online 连接器与您的 QuickBooks 公司双向工作：把销售订单、客户、发票、产品与收款拉进来，能把客户、发票、产品与收款推回去，还能按产品查库存。推到 QuickBooks 的收款可以关联到对应发票做核销。本连接用 Realm ID（Company ID）加您粘贴的 access token 来标识。token 1 小时就过期——任何功能突然不工作时，先取一份新 token，别先改别的东西。

前置条件#

• 一个能登录的 QuickBooks Online 公司，且有打开 Account and settings 的权限。
• 在 Intuit Developer 里有一个应用，以便运行它的 OAuth2 playground、为该公司取得 access token。
• 您知道公司所在的环境：真实公司填 production，Intuit Developer 沙箱公司填 sandbox。
• 拿到 token 后要抓紧完成：access token 1 小时过期，所以最后再取，取完马上填入并测试。

拿凭证#

1. Realm ID 在 QuickBooks 产品内取：登录 QuickBooks，点右上角齿轮图标 ⚙，打开 Account and settings，进 Billing & subscription，复制那里显示的 Company ID——这个 Company ID 就是 Realm ID。
2. access token 在 Intuit Developer 取：打开 Intuit Developer，打开您的应用，打开它的 OAuth2 playground。
3. 在 OAuth2 playground 里，为同一个公司、同一种环境（production 或 sandbox）走完 OAuth2 流程，复制它返回的 access token。
4. 直接进入填入步骤：这个 access token 1 小时就过期。刷新 token 要用同一个 Intuit Developer 应用的 Client ID 与 Client Secret，所以也请把那组应用的值放在手边。

填进 Integration#

1. 打开 Integration → 连接器市场 → QuickBooks Online → 新建连接。
2. realm_id——必填，Realm ID（Company ID）：粘贴从 QuickBooks → 齿轮图标 ⚙ → Account and settings → Billing & subscription 复制的 Company ID，例如 123456789。
3. environment——可选，环境：真实公司填 production，Intuit Developer 沙箱公司填 sandbox。留空则按 production。
4. access_token——必填，Access token：把 Intuit Developer → 您的应用 → OAuth2 playground 得到的 access token 完整粘贴进来，并立即完成，因为它 1 小时就过期。这是密码类型字段，作为秘密保存。

测试连接#

点测试连接。测试用您的 token 作 Bearer 凭证，从 QuickBooks 读您的公司信息——production 时按您的 realm_id 调公司信息，sandbox 时改走沙箱地址。成功应答会返回您的公司名，您由此确认 token 与 Realm ID 属于预期的公司。realm_id 缺失，测试以 MISSING_REALM_ID 停下；access_token 缺失，以 MISSING_TOKEN 停下，都不发请求。返回 401 会报 INVALID_TOKEN——token 无效，或最常见的：已经过了 1 小时。测试等 12 秒，超时报 TEST_TIMEOUT。

配 Mapping / 选模板#

选 QuickBooks Online 标准 Mapping。它覆盖本连接处理的对象：销售订单、客户、发票、产品（items）、收款，以及按产品的库存数量。测试通过后先拉一次，把一条真实记录对照核对——订单号或发票号、客户、明细行与金额——再推一个客户或产品、确认它出现在 QuickBooks 里，然后再激活。如果您公司里某个名称与标准对象不同，在 Mapping 里调整那个字段，不要去改 QuickBooks 里的东西。

激活#

激活后，连接按您设的频率从 QuickBooks Online 拉销售订单、客户、发票、产品与收款，在对应流程运行时把客户、发票、产品与收款推回去，并按产品回答库存查询。先在 运行监控 / 日志里盯头几次运行、和 QuickBooks 对照无误，再放手跑。

保持 token 新鲜：它 1 小时就过期，所以运行开始报 token 错误时，回到 Intuit Developer → 您的应用 → OAuth2 playground，为同一个公司、同一种环境取一份新的 access token，粘贴进 access_token，再重新测试。日常续 token 不需要改连接里的其他任何东西。

常见问题#

测试报 INVALID_TOKEN（401）

QuickBooks 拒绝了 access token。最常见的原因是时间：token 1 小时就过期，粘贴时能用的 token，到测试时或后续运行开始时可能已经过期。为另一个公司或另一种环境取的 token 也会被同样拒绝。

不要先改 realm_id 或 environment。去 Intuit Developer → 您的应用 → OAuth2 playground，为同一个公司、同一种环境重新走一遍流程，把新的 access token 粘贴进 access_token，保存后立即重新测试。

测试以 MISSING_REALM_ID 或 MISSING_TOKEN 停下

两个标识值里有一个是空的，测试在两者齐全前不发请求。MISSING_REALM_ID 表示 realm_id 为空；MISSING_TOKEN 表示 access_token 为空——或您粘贴的 token 被截断、没有存下可用内容。

realm_id 从 QuickBooks → 齿轮图标 ⚙ → Account and settings → Billing & subscription → Company ID 补齐，access_token 从 OAuth2 playground 取一份新的完整粘贴。保存后趁 token 还新鲜立即重测。

测试报 MISSING_SCOPE

token 本身被接受了，但它不带本连接需要的会计范围（com.intuit.quickbooks.accounting），所以 QuickBooks 不让它读公司信息。

在 OAuth2 playground 里重新走流程，确认您的应用包含会计范围，复制新的 access token，粘贴进 access_token 后重新测试。

测试返回的公司名不是预期的那个

token 与 Realm ID 描述的不是同一个公司。测试结果里的公司名来自 token 与 realm_id 实际指向的公司——常见是预期 production、实际连到了沙箱公司，或 token 是在 playground 里为另一个公司取的。

把三个值一起核对：realm_id 来自目标公司的齿轮图标 ⚙ → Account and settings → Billing & subscription → Company ID，environment 与该公司一致地设为 production 或 sandbox，token 是在 playground 里为同一个公司、同一种环境走流程取的。修正对不上的那个后重测。

一切都通了，但一小时后运行开始失败

这个时间点就是 token 的寿命，不是 Mapping 坏了，也不是公司变了。access token 1 小时过期，测试通过的连接在后续运行里会报 token 错误，直到粘贴一份新 token。

在 Intuit Developer → 您的应用 → OAuth2 playground 为同一个公司、同一种环境取一份新的 access token，粘贴进 access_token 并测试。刷新 token 要用该应用的 Client ID 与 Client Secret——把那组应用的值备好，续期就快。

测试报 TEST_TIMEOUT 或 CONNECTION_FAILED

公司信息请求没有完成。TEST_TIMEOUT 表示 12 秒内没有收到完整应答；CONNECTION_FAILED 表示到 QuickBooks 的请求没发通。在长时间怀疑网络之前，记住本连接的排查顺序：token 过期或环境不对仍是第一个要排除的。

先为同一个公司粘贴一份新的 access token，并确认 environment 与之匹配（production 或 sandbox），再重新测试。若新鲜且匹配的 token 仍超时，稍等后重试，并在改 realm_id 之前先在 运行监控 / 日志里看确切错误。