> For the complete documentation index, see [llms.txt](https://help.impact.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.impact.com/brand/zh/what-would-you-like-to-learn-about/platform-features/product-catalogs/troubleshoot-product-catalog-errors-and-warnings.md).

# 排查产品目录错误与警告

每个产品目录都有一个健康评分，用于指示目录中存在哪些问题（如果有的话）。问题可能在任何阶段出现：当文件被上传或连接时、处理之后，或者当你的合作伙伴尝试查看和推广你的产品时。请使用本指南逐步排查各阶段的问题，并将你的目录提升到 *优秀* 范围内。

{% hint style="info" %}
**提示：** 一个健康的目录不仅仅是清除错误。请遵循 [产品目录最佳实践](/brand/zh/what-would-you-like-to-learn-about/platform-features/product-catalogs/product-catalog-best-practices.md) 以保持数据完整、结构良好，并为更高的曝光度和表现做好准备。
{% endhint %}

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2FZTsEfqMM8xnWruw90lbm%2Feng-350-5.mp4?alt=media&token=80c0e779-2118-482b-9a88-10ff3da3f8a4>" %}

## 目录健康评分

1. 从左侧导航菜单中选择 ![](/files/209022bdb234289211a24a980f6227a8684cc439) **\[Engage]** **→** **内容** **→** **产品** **→** [**产品目录**](https://app.impact.com/secure/advertiser/engage/ads/productcatalogs/manage-ads-product-catalog-flow.ihtml).
2. 如果某个目录存在任何错误、警告或重复行项， *健康* 列会显示各项的数量。

   * 当下一次拉取事件发生时，会自动获取目录更新的上传方式。

   <div data-with-frame="true"><figure><img src="/files/8855092c100d76565e3a29df8f6e2ef9bd983c2a" alt="" width="563"><figcaption></figcaption></figure></div>

<details>

<summary>健康说明</summary>

| 健康指示    | 说明                                            |
| ------- | --------------------------------------------- |
| **待处理** | 你的产品目录正在等待首次上传或数据拉取。                          |
| **处理中** | 你的产品目录正在处理中。                                  |
| **优秀**  | 表示目录健康。该产品数据集完整且结构良好，因此最有可能表现出色。              |
| **良好**  | 表示某些包含关键信息的建议字段可能缺失，例如类目或描述。弥补这些缺失可提升目录的整体质量。 |
| **较差**  | 表示你提供的记录中有超过 10% 缺少必需信息。必须修复此目录并重新上传。         |

</details>

## 排查上传和连接问题

在目录可以处理之前，impact.com 必须成功接收它。以下步骤按你在创建目录时选择的上传方式分组。如果你不确定当前使用的是哪种方式，请选择该目录并查看其 *上传方式* 设置。

### 直接上传

直接上传问题通常是格式或文件名不匹配，或者文件超过 1 GB 限制。

| 问题       | 检查内容                                                                     | 如何修复                                                                       |
| -------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| 选择了错误的格式 | 你选择的格式（例如 TXT）与上传的文件（例如 XML）不匹配。                                         | 重新上传并选择与文件匹配的格式。XML 文件使用 `.xml` 扩展名，CSV 文件使用 `.csv`，而以 TAB 分隔的文件使用 `.txt`. |
| 文件名不匹配   | 你上传的文件名称必须与 *上传文件名* 中设置的名称完全一致，包括扩展名。                                    | 重命名你的文件，或更新 *上传文件名* ，使二者完全一致。                                              |
| 压缩文件无法处理 | impact.com 支持 gzip 和标准 zip 压缩文件。压缩文件可以使用第二个扩展名来表示压缩，例如 `catalog.xml.gz`. | 请确认你的压缩类型为 gzip 或 zip，并且文件针对其格式和压缩都使用了正确的扩展名。                              |

### impact.com FTP 服务器

大多数 FTP 问题都归结为连接设置或凭据。

| 问题        | 检查内容                                       | 如何修复                                                                                                    |
| --------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| 无法连接到服务器  | 请确认你正在连接到主机 `products.impact.com` 端口 `21`. | 使用正确的主机和端口更新你的 FTP 客户端，然后重新连接。                                                                          |
| 缺少 FTP 凭据 | 你需要使用为你的账户签发的 FTP 登录名和密码才能连接。              | 找到你的 *FTP 产品数据系统凭据* 在你账户的技术配置设置中。如果你找不到或无法访问它们， [请联系支持团队](https://app.impact.com/support/portal.ihtml). |

### 从 URL 拉取

支持的协议为 *从 URL 拉取* 有 `http://`, `https://`, `ftp://`，以及 `sftp://`。如果你的目录未能正确加载、更新或处理，请使用下表识别并解决问题。

| 问题               | 检查内容                                                                                                                                                                               | 如何修复                                                                                                                                                                   |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| URL 不是直接下载链接     | 在浏览器中打开你的 URL。如果它重定向到登录页面、云存储落地页，或者返回 404 或 403 错误，则该 URL 不是直接下载链接。                                                                                                                | 将 URL 更新为可直接下载文件的链接，或在浏览器中打开时以原始数据形式显示的链接。                                                                                                                             |
| 文件名不匹配           | 你在目录设置中的 *上传文件名* 该项必须与 URL 处的实际文件名完全一致，包括扩展名（`.csv`, `.xml`, `.txt`, `.gz`).                                                                                                       | 更新 *上传文件名* 使其与你的文件名完全一致。哪怕是很小的不匹配也会导致 *未找到与该请求对应的目录* 错误。                                                                                                               |
| 格式或分隔符不匹配        | 请确认所选格式（CSV、TXT、XML、GMC）与你的文件一致。如果你使用的是分隔文件，请确认分隔符（逗号、制表符、竖线）与配置一致。                                                                                                                | 在目录设置中更正格式或分隔符。不匹配会导致 *未找到有效记录* 错误。                                                                                                                                    |
| FTP/SFTP：凭据或路径无效 | 请验证你的 URL 使用的格式为 `sftp://{username}:{password}@{host}/{file_path}`。路径必须指向确切的文件，而不仅仅是目录。凭据中的特殊字符必须进行 URL 编码（例如， `@` 会变成 `%40`).                                                     | 使用 FileZilla 等 FTP 客户端测试你的凭据。使用更正后的凭据和完整文件路径更新 URL。                                                                                                                    |
| 拉取超时或连接失败        | 你的服务器防火墙可能正在阻止 impact.com 的请求。                                                                                                                                                     | 请联系你的托管服务提供商或 IT 团队，将 impact.com 的 IP 地址范围加入允许列表。                                                                                                                      |
| URL 需要身份验证       | 此上传方式不支持基于会话或基于 cookie 的身份验证。                                                                                                                                                      | 请使用可公开访问的直接下载 URL，或在 URL 中嵌入 HTTP Basic Auth（`https://user:pass@host/path`），或使用在 URL 中包含凭据的 FTP/SFTP。如果你的数据源需要基于浏览器的登录，请将目录切换到其他上传方式，例如 *直接上传* 或 *impact.com FTP 服务器*. |
| URL 超过 2,048 个字符 | 带签名的云存储 URL 可能超过 2,048 字符限制，并且可能被截断。                                                                                                                                               | 使用可保留直接下载的 URL 缩短服务，或将文件托管在更短的 URL 下。                                                                                                                                  |
| 目录卡在“处理中”或“待处理”  | 检查该 URL 处的文件是否仍可访问，以及对于你的拉取频率而言文件大小是否异常过大。                                                                                                                                         | 请确认文件可用。如果目录仍停留在 *处理中* 或 *待处理*, [请联系支持团队](https://app.impact.com/support/portal.ihtml) ，请请求手动重新处理。                                                                     |
| 目录停止自动更新         | 检查该文件是否仍可在同一 URL 访问，以及文件名、格式或服务器访问设置是否已更改。                                                                                                                                         | 在原始 URL 恢复该文件，或更新目录设置以反映新的 URL 或文件名。对于大型目录（1,000,000+ 项），请考虑降低拉取频率以避免超时。                                                                                               |
| 上传后缺少字段或数据       | 请确认你的字段名称与所选格式的规范一致，例如 [Google Merchant Center 字段](https://support.google.com/merchants/answer/7052112) 适用于 GMC 格式。将标准规范之外的自定义字段映射到 impact.com 的自定义字段槽位（`Numeric1`, `Text1`，依此类推）。 | 从 impact.com 下载你上传的目录，并将其与源文件进行比较，以找出数据丢失的位置。根据需要更新字段名称或映射，然后重新上传。                                                                                                     |

### 集成购物车导入

此方式会从现有电子商务平台拉取你的目录。大多数连接问题都归结为凭据不正确或缺少读取权限。请在下方选择你的平台。

{% tabs %}
{% tab title="Shopify" %}
如果你看到类似以下错误： *连接 Shopify 时 HTTP 状态码不成功：401* 或 *目录文件中未找到有效记录*，通常是你的身份验证信息或权限导致的。

* 你的密码必须是 **Admin API 访问令牌**，其开头为 `shpat_` （或 `shap_`）。你可以在 Shopify 管理后台的 **应用** **→** **API 凭据** **→** **Admin API 访问令牌**.
* 中找到它。如果你没有看到 **Admin API 访问令牌**，请选择 **安装应用** 在 Shopify 中生成它。
* 请确认 `read_products` 权限（scope）已授予该应用。否则，Shopify 会返回错误，说明该操作需要商家批准 `read_products` 权限范围。
* 对于集合，请在 Shopify 管理后台的 **产品** **→** **集合**中找到集合 ID。选择该集合；其 ID 会显示在页面 URL 的末尾。

有关完整设置步骤，请参阅 [Shopify 产品目录集成指南](https://integrations.impact.com/impact-brand/docs/shopify-product-catalog).
{% endtab %}

{% tab title="WooCommerce" %}
如果你看到 *连接 WooCommerce 失败。请重试*，请检查你的凭据和 API 设置。

* 你的 **API 用户名** 就是你的 WooCommerce *消费者密钥*，而你的 **API 密码** 就是你的 *消费者密钥*.
* 在 WooCommerce 中启用旧版 REST API： **WooCommerce** **→** **设置** **→** **高级** **→** **旧版 API**，然后勾选复选框以启用它。

供参考，请参阅 [WooCommerce REST API 文档](https://woocommerce.com/document/woocommerce-rest-api/).
{% endtab %}

{% tab title="BigCommerce" %}
连接 BigCommerce 需要两个值以及正确的只读权限。

* 输入你的 **店铺哈希值** 和 **访问令牌** 在 impact.com 界面中。你的店铺哈希值是店铺 API 路径中的标识符。
* 将 **产品** 和 **信息与设置** 权限设为只读，在 BigCommerce 中创建 API 账户时如此设置。

供参考，请参阅 BigCommerce 关于以下内容的指南： [创建 API 令牌](https://developer.bigcommerce.com/docs/storefront-auth/tokens#create-a-token).
{% endtab %}

{% tab title="Shoplazza" %}
你的 Shoplazza 私有应用需要对以下资源具有读取权限： `产品`, `集合`，以及 `店铺`.

有关设置步骤，请参阅 Shoplazza 关于以下内容的指南： [构建私有应用](https://www.shoplazza.dev/reference/quick-construction-of-private-apps).
{% endtab %}
{% endtabs %}

## 上传后排查错误和警告

文件接收后，impact.com 会验证每条记录。错误会阻止记录被处理，而警告会标记已接受但可能引发问题的数据。请使用以下部分来解释并解决它们。

### 查看错误和警告

1. 在 *健康* 列中，选择 **错误**, **警告**，或 **重复项** 链接。
   * 你将被重定向到一个包含更多细节的页面。impact.com 仅代表重复组中的第一项；所有与第一项重复的条目都会被忽略。
2. 你也可以使用 *搜索* 页面顶部的字段和筛选器来梳理这些问题。
3. 检查这些问题并按需修改，然后重新上传你的产品目录。

<details>

<summary>筛选器说明</summary>

| 筛选   | 说明                                            |
| ---- | --------------------------------------------- |
| 错误类型 | 专门筛选 *错误*, *警告*, *重复项*，或 *全部* 问题。             |
| 必需   | 筛选任何特定缺失的必需产品目录字段，或 *全部* 字段。                  |
| 建议   | 筛选任何特定缺失的推荐产品目录字段，或 *全部* 字段。                  |
| 无效   | 筛选任何特定的基于校验的错误，例如重复 SKU、无效的 Google 类目代码或其他错误。 |

</details>

<details>

<summary>常见错误和警告信息</summary>

| 消息                                                                   | 说明                                                                                               |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| *记录“X”：缺少必需字段：（字段名）*                                                 | 指定行缺少一个或多个必需字段。                                                                                  |
| *记录“X”：CatalogItemId(CatalogItemId)：缺少必需字段：（字段名）*                    | 数据文件中的某一行缺少必需字段。                                                                                 |
| *未找到与该请求对应的目录。请检查上传文件的文件名是否与目录中注册的文件名相同*                             | 你在目录设置中的 *上传文件名* 在 *上传方式* 创建目录时设置的部分与您上传文件的名称不完全一致。                                              |
| *目录文件中没有属性*                                                          | 产品目录数据文件没有任何可处理的数据。                                                                              |
| *带有该 ID 的目录项在目录中出现多次，第一项之后的条目将被忽略*                                   | 两个或多个条目具有相同的 ID。所有产品都需要唯一值，重复条目不会被处理。                                                            |
| *记录“X”存在错误：（第 X 行）封装标记与分隔符之间存在无效字符*                                  | 某一行中双引号的使用无效。请用双引号将字段括起来，并将其他所有双引号替换为两个双引号。                                                      |
| *（起始行 X）在封装标记完成前已到达 EOF*                                             | EOF 表示“文件末尾”。所提到的起始行有一个没有闭合的开头双引号，或者意外的换行中断了数据流。                                                 |
| *解析（目录类型）字段时出错：值为：（字段）*                                              | 产品字段无效，无法接受。                                                                                     |
| *记录（recordNumber）存在错误：分隔值数量（FieldsLength）与预期值（ColumnNamesLength）不匹配* | 对于给定的行，数据存在于一个没有标题的列中。                                                                           |
| *目录文件中未找到有效记录*                                                       | 数据文件为空、检测到的数据无效，或者指定的文件名不正确。                                                                     |
| *文件中超过 10% 的记录存在错误*                                                  | 如果出现这种情况，则无法处理该数据文件。请参阅 *了解 10% 错误阈值* 下方。                                                        |
| *处理失败，因为发生了内部系统错误...*                                                | 你无需采取任何操作。最后一个成功处理的目录仍将对媒体合作伙伴可用。请参阅 [impact.com 状态页面](https://status.impact.com/) 以了解服务中断的详细信息。 |
| *值为（field value）的字段（field name）没有有效的协议*                              | 该字段值不是格式正确的 URL。                                                                                 |

</details>

### 格式和分隔符警告

| 问题                            | 如何修复                                       |
| ----------------------------- | ------------------------------------------ |
| 分隔符问题：错误的逗号、制表符或空行会破坏字段之间的边界。 | 请在目录文件中更正分隔符用法，使每个字段都以一致方式分隔，然后重新上传。       |
| 描述字段中的换行会中断记录处理。              | 分隔文本格式（CSV 和 TSV）不支持换行。上传前请移除描述等文本字段中的换行符。 |

### Google Merchant Center 格式错误

如果你使用 Google Merchant Center（GMC）格式，大多数问题都出现在该格式的 `类目` 部分、预定义字段值或 XML 结构上。

{% tabs %}
{% tab title="缺少 Google 产品类目" %}
当你在 *错误* 中选择 *产品目录* 屏幕上时，你可能会在 *缺少 Google 产品类目* 中看到该项。 *建议* 列中看到该项。这表示你的目录中未包含 Google 类目代码或完整的 Google 类目字符串。

要解决此问题，请参阅你的 [Google Merchant Center 账户](https://merchants.google.com/)。Google 会自动为商品建议类目；上传已更正的目录时请使用这些建议。

<div data-with-frame="true"><figure><img src="/files/a4fcbb83ed86088df351fae86d5cf06c7498d71a" alt=""><figcaption></figcaption></figure></div>
{% endtab %}

{% tab title="Google 产品类目不匹配" %}
当你在 *错误* 中选择 *产品目录* 屏幕上时，你可能会在 *Google 产品类目不匹配* 中看到该项。 *无效* 列中的内容。这表示你的目录中商品所使用的类目与预期的 [分类代码](https://www.google.com/basepages/producttype/taxonomy-with-ids.en-US.txt) （例如 7386）或 Google 提供的完整类目格式不匹配，例如：

`动物与宠物用品 > 宠物用品 > 鸟类用品 > 鸟笼配件 > 鸟笼食盆与水盆`

要解决此问题，请更正 Google 产品类目的列出格式，然后重新上传你的目录。

<div data-with-frame="true"><figure><img src="/files/2000eec488450ef0d0f6f385bf96dcc2d709402c" alt=""><figcaption></figcaption></figure></div>
{% endtab %}

{% tab title="可用性值不被接受" %}
类似这样的错误： *无法解析字段：availability，其值为* 表示某个预定义字段使用了 GMC 无法识别的值。对于 GMC 目录，类目和值必须精确无误。

* 请对 `availability` 字段使用该值。
* 支持的 availability 值为 `in_stock`, `out_of_stock`, `preorder`，以及 `backorder`.
* 检查可能影响格式的特殊符号，例如值字段中出现货币符号。
  {% endtab %}

{% tab title="XML：未找到有效记录" %}
如果您上传了 Google Merchant Center（XML 格式）目录并看到 *在目录文件中未找到有效记录。请修复文件并重新上传*，则 XML 结构很可能不正确。

XML 文件必须在其起始元素中包含 `rss`, `RDF`，或 `feed` 。请更正根元素并重新上传。
{% endtab %}
{% endtabs %}

{% hint style="info" %}
**eBay Commerce Merchant Center 格式：** 在 `.csv` 文件中，请将字段列值（类别）中的空格替换为下划线。例如，使用 `Item_Title` 而不是 `Item Title`.
{% endhint %}

### 了解 10% 错误阈值

如果上传文件中超过 10% 的记录包含错误，则该文件不会被处理。发生这种情况时：

* 您的目录将继续显示上次成功上传的版本，因此会显示较旧的 *上次成功提交* 时间戳。
* 你在目录设置中的 **查看商品** 选项仅在该目录 ID 之前成功上传过文件时才会出现。

修复已标记的记录，使错误少于 10%，然后重新上传。

## 让您的目录对合作伙伴可用

即使目录状况良好，在您将其设为可用并满足合作伙伴可见性要求之前，它仍无法传达给您的合作伙伴。如果您的目录已成功处理，但合作伙伴在可见性、商品访问或跟踪链接方面遇到问题，请使用本部分。

### 合作伙伴无法看到目录

请检查以下两个设置：

* 确保目录可供使用：
  1. 选择 ![](/files/209022bdb234289211a24a980f6227a8684cc439) **\[Engage]** **→** **内容** **→** **产品** **→** [**产品目录**](https://app.impact.com/secure/advertiser/engage/ads/productcatalogs/manage-ads-product-catalog-flow.ihtml) 并找到该目录。
  2. 选择 ![](/files/48274f9251fd79e93a99aad7b4393690b07a61c9) **\[更多]** 然后选择 **设为可用**.
* 检查是否限制了合作伙伴访问：
  1. 选择 ![](/files/209022bdb234289211a24a980f6227a8684cc439) **\[Engage]** **→** **内容** **→** **产品** **→** [**产品目录**](https://app.impact.com/secure/advertiser/engage/ads/productcatalogs/manage-ads-product-catalog-flow.ihtml) 并找到该目录。
  2. 将鼠标悬停在目录上，然后选择 **编辑**.
  3. 在 *限制合作伙伴访问* 部分，检查是否 **仅允许特定合作伙伴访问** 已 ![](/files/3980f01ba7b178cc917bfb7b270feb4fac2992c6) 开启。
  4. 如果是， ![](/files/c2dcdffe00f000bd34f794287e3006cfa55e8ce8) 将其关闭并选择 **保存**.

### 合作伙伴无法查看或搜索特定商品

商品要在合作伙伴界面中可见，必须满足以下所有要求：

* 原价大于 2.00 美元。
* 商品的库存状态不是 *缺货。*
* 该商品具有有效的商品 URL，并指向实时的商品详情页。
* 该商品具有图片 URL。
* 该商品位于一个没有 [规则](/brand/zh/what-would-you-like-to-learn-about/platform-features/product-catalogs/create-and-manage-product-catalog-rules.md) 应用的目录中。

### 合作伙伴跟踪链接返回“格式错误”错误

如果合作伙伴在使用您商品中的跟踪链接时看到“您点击的链接格式错误”，通常是因为未启用深度链接，或者商品的落地页域名未设置为允许的域名。要启用深度链接、设置允许的域名并解决此错误，请参阅 [为深度链接设置允许的域名](/brand/zh/what-would-you-like-to-learn-about/account-administration/program-settings/tracking-settings/set-up-permitted-domains-for-deep-linking.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.impact.com/brand/zh/what-would-you-like-to-learn-about/platform-features/product-catalogs/troubleshoot-product-catalog-errors-and-warnings.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.