> 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-uploads-and-connections.md).

# 排查产品目录上传和连接问题

impact.com 必须先成功接收商品目录文件，才能处理该目录。本指南按上传方式组织，请前往与您的商品目录所用方式对应的部分： [*从 URL 拉取*](#pull-from-url-recommended), [*集成购物车导入*](#integrated-shopping-cart-import-recommended), [*impact.com FTP 服务器*](#impact.com-ftp-server), [*impact.com SFTP 服务器*](#impact.com-sftp-server)或 [*直接上传*](#direct-upload)。如果您不确定商品目录使用的是哪种方式，请编辑该目录并检查其 [*上传方式* 设置](https://help.impact.com/brand/zh/what-would-you-like-to-learn-about/platform-features/product-catalogs/add-product-catalogs-as-a-brand.md#upload-your-product-catalog).

impact.com 推荐使用 *从 URL 拉取* 或 *集成购物车导入*，因为这两种方式下，impact.com 可以控制商品目录的拉取时间和更新频率。如果您使用 impact.com FTP 服务器、impact.com SFTP 服务器或 *直接上传*，则需要自行定期提供更新后的商品目录数据。最好每天更新，每周更新也可以。

如果 impact.com 已收到您的文件，但商品目录显示错误或警告，请参阅 [排查商品目录错误和警告](https://help.impact.com/brand/zh/what-would-you-like-to-learn-about/platform-features/product-catalogs/troubleshoot-product-catalog-errors-and-warnings.md).

## 从 URL 拉取（推荐）

“ *从 URL 拉取* ”支持的协议包括 `http://`, `https://`, `ftp://`和 `sftp://`。如果您的商品目录无法正常加载、更新或处理，请使用下表识别并解决问题。

| 问题                | 检查内容                                                                                                                                                                         | 解决方法                                                                                                                                                                    |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| URL 不是直接下载链接      | 在浏览器中打开您的 URL。如果它重定向到登录页面或云存储的落地页，或者返回 404 或 403 错误，则该 URL 不是直接下载链接。                                                                                                         | 将 URL 更新为在浏览器中打开时可直接下载文件或以原始数据形式显示文件的链接。                                                                                                                                |
| 文件名不匹配            | 商品目录设置中的 *上传文件名* 必须与 URL 指向的实际文件名完全一致，包括扩展名（`.csv`, `.xml`, `.txt`, `.gz`).                                                                                                  | 更新 *上传文件名* ，使其与您的文件名完全一致。即使有细微差异，也会导致 *No catalog found for the request* 错误。                                                                                            |
| 格式或分隔符不匹配         | 确认所选格式（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。如果您的数据 feed 需要通过浏览器登录，请将目录切换为其他上传方式，例如 *直接上传* 或 *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 下载已上传的目录，并与源文件进行比较，找出数据丢失的位置。根据需要更新字段名称或映射，然后重新上传。                                                                                                         |

## 电商平台集成导入（推荐）

此方法会从现有电商平台拉取目录。大多数连接问题都源于凭据错误或缺少读取权限。请在下方查找您的平台。

### Shopify（推荐）

如果您看到类似以下的错误 *连接到 Shopify 时 HTTP 状态代码不成功：401* 或 *在目录文件中未找到有效记录*，通常是身份验证信息或权限导致的问题。

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

有关完整的设置步骤，请参阅 [Shopify 商品目录集成指南](https://integrations.impact.com/integration-guides/for-brands/plugin-integrations/e-commerce/integrate-with-shopify/shopify-product-catalog).

### Amazon（推荐）

Amazon 购物车集成仅适用于订阅了 [卖家订阅](https://help.impact.com/brand/zh/what-would-you-like-to-learn-about/seller-program/amazon-seller-program/amazon-seller-program-explained.md) 的品牌，且不支持自助使用。由于 Amazon API 的限制，自动从 Amazon 导入的商品目录最多包含 1,000 件商品。如果卖家商品目录中有超过 1,000 件商品，请改用文件上传方式，例如 *通过 URL 拉取*。

有关设置步骤，请参阅 [Amazon 集成指南](https://integrations.impact.com/integration-guides/for-brands/plugin-integrations/e-commerce/integrate-with-amazon).

### BigCommerce

连接 BigCommerce 需要两个值，以及正确的只读权限。

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

有关详情，请参阅 BigCommerce 的指南： [创建 API 令牌](https://developer.bigcommerce.com/docs/storefront-auth/tokens#create-a-token).

### WooCommerce

如果你看到 *无法连接到 WooCommerce。请重试*，并检查您的凭据和 API 设置。

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

如需参考，请参阅 [WooCommerce REST API 文档](https://woocommerce.com/document/woocommerce-rest-api/).

### Shoplazza

您的 Shoplazza 私有应用需要对以下资源具有读取权限： `product`, `collection`和 `shop`.

有关设置步骤，请参阅 Shoplazza 关于 [创建私有应用](https://www.shoplazza.dev/reference/quick-construction-of-private-apps).

## impact.com FTP 服务器

大多数 FTP 问题都与连接设置或凭据有关。

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

## impact.com SFTP 服务器

impact.com SFTP 服务器是一种专用上传方式，仅用于特定集成。

| 问题          | 检查内容                                                           | 解决方法                                                                                            |
| ----------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| 您的信息流平台无法连接 | 确认您的平台连接的主机是 `products.impact.com` ，端口为 `22`，并且使用的是为您的账户签发的凭据。 | 使用 FileZilla 或 Cyberduck 等标准 SFTP 客户端测试同一组凭据。如果客户端可以连接，但您的信息流平台仍无法连接，请按照以下步骤将目录切换为 *从 URL 拉取* 。 |

### 从推送切换为拉取

impact.com 建议拉取 Feed，而不是推送 Feed。当 impact.com 直接从 Feed 平台的 SFTP 服务器（例如 SFTPGo）拉取 Feed 时，impact.com 可以控制商品目录的更新时间和更新频率，您也不再需要依赖 impact.com 的 SFTP 服务器。切换为拉取也能解决 Feed 平台（例如 Feedonomics）向 impact.com 的 SFTP 服务器推送文件时可能遇到的连接错误。

切换之前，请让 Feed 平台（例如 Feedonomics）为您的 Feed 设置一个出站 SFTP 位置，并提供以下信息：

* SFTP/FTP 主机和端口（例如 sftpgo.feedonomics.com:22）
* 用户名和密码
* 文件路径（例如 incoming/catalog\_feed.txt.gz）

{% hint style="warning" %}
**警告：** 请更新现有商品目录，而不要创建新目录。使用相同 *上传文件名* 的新目录会返回 *文件名已被占用* 错误，而且现有商品目录可能已用于其他计划。
{% endhint %}

1. 在左侧导航菜单中，选择 ![](https://1186853034-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwMLlMoFBtKJa8ptd3zaw%2Fuploads%2Fgit-blob-230534471fef5f40808e921e41ee44e4a06ded03%2Fe6cb9548999afdc1ed3ce4942e4cb5b45b5cecbd323267aac2a7cd1915fccc09.svg?alt=media) **\[互动]** **→** **内容** **→** **商品** **→** [**商品目录**](https://app.impact.com/secure/advertiser/engage/ads/productcatalogs/manage-ads-product-catalog-flow.ihtml).
2. 将鼠标悬停在现有目录上，然后选择 **编辑**.
3. 在 *上传方式* 部分中，选择 **从 URL 拉取**.
4. 选择与 Feed 文件匹配的 **格式** 。
5. 输入 **上传文件名**，确保文件名完全一致，包括扩展名。
6. 输入 **拉取 URL** ，格式为 `sftp://[username]:[password]@[host]:22/[path/to/file]`.
   * 对凭据中的任何特殊字符进行 URL 编码，例如 `@` 会变为 `%40`.
7. 选择 **获取频率**, **获取时间**和 **时区**.
8. 选择 **保存**.

## 直接上传

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

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


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
