Orders API

Orders API 使商家可以处理通过 Shopping Actions 收到的订单。通过此 API，加入的商家可以执行以下操作：

• 接收并确认新订单
• 反映订单的运输过程
• 提供为应对退货或其他活动进行的退款

注意：此程序仅适用于处于测试版模式时选择合作伙伴。

Orders API 使用入门

要使用 Orders API，请执行以下操作：

1. 在“Shopping Actions”中注册您的 Merchant Center 帐号。（这是对您的 Merchant Center 注册的补充。）请与我们联系，以确保您的 Google 帐号已注册。

2. 在您的 Merchant Center 帐号中同意 Shopping Actions 条款。为此，请勾选“Merchant Center > Google 线上消费 > 设置”复选框。
3. 配置新项目。作为此步骤的一部分，您将下载一个 JSON 密钥文件，并且可能需要您进行修改，如服务帐号密钥中所述。
   警告：安全存储此密钥文件并跟踪其位置。如果您丢失此文件，则无法再次下载，但您可以重复此步骤来创建一个新的项目，然后获得一个新的密钥文件。

   有关其他信息，请参阅配置 Google 控制台项目。

4. 向上一步创建的新 Google 服务帐号 (GSA) 添加“Shopping Actions Order Manager”角色。对于将在 Merchant Center 中使用 Orders API 或访问 Orders 视图的所有其他帐号，请执行此操作。
5. （可选）下载适合您的应用的 Content API 客户端库。
6. 修改 API 密钥（如果您是通过网络服务而不是使用库进行调用）。
7. 在您的应用中实现 OAuth 2.0 身份验证。或者，如获取访问令牌中所述，您可以获取要包含在 RESTful 请求中的访问令牌。
8. 调用 Orders API。使用沙盒模式测试您的 Orders API 实现情况，然后再将其部署到生产环境中。我们还提供了一个试用此 API 的快速教程。

分配 Order Manager 角色

在您使用 Orders API 之前，必须将“Shopping Actions Order Manager”角色分配给您的 Google 服务帐号 (GSA) 以及所有其他将访问 Merchant Center 中 Orders API 或 Orders 视图的帐号。

要分配 Order Manager 角色，请执行以下操作：

1. 打开 Merchant Center。
2. 点击右上角的三点状菜单并选择“用户”：

   

   Merchant Center 显示用户及其角色的列表。

   如果在下拉列表中没有看到“用户”选项，则表示您的帐号没有管理权限。

3. 点击一个用户所在的行进行修改。Merchant Center 会显示“用户偏好设置”视图。

   如果帐号不在用户列表中，请点击 + 图标添加帐号。

4. 在用户访问权限部分中，勾选 Shopping Actions Order Manager 复选框，如以下示例所示：

   

5. 点击保存按钮保存更改。

   Shopping Actions Order Manager 角色应出现在用户列表中此用户的旁边。对于将在 Merchant Center 中访问 Orders API 或 Orders 视图的所有帐号，请重复上述过程。

沙盒模式和生产环境模式

您可以在两种模式其中之一使用 Orders API，具体取决于是构建并测试沙盒中的实现情况，还是将 Orders API 部署到生产环境中。在沙盒模式下，您还有可能首次使用新的 API 功能。

您指明要在网址中使用的版本：

https://www.googleapis.com/content/mode/merchant_ID/orders/

其中，merchant_ID 是您的 Merchant Center ID，mode 指定要使用的模式：

• 生产环境模式（“v2”）：为了实现实时订单处理，请将网址中的 mode 指定为“/v2”，即可使用生产环境模式。例如：

  GET 'https://www.googleapis.com/content/v2/42/orders/'

• 沙盒模式（“v2sandbox”）：为了试验和发出测试请求，请将网址中的 mode 指定为“/v2sandbox”，即可使用沙盒模式。例如：

  GET 'https://www.googleapis.com/content/v2sandbox/42/orders/'

  沙盒模式还支持生产环境模式并不支持的下列方法：

  • createtestorder
  • advancetestorder
  • gettestordertemplate

教程：使用“试用此 API”功能

要在沙盒模式下快速创建测试订单，请使用 createtestorder 文档页面右侧的“试用此 API”框。“试用此 API”功能这一能力适用于所有 API 文档页面。

注意：要使用“试用此 API”，您登录的 Google 帐号必须已添加至 Merchant Center 并且被授予 “Shopping Actions Order Manager”角色权限，如 Orders API 使用入门所述。

要使用“试用此 API”创建一个测试订单，请执行以下操作：

1. 打开 API 参考并导航至 createtestorder 页面。

   请注意，“试用此 API”会调用您当前正在查看的文档的方法。例如，如果您查看的是 createtestorder 参考页面，“试用此 API”功能会调用 createtestorder。要调用 get，请导航至 get 参考页面。

2. 在 merchantId 请求参数字段中输入商家 ID。
3. 将 templateName 字段添加至请求正文，然后将其设置为下文所述的其中一个模板（例如“template1”）。

   以下示例显示了使用商家 ID“42”进行的简单调用：

   

4. 点击 Execute 按钮。

   Orders API 创建一个新的测试订单，并使用 HTTP 200 进行响应。响应信息包括新建订单的订单 ID，如以下示例所示：

   

5. 从响应信息中复制 orderId 的值。您可以在后续步骤中使用此订单的 ID。

后续步骤

创建一个测试订单后，您可以对此订单执行确认和发货过程，同时在每个步骤中设置其状态。常见的工作流程如下：

1. 使用 get 方法查看新建订单的内容。您还可以使用 list 获取所有订单的列表。
2. 使用 advancetestorder 将您的订单的状态预先设置为“pendingShipment”。
3. 使用 acknowledge 确认收到此订单。
4. （可选）使用 updatemerchantorderid 分配一个 Merchant Order ID。
5. 使用 shiplineitems 为您的订单创建一次发货操作，并将其状态更改为“已发货”。
6. 使用 updateshipment 将发货状态设置为“已送达”，从而完成整个工作流程。

在使用 Orders API 中详细介绍了这些步骤。

订单模板

Google 提供以下已创建的预填充订单模板，因此您不必输入所有详细信息。这些信息可以使用 createtestorder 方法中的模板参数进行调用：

• “template1”：两种商品/库存量单位，数量为 2 和 1，无促销活动
• “template1a”：两种商品/库存量单位，数量为 2 和 1，免费送货促销
• “template1b”：两种商品/库存量单位，数量为 2 和 1，特定商品促销
• “template2”：一种商品/库存量单位，数量为 2，无促销活动

正如您从模板中看到的那样，Orders API 支持发送包含多种商品/库存量单位和不同数量的订单。

您可以使用商家 ID 和要查看的模板名称来调用 gettestordertemplate，即可查看不同的模板数据。