Merchant API v1beta 已于 2026 年 2 月 28 日停用并关停。如需了解迁移到最新稳定版的步骤，请参阅从 v1beta 迁移到 v1。

常见问题解答

本部分解答了与 Merchant API 的开发者注册相关的常见问题。

一般注册

有关注册流程的常见问题：

使用 Merchant API 是否必须注册开发者账号？

可以。您必须注册开发者联系信息，以便 Google 可以发送重要的 API 特定更新，例如服务公告和新功能信息。

如果您只是想探索和测试 Merchant API，可以使用 Google OAuth Playground 和 API Explorer 等无需注册的工具。

我需要多久登记一次？

注册是针对每个 Google Cloud 项目的一次性设置。无论您是否使用多个商家账号，都只需执行一次注册操作，该操作适用于关联的 Google Cloud 项目中的所有用户和服务账号。

成功注册 Google Cloud 项目后，除非通过调用 unregisterGcp 方法明确移除该关联，否则该关联会一直处于有效状态。您无法注册共享的 Google 所有项目，例如 APIs Explorer 或 OAuth Playground。

我应该提供哪个电子邮件地址作为开发者联系信息？

我们建议使用个人的公司电子邮件地址。或者，您也可以使用常规群组别名。您不能使用服务账号电子邮件地址，因为相关通信是发送给真人收件人的。Google 会发送重要的 API 特定更新，例如服务公告和新功能信息。

如果该电子邮件地址属于 Merchant Center 账号中的现有用户，系统会自动向该用户授予 API_DEVELOPER 角色。如果不是，则向该地址发送邀请。

在 registerGcp 方法中，开发者联系电子邮件地址字段是可选的。如果您在注册时未为此字段提供值，则必须在 Merchant Center 界面中或通过调用 accounts.users.create 方法创建一个具有 API_DEVELOPER 角色的用户。

开发者联系电子邮件地址是否需要是 Google 账号？

可以。如需使用现有的非 Google 电子邮件地址，您可以在创建 Google 账号注册流程中选择使用现有电子邮件地址选项，以将其与 Google 账号相关联。您无法使用服务账号电子邮件地址，因为服务账号无法接收电子邮件。

如何对注册调用执行身份验证和授权？

根据您的使用场景，注册调用的身份验证和授权有两种不同的方案：

OAuth 2.0：适用于管理多个商家账号的第三方提供商或代理机构
服务账号：用于访问您自己的 Merchant Center 账号

无障碍功能的替代文本

上图显示了注册调用的两种身份验证和授权流程。您可以从以下选项中进行选择：

将 OAuth 与关联到 Google 账号的电子邮件地址（例如 account@email.com）搭配使用
使用服务账号，例如 sa@project.iam.gserviceaccount.com

如果您决定使用 OAuth，请执行以下操作：

在 Google Cloud 项目中为您的电子邮件地址创建 OAuth 凭据
确保授权电子邮件地址存在于您的 Merchant Center 中，并且具有 ADMIN 访问权限类型

如果您决定使用服务账号，请执行以下操作：

确保服务账号存在于您的 Google Cloud 项目中
确保与服务账号关联的电子邮件地址存在于您的 Merchant Center 账号中，并且具有 ADMIN 访问权限类型

使用直接 API 调用或客户端库，在身份验证身份的安全上下文下执行注册调用。提供开发者的联系电子邮件地址，例如 developer@email.com。

如果注册调用成功，则 Merchant Center 中会存在一个具有所提供的开发者电子邮件地址和 API_DEVELOPER 角色的用户。您会收到 DeveloperRegistration 资源作为响应。

身份验证电子邮件地址与开发者联系电子邮件地址有何区别？

这两个电子邮件地址在 Merchant API 生态系统中具有不同的用途：

身份验证电子邮件地址：您通常使用与您的 Google 账号或服务账号关联的电子邮件地址作为身份来授权对 Merchant API 的请求，前提是：
- 该用户存在于您的 Merchant Center 账号中，并且拥有 ADMIN 角色。
- 已启用 Merchant API 的 Google Cloud 项目托管着 OAuth 客户端或与授权 API 调用的电子邮件地址关联的服务账号。
开发者联系电子邮件地址：开发者联系电子邮件地址也必须与 Google 账号相关联，但它主要用于接收 Google 发送的重要服务公告和 API 更新信息。它可以属于某个用户，也可以属于某个用户群组。默认情况下，该用户在 Merchant Center 中拥有 API developer 角色。

我是否必须接受通过开发者联系电子邮件地址收到的邀请？

可以。您提供的开发者联系电子邮件地址的收件人有 14 天的时间来接受邀请。只有在他们接受邀请后，注册流程才算完成。不过，您可以在这段时间内执行 API 调用。

如果未在指定时间内接受邀请，邀请链接将失效。您将无法再执行 Merchant API 调用，并且必须重新开始注册流程。

账号和项目管理

关于账号和项目管理的常见问题：

我使用多个 Merchant Center 账号。我是否需要向 Merchant API 注册我想要使用的每个 Merchant Center 账号？

不可以。如果您是第三方开发者或管理多个商家账号的代理机构，请使用您自己的主要 Merchant Center 账号注册 Google Cloud 项目，而不是使用每个商家的账号。这样一来，您在为商家处理所有 API 相关事宜时，就代表了开发者。

我使用多个 Merchant Center 账号。如何选择我的主要 Merchant Center 账号？

选择要使用的主账户取决于您的商家类型：

已拥有高级账号的购物平台：如果您的商家以购物平台的形式运营，并且已拥有代表整个平台的高级账号，请使用此现有账号 ID 作为主要 Merchant Center 账号。
购物比较服务 (CSS)：如果您是 CSS，请使用您的唯一 CSS 账号 ID 或 CSS 组账号 ID。
代理机构、开发者和其他第三方：如果您是管理多个商家账号的第三方企业（例如代理机构或第三方开发者），但没有代表您企业的单个 Merchant Center ID，则应创建一个新的主 Merchant Center 账号，并申请将其转换为高级账号。

将 Google Cloud 项目注册到您的主要 Merchant Center 账号后，您可以使用该项目来管理您有权访问的任何其他 Merchant Center 账号，而无需单独注册这些账号。

我使用多个 Google Cloud 项目。我是否需要分别注册？

可以。由于注册过程会关联调用 Google Cloud 项目，因此您必须从用于进行 API 调用的每个 Google Cloud 项目中执行 registerGcp 调用。

一个 Google Cloud 项目一次只能注册到一个 Merchant Center 账号。不过，一个 Merchant Center 账号可以注册多个 Google Cloud 项目。同样，您可以使用同一开发者电子邮件地址在多个 Google Cloud 项目或多个 Merchant Center 中执行多次注册。

如果我使用多个 Merchant Center 账号注册 Google Cloud 项目，会发生什么情况？

尝试注册已在其他 Merchant Center 账号中注册的 Google Cloud 项目会导致 ALREADY_REGISTERED 错误。

如何对开发者注册 API 调用进行身份验证？

如需对 Merchant API 的开发者注册 API 调用进行身份验证，您可以使用通过 Google Cloud 项目管理的凭据。您可以通过以下两种主要方式来指定执行身份验证的身份：

使用 OAuth 2.0 的 Google 账号（例如 Gmail）：此方法使用在您的 Google Cloud 项目中生成的 OAuth 2.0 客户端凭据。API 调用是代表用户登录的特定 Google 账号获得授权的。
服务账号：此方法使用 Google Cloud 服务账号，这是一种特殊类型的 Google 账号，专为应用而设计。服务账号的凭据也在您的 Google Cloud 项目中进行管理。

若要成功注册为开发者，身份验证身份（Google 账号或服务账号）必须在 Merchant Center 中满足以下条件：

在 Merchant Center 中以用户身份存在：与进行身份验证的 Google 账号或服务账号关联的电子邮件地址必须已添加到您要注册的 Merchant Center 账号中，且已添加为用户。
需要管理员角色：相应用户必须在特定 Merchant Center 账号中被分配 ADMIN 角色。

发出 API 调用时：

如果您使用的是直接 API 调用，则必须在 Authorization 标头中获取并提供有效的访问令牌。此令牌是通过 Google 账号的 OAuth 2.0 流程或服务账号的服务器到服务器身份验证流程生成的。
Google 提供的客户端库通常会处理获取和刷新访问令牌的复杂性，作为其配置的一部分。

进行身份验证的用户可能与开发者联系人用户不是同一用户。如需了解详情，请参阅身份验证电子邮件地址与开发者联系电子邮件地址有何区别？

我需要多久刷新一次访问令牌？

服务账号和 OAuth 2.0 的访问令牌通常会在 1 小时后过期。不过，获取新令牌的机制取决于您使用的身份验证方法：

服务账号使用私钥或环境凭据在需要时创建新的访问令牌。
OAuth 2.0 流程使用 refresh_token 调用 Google OAuth2 令牌端点，以接收新的 1 小时访问令牌。

我们强烈建议您使用官方 Google 身份验证库，该库会自动处理此轮换，因此您的应用永远不会出现停机情况。

用户和角色

关于用户和角色的常见问题：

开发者电子邮件账号是否必须已存在于 Merchant Center 中？

不可以。如果注册电子邮件账号尚不存在于 Merchant Center 中，Merchant API 会在 Merchant Center 中创建该账号，并将其状态设置为“待处理”。如果开发者电子邮件地址属于 Merchant Center 账号中的现有用户，系统会自动向该用户授予 API_DEVELOPER 角色。

开发者联系电子邮件地址是否需要在 Merchant Center 中拥有管理员权限？

不需要。与开发者联系电子邮件地址关联的 Merchant Center 用户默认拥有接收重要通知所需的 API_DEVELOPER 角色。不过，该角色在 Merchant Center 内的权限最低。如需允许此用户进行其他 API 调用或在 Merchant Center 界面中管理设置，您需要为其授予其他角色，例如 STANDARD 或 ADMIN。如需详细了解 Merchant Center 角色，请参阅“访问权限类型”。

“API 开发者”角色拥有哪些权限？

API Developer 角色是 Merchant Center 中权限最少的角色。如果您计划使用开发者联系电子邮件地址来授权对 Merchant API 的调用，建议添加 ADMIN 或 STANDARD 权限，以允许用户执行 API 调用。

我是否需要注册每个调用 API 的开发者用户或服务账号？

不可以。开发者注册与用于进行 API 调用的 Google Cloud 项目相关联，而不是与个人用户或服务账号相关联。Google Cloud 项目成功注册到您的主 Merchant Center 账号后，您可以使用通过关联的 Google Cloud 项目管理的任何身份（使用 OAuth 凭据或服务账号）来授权 Merchant API 调用，前提是这些身份存在于您的 Merchant Center 账号中，并且已分配 ADMIN 角色。

在初始注册后，如何更改开发者联系电子邮件地址？

如需管理或更改联系人，请使用标准 accounts.users 服务或 Merchant Center 界面中的“访问权限和服务”页面，以添加或移除具有 API Developer 角色的用户。

如果从 Merchant Center 账号中移除了最后一位“API 开发者”用户，会发生什么情况？

系统会启动 30 天的宽限期，以避免服务立即中断。在此期间：

管理员会通过电子邮件收到三封强制性服务公告（通常是在屏蔽前大约 30 天、17 天和 4 天）。
API 调用将继续正常运行。
如果在宽限期结束之前未添加新的 API Developer，则来自关联 Google Cloud 项目的 API 调用将被阻止，并显示 AUTH_GCP_NOT_REGISTERED 错误。

30 天宽限期结束后，系统会屏蔽相关联的 Google Cloud 项目发出的 API 调用，并且这些项目会收到 AUTH_GCP_NOT_REGISTERED 错误，直到恢复有效的开发者联系信息。

如果开发者注册所用的 Merchant Center ID 被删除，会怎么样？

在集成处于有效状态时，请勿删除用于开发者注册的 Merchant Center 账号。删除此账号会立即中断您的集成，并且您将无法再通过关联的 Google Cloud 项目执行 API 调用。

如果您必须删除该 Merchant Center 账号，应先调用 unregisterGcp 方法来安全地移除关联，然后再继续删除 Merchant Center ID。如果您想继续使用 Merchant API，需要在取消注册当前 Merchant Center ID 后立即注册另一个 Merchant Center ID。只有在完成上述操作后，才能继续删除 Merchant Center ID。

特殊使用情形

有关特殊用例的常见问题：

我是管理多个商家账号的代理机构或第三方开发者。设置此功能的最佳方式是什么？

第三方开发者和代理机构应维护自己的主要 Merchant Center 账号，并将所有 Google Cloud 项目注册到该集中式账号。请勿使用每个商家的个人账号注册您的 Google Cloud 项目。

Google 应用脚本的注册流程是怎样的？

Apps 脚本通常在默认的 Google Cloud 项目中运行。您必须向 Merchant Center 账号注册此默认 Google Cloud ID。Google Cloud ID 由 API 自动获取，因此您无需将其作为参数提供。

我可以查看某个 Merchant Center ID 是否已注册到特定 Google Cloud 项目 ID 吗？

可以。您可以使用 getAccountForGcpRegistration 方法检查哪个 Merchant Center ID 已注册到特定 Google Cloud 项目。如需移除 Google Cloud 项目与您的 Merchant Center 账号之间的关联，请使用 unregisterGcp 方法。