在您使用 Orders API 之前,请确保按照 Orders API 使用入门中的步骤操作。
以下步骤总结了您为处理简单交易而执行的 Orders API 调用。下面我们详细介绍每个步骤:
这些示例使用 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[].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 参考文档中可以发现可供您选择的其他调用,并且在限制和限制条件中可以了解应该注意的所有现有问题。