使用 Orders API

在您使用 Orders API 之前,请确保按照 Orders API 使用入门中的步骤操作。

以下步骤总结了您为处理简单交易而执行的 Orders API 调用。下面我们详细介绍每个步骤:

  1. 创建您的首个订单
  2. 转换您的订单状态pendingShipment
  3. 列出您帐号中的订单
  4. 确认您已收到订单。
  5. 给订单分配商家订单 ID
  6. 创建新运单
  7. 更新订单状态delivered

这些示例使用 base_url 参考 https://www.googleapis.com。此外,通过在网址中指定 /v2sandbox,所有示例都使用沙盒模式。在生产环境中,您应该用 /v2 替换上述网址中的内容。

创建您的首个订单

确保您可以通过 API 验证自己的 Merchant Center 帐号后,即可在沙盒模式下使用 createtestorder 调用创建您的首个订单。

调用如下所述的网址端点,然后使用 templateName 参数指定预设订单,您可以借助此订单开始使用 API。订单模板中介绍了可用的模板。

POST base_url/content/v2sandbox/merchant_ID/testorders
{
  "templateName": "template1"
}

成功调用后,Google 返回一则响应,其中包含刚创建的帐号的 orderId,如以下示例所示:

{
  "kind": "content#ordersCreateTestOrderResponse",
  "orderId": "G-PLA-7877-86-2240"
}

(仅限沙盒)转换您的订单

订单通常会自动从 inProgress 起始状态转移到 pendingShipment。但是,在沙盒模式下,状态转换由您控制,因为订单不会自行转到 pendingShipment。要将订单状态更改为 pendingShipment,请使用以下语法调用 advancetestorder

POST base_url/content/v2sandbox/merchant_ID/testorders/order_ID/advance

在请求正文中,将 orderId 设置为您创建的订单的 ID。例如:

POST base_url/content/v2sandbox/merchant_ID/testorders/G-PLA-7877-86-2240/advance
{
  "orderId": "G-PLA-7877-86-2240"
}

在生产环境模式下,订单的状态为 pendingShipment 后,您可以确信此订单已得到确认,并且可以开始配送。

要确认状态已更新,请使用 get

GET base_url/content/v2sandbox/merchant_ID/orders/G-PLA-7877-86-2240

在将订单转到 pendingShipment 后,您可以继续进行下一处理阶段了。

列出并确认订单

本部分着重介绍成功使用 Orders API 过程中涉及的某些预处理步骤。

列出您帐号中的订单

尽管您知道刚创建的订单的 ID,但是,在实践中,这些订单将来自于刚点击购买的客户,因此您目前还没有订单 ID。

要处理这种情况,请使用 list 查找要处理的新订单:

GET base_url/content/v2sandbox/merchant_ID/orders/

这一简单调用会列出 Merchant Center 帐号中的所有订单。您知道自己的帐号中有订单后,就可以对其进行操作,以便更轻松地使用此订单。我们建议您执行轮询的频率为大约每 10 分钟一次。

确认您收到的订单

处理新订单到货情况时,请将其标记为已确认。您可以使用 acknowledge 来执行此操作,如以下示例所示:

POST base_url/content/v2sandbox/merchant_ID/orders/G-PLA-7877-86-2240/acknowledge
{
  "operationId": "operation-1"
}

acknowledge 调用采用一个参数 operationId。此参数是一个将在 API 中频繁显示的字段,在同一订单的操作中应该是唯一的。operationId 字段允许重试请求,并在发生诸如超时等错误时防止重复操作的意外情况。

请注意,您可以将 acknowledged=false 添加到 list 调用中,然后此调用仅列出尚未确认的订单。这使得处理新订单变得更轻松。例如:

GET base_url/content/v2sandbox/merchant_ID/orders/?acknowledged=false

分配商家订单 ID

确认订单后,您可以使用 updatemerchantorderid 为其分配商家订单 ID。您分配的值在 Merchant Center 帐号中应该是唯一的,但除此之外没有任何约束。

我们强烈建议您使用自己的订单管理系统所使用的实际订单 ID,以便两个系统共享一个唯一的密钥,这对于所需的任何对帐都可能派上用场。

POST base_url/content/v2sandbox/merchant_ID/orders/G-PLA-7877-86-2240/updateMerchantOrderId
{
  "operationId": "operation-2",
  "merchantOrderId": "unique_value_within_mc_account"
}

分配商家订单 ID 后,您可以使用 getbymerchantorderid 查询特定订单。

是时候打包了!配送您的订单

在您准备好配送您的订单后,就可以使用 shiplineitems 创建新的运单。

在调用 shiplineitems 创建运单时,您必须在请求正文中包含以下内容:

  • shipmentId:将该值设置为运单的 ID。

  • operationId:在您确认收到订单时创建该值。

  • lineItems[].lineItemId:从 getlist 调用的响应中的订单资源中获取该值。

  • lineItems[].quantity:您必须至少配送 1 件商品。

当 Google 创建一个订单的运单时,它将订单的状态设置为 shipped(如果原始订单中的所有商品都已配送)或 partiallyShipped(如果原始订单中的某些商品尚未配送)。

以下实例显示了示例 shiplineitems 调用:

POST base_url/content/v2sandbox/merchant_ID/orders/G-PLA-7877-86-2240/shipLineItems
{
  "operationId": "operation-3",
  "shipmentId": "shipment-1",
  "lineItems": [
    {
      "lineItemId": "CYBIDQWXDKCZEYE",
      "quantity": 1
    }
  ],
  "carrier": "FedEx",
  "trackingId": "ASDFGHJKL12347890"
}

更新订单状态

运单到达后,您可以使用 updateshipment 将运单的状态更新为 delivered

请确保匹配您在使用 shiplineitems 创建运单时设置的 shipmentId。配送此订单后,您可以在 get 调用所做的响应中找到该值。

以下示例显示了 updateshipment 调用:

POST base_url/content/v2sandbox/merchant_ID/orders/G-PLA-7877-86-2240/updateShipment
{
  "operationId": "operation-4",
  "shipmentId": "shipment-1",
  "status": "delivered"
}

在此阶段,订单已经完成!您已通过 Orders API 成功履行您的首个订单。在 API 参考文档中可以发现可供您选择的其他调用,并且在限制和限制条件中可以了解应该注意的所有现有问题。