大多数同步错误都属于少数几类，并且有明确的修复方法。本指南涵盖了客户最常遇到的错误、它们的成因以及每种错误的具体解决方法。
如果您不确定首先在哪里查找错误，请从读取和筛选审计日志开始，以找到失败的特定记录。
一目了然的错误状态
在深入研究具体错误之前，您的审计日志中的每种状态都意味着什么：
- 已同步：记录已成功发送到 QuickBooks。
- 错误：同步尝试失败。日志条目将包含原因。
- 待定：记录已排队，尚未处理。
- 暂停：记录正在等待满足同步触发条件，例如付款或发货状态要求。
下面的所有错误都会在您的日志中显示为错误状态。
1. QuickBooks 中未找到客户
含义：LedgerPort 尝试将 Shopify 客户与现有 QuickBooks 客户进行匹配，但未找到。订单无法同步，因为没有要附加的客户。
如何修复：
选项 A：手动映射客户。
- 转到左侧边栏中的映射。
- 点击客户。
- 找到客户，然后从下拉列表中选择匹配的 QuickBooks 记录。
- 转到手动同步 » 订单并重新同步受影响的订单。
选项 B：切换到通用客户模式。如果您不需要在 QuickBooks 中进行按客户跟踪，可以将所有未匹配的客户路由到一个通用的 QuickBooks 客户。
- 转到同步配置 » 客户。
- 将客户策略更改为通用。
- 从手动同步 » 订单重新同步受影响的订单。
2. 产品未映射
含义：LedgerPort 未能为订单中的一个或多个产品找到匹配的 QuickBooks 项目。这通常发生在产品存在于 Shopify 中，但尚未在 QuickBooks 中映射或创建时。
如何修复：
选项 A：运行自动映射。
- 转到映射 » 产品。
- 点击自动映射。LedgerPort 将尝试按 SKU 或名称匹配产品。
- 检查仍未映射的任何项目，并手动处理它们。
选项 B：手动映射。
- 转到映射 » 产品。
- 找到未映射的产品，然后从下拉列表中选择正确的 QuickBooks 项目。
选项 C：设置默认产品回退。如果您希望未映射的产品使用占位符项目进行同步而不是失败：
- 转到 同步配置 » 产品。
- 在 未匹配处理 下，选择 使用默认产品 并选择备用的 QuickBooks 项目。
3. QuickBooks 连接不健康 / 授权错误
含义：LedgerPort 无法访问您的 QuickBooks 帐户。这通常是因为 QuickBooks 访问令牌已过期。这是最常见的同步错误，并且很容易修复。
如何修复：
- 在左侧边栏中转到 连接。
- 在 QuickBooks Online 下，点击 重新连接。
- 登录 QuickBooks 并点击 授权。
- 重新连接后，从 手动同步 » 订单 重新同步在断开连接期间失败的任何订单。
4. QuickBooks 中存在重复条目
含义：LedgerPort 尝试在 QuickBooks 中创建一笔交易，但具有相同订单号的记录已存在于其中。如果订单是手动同步然后再次自动同步，或者之前的同步部分完成，则可能会发生这种情况。
如何修复：
首先检查 QuickBooks。如果交易存在且正确，您可以将其标记为在您的审计日志中已解决，而无需重新同步。
如果重复项是错误创建的：
- 删除 QuickBooks 中的重复交易。
- 转到 手动同步 » 订单，找到订单，然后重新同步它。
为防止将来发生这种情况，请确保您不会对手动同步已在自动同步队列中的订单进行手动同步。
含义：应用于 Shopify 订单的税率在 LedgerPort 中没有匹配的配置。同步停止，因为它无法确定在 QuickBooks 中记录税款的位置。
如何修复：
- 转到 同步配置 » 会计。
- 检查您的税务配置。如果您使用的是 逐项税，请检查所有 Shopify 税率是否都具有相应的 QuickBooks 税码映射。
- 如果您希望 QuickBooks 自动处理税款计算，请在同一选项卡中切换到 QuickBooks 自动销售税。
- 从手动同步 » 订单重新同步受影响的订单。
6. 无效帐户
含义：您的同步配置中引用的 QuickBooks 帐户（例如收入帐户、销货成本帐户或清算帐户）在 QuickBooks 中已不存在，或已被重命名或删除。
如何修复：
- 登录 QuickBooks 并检查您的会计科目表以确认哪些帐户处于活动状态。
- 在 LedgerPort 中，转到 同步配置 并检查付款、产品和会计选项卡，查找可能已过时的任何帐户引用。
- 更新受影响的字段以指向正确的活动帐户。
- 从 手动同步 重新同步受影响的记录。
7. QuickBooks API 超时
含义：LedgerPort 向 QuickBooks 发送了请求，但未及时收到响应。这通常是由 QuickBooks 端暂时性减速引起的，而不是配置问题。
如何修复：
等待几分钟，然后重试同步。
- 转到 手动同步 并选择失败的实体类型（订单、产品等）。
- 选择受影响的记录，然后点击 同步选定项。
如果超时在数小时内持续发生，请查看QuickBooks Online 状态页，了解是否存在已知的服务问题。
8. 超出速率限制
含义：LedgerPort 在短时间内向 QuickBooks API 发送了过多的请求。QuickBooks 会强制执行速率限制，此错误表示暂时达到了该限制。在一次性同步大量积压订单时最常见。
如何修复：
无需进行配置更改。LedgerPort 将自动重试速率受限的请求。如果您正在进行大量手动同步，请等待 15 到 30 分钟，然后再次检查日志。一旦速率限制窗口重置，记录通常会自动同步。
9. 订单暂挂
含义：订单存在于 Shopify 中，但尚未触发同步，因为它不符合您配置的同步触发条件。例如，如果您的同步设置为仅对已付款订单运行，而订单仍处于待付款状态，则该订单将暂挂，直到捕获付款为止。
如何修复：
这通常是预期行为。检查您的同步触发器设置：
- 转到同步配置 » 订单。
- 查看设置为同步触发器的付款状态和发货状态。
- 如果订单应已同步，请确认其在 Shopify 中的状态符合您的触发条件。
如果您想立即同步订单而不考虑其状态，请转到手动同步 » 订单，找到该订单并手动同步。
10. 缺少必填字段
含义：订单或记录缺少 QuickBooks 创建交易所需的信息。常见示例包括缺少账单地址、客户姓名为空或产品无价格。
如何修复：
- 在 Shopify 中打开订单并添加缺失的信息（客户姓名、地址等）。
- 返回 LedgerPort 并转到手动同步 » 订单。
- 找到订单并重新同步。
如果问题出在 QuickBooks 端（例如，必需的自定义字段），请登录 QuickBooks 并检查交易模板是否具有 LedgerPort 无法填充的必填字段。
如果以上方法均无法解决您的错误，您审计日志中的完整错误消息通常会指出具体原因。请参阅阅读和筛选审计日志，查找并阅读任何失败记录的详细错误消息。
日志保留提醒：您可以查看审计日志的范围取决于您的套餐。免费套餐保留日志 7 天，增长套餐保留 30 天，规模套餐保留 90 天，企业套餐无限期保留。要访问更早的日志，您可以升级您的套餐。
如果您仍遇到问题，请联系我们，并提供受影响的订单号以及审计日志中错误的屏幕截图。我们的支持团队将能够提供帮助。
