供应商直接配送动态沙箱指南
Use the Selling Partner API dynamic sandbox to test vendor direct fulfillment operations.
概述
销售伙伴 API 的动态沙箱环境允许您在不影响生产数据或触发真实事件的情况下测试应用程序。动态沙箱将请求路由到沙箱后端,后端可以根据请求参数返回真实的响应。通过向沙箱端点而非生产端点发送请求,您可以在不影响生产数据的情况下测试标准工作流程。
This guide introduces the available dynamic sandbox operations for the Vendor Direct Fulfillment APIs. For more information about the Selling Partner API sandbox environments, refer to Selling Partner API sandbox.
供应商直接配送 API 中的动态沙箱支持
The following Vendor Direct Fulfillment API sections support the dynamic sandbox:
-
供应商直接配送订单 API 2021-12-28 版本支持所有等效的 V1 生产操作。
注意
Production calls for Vendor Direct Fulfillment Orders API include additional response parameters beyond
scenarioId
andorderId
sandbox parameters. You must update your request to specify these additional parameters prior to making production calls. -
供应商直接配送发货 API 2021-12-28 版本支持所有等效的 V1 生产操作。
静态响应
The dynamic sandbox backend service does not yet return dynamic responses for all Vendor Direct Fulfillment Shipping operations. The service returns static responses for the
submitShipmentStatusUpdates
,getCustomerInvoices
,getCustomerInvoice
,getPackageSlips
, andgetPackageSlip
operations. Any successful call to one of these operations always returns the same static response for that operation. -
供应商直接配送交易 API 2021-12-28 版本支持所有等效的 V1 生产操作。
使用供应商直接配送沙箱数据 API 2021-10-28 版本生成虚构的订单,以便在使用这些 API 进行测试时使用。
使用支持的直接配送 API 进行测试
Follow these high-level steps to test using the supported Direct Fulfillment APIs:
-
生成用于测试的虚构订单。您生成的订单旨在适应场景下描述的特定业务测试场景。
-
Use the generated orders to perform business test scenarios with the supported Vendor Direct Fulfillment APIs and operations.
重要说明
You must direct your sandbox requests to the Selling Partner API sandbox endpoints. If you are using a SP-API sandbox environment to test a call that requires a Restricted Data Token (RDT), you must get the RDT from the production environment and pass it to your sandbox call. For more information about restricted operations for which you need an RDT, refer to the Token API Use case guide.
场景
出于测试目的,生成的订单支持以下业务场景。这些是测试订单支持的唯一用例,主要侧重于为配送生成标签。除非另有说明,否则标签场景会返回固定、标准化、虚构的标签。
- LIFECYCLE: Use these test orders to simulate order lifecycle testing. The response to an operation that employs these orders can vary. For example, a ship label request made for a multi-box order results in a multiple label response. Similarly, a ship label request made with a package dimension change can result in a ship method change in the response.
- LABEL_CASE-SHIP_METHOD_UNASSIGNABLE: Use these test orders to simulate a ship method unassignable error, which occurs when Amazon is not able to assign a ship method for an order.
- LABEL_CASE-INCONSISTENT_METHODS: Use these test orders to simulate an "inconsistent ship method" error, which occurs when Amazon is not able to assign the same ship method to all of the boxes for a multi-box or multi-package order.
- LABEL_CASE-CARRIER_INTERNAL_FAILURE: Use these test orders to simulate a "carrier internal failure" error, which occurs when the carrier throws an error during label generation.
- LABEL_CASE-SYS_INTERNAL_FAILURE: Use these test orders to simulate a "system internal failure" error, which occurs when an unexpected failure happens in Amazon's systems.
- LABEL_CASE-DEST_ADDRESS_WRONG: Use these test orders to simulate a "destination address is wrong" error, which happens when a customer address falls outside of a carrier's service area.
- LABEL_CASE-SERVICE_NOT_AVAILABLE: Use these test cases to simulate a "service not available" error, which occurs when the selected carrier service is not available or applicable.
- SHIP_CONFIRM_CASE-SHIP_METHOD_UNASSIGNABLE: Use these test orders to simulate a ship method unassignable error, which occurs when Amazon is not able to assign a ship method for an order. This applies to vendor own label shipments.
- SHIP_CONFIRM_CASE-SYS_INTERNAL_FAILURE: Use these test orders to simulate a "system internal failure" error, which occurs when an unexpected failure happens in Amazon's systems.
测试订单 ASIN
生成的虚构订单使用一组测试 ASIN(亚马逊标准识别码)和相关包裹特征,如下表所示。
包裹类型 | ASIN | 包裹特性 |
---|---|---|
小包裹 | TESTASIN001 | 包裹尺寸(高 x 宽 x 长):1 英寸 x 1 英寸 x 2 英寸 重量:1 磅 |
小包裹 | TESTASIN004 | 包裹尺寸(高 x 宽 x 长):5 英寸 x 2 英寸 x 8 英寸 重量:3 磅 |
重型 | TESTASIN002 | 包裹尺寸(高 x 宽 x 长):50 英寸 x 50 英寸 x 30 英寸 重量:100 磅 |
多件套 | TESTASIN003 | 包裹 1 尺寸(高 x 宽 x 长):36 英寸 x 37 英寸 x 24 英寸 重量:7 磅 包裹 2 尺寸(高 x 宽 x 长):10 英寸 x 30 英寸 x 40 英寸 重量:3 磅 |
Tutorial - Generate fictional orders for testing
Use this tutorial to generate test orders for the preceding scenarios to test the Vendor Direct Fulfillment APIs.
Follow these steps to generate test orders and related label scenarios:
-
调用
generateOrderScenarios
操作,指定所需的对应方标识符。亚马逊会收到测试数据请求。如果操作成功,则响应将包含
transactionId
值。收到成功响应后,请等待大约 30-40 分钟后再继续。 -
Periodically call the
getOrderScenarios
operation, passing thetransactionId
value from the previous step, until you receive a successful response and thestatus
value in the response indicates that processing has ended. Processing ends when the status equalsSUCCESS
orFAILURE
. At this point the response includes either the test orders if the status isSUCCESS
, or an error array with details about the errors if the status isFAILURE
.
先决条件
为了完成本教程,您需要:
- 来自您正在为其进行调用的销售伙伴的授权。
- Approval for the Direct-to-Consumer Shipping role in your developer profile.
- The Direct-to-Consumer Shipping role selected in the App registration page for your application.
Step 1: Request fictional test orders
通过提供所需的对应方标识符来申请测试订单。若要申请生成测试订单,请调用 generateOrderScenarios
操作,并传递以下参数:
请求参数
请求正文
参数 | 描述 | 必填项 |
---|---|---|
orders |
由对应方标识符表示的一系列测试订单。 类型:< 订单场景请求 > 数组 |
有帮助 |
请求示例
POST http://sandbox.sellingpartnerapi-na.amazon.com//vendor/directFulfillment/
sandbox/2021-10-28/orders
{
"orders": [
{
"sellingParty": {
"partyId": "NIQQM"
},
"shipFromParty": {
"partyId": "CWPQ"
}
}
]
}
响应
成功的响应包括以下内容:
参数 | 描述 | 必填项 |
---|---|---|
transactionId |
亚马逊分配的用于识别此交易的指南。 类型:字符串 |
有帮助 |
响应示例
{
"transactionId": "0343fcb3-fd7e-455e-968f-fb4ff7dd4081-20211014222021"
}
收到带有交易编号的成功响应后,请等待大约 30-40 分钟,然后再继续执行步骤 2。
Step 2: Return the status and the requested fictional orders if ready
To retrieve the status of the generateOrderScenarios
transaction, and the requested test order data if available, call the getOrderScenarios
operation and pass the required transactionId
parameter. You must call this operation periodically until you receive either a successful response that contains the generated test orders, or a failure response that contains an error array with details about the errors.
After you receive the test orders, use them to perform dynamic ship label testing with the supported Vendor Direct Fulfillment APIs and operations.
请求参数
路径参数
参数 | 描述 | 必填项 |
---|---|---|
transactionId |
对生成订单场景 (generateOrderScenarios) 操作的响应中返回的交易标识符。 | 有帮助 |
请求示例
GET http://sandbox.sellingpartnerapi-na.amazon.com/vendor/directFulfillment/
sandbox/2021-10-28/transactions/0343fcb3-fd7e-455e-968f-fb4ff7dd4081-20211014222021
响应
成功的响应包括以下内容:
参数 | 描述 | 必填项 |
---|---|---|
transactionStatus |
包括状态在内的交易详情。如果交易成功,则还会包括请求的测试订单数据。 类型:交易 |
有帮助 |
响应示例
成功(HTTP 状态码 200)- 响应包含生成的场景测试数据和订单号
{
"transactionStatus":
{
"transactionId": "ff35f39e-e69f-499e-903e-6c4f6c32609f-20210827003315",
"status": "Success",
"testCaseData":
{
"scenarios": [
{
"scenarioId": "LIFECYCLE",
"orders": [
{
"orderId": "T1111N"
},
{
"orderId": "T1111P"
}
]
},
{
"scenarioId": "LABEL_CASE-SHIP_METHOD_UNASSIGNABLE",
"orders": [
{
"orderId": "T5555N"
},
{
"orderId": "T5555P"
}
]
},
{
"scenarioId": "LABEL_CASE-INCONSISTENT_METHODS",
"orders": [
{
"orderId": "T2222N"
},
{
"orderId": "T2222P"
}
]
},
{
"scenarioId": "LABEL_CASE-CARRIER_INTERNAL_FAILURE",
"orders": [
{
"orderId": "T3333N"
},
{
"orderId": "T3333P"
}
]
},
{
"scenarioId": "LABEL_CASE-SYS_INTERNAL_FAILURE",
"orders": [
{
"orderId": "T4444N"
},
{
"orderId": "T4444P"
}
]
},
{
"scenarioId": "SHIP_CONFIRM_CASE-SHIP_METHOD_UNASSIGNABLE",
"orders": [
{
"orderId": "buw38"
}
]
},
{
"scenarioId": "SHIP_CONFIRM_CASE-SYS_INTERNAL_FAILURE",
"orders": [
{
"orderId": "qqw52"
}
]
},
{
"scenarioId": "LABEL_CASE-DEST_ADDRESS_WRONG",
"orders": [
{
"orderId": "T6666N"
},
{
"orderId": "T6666P"
}
]
},
{
"scenarioId": "LABEL_CASE-SERVICE_NOT_AVAILABLE",
"orders": [
{
"orderId": "T7777N"
},
{
"orderId": "T7777P"
}
]
}
]
}
}
}
响应示例
处理中(HTTP 状态码 404)- 请求正在处理中,测试数据的生成尚未完成。
{
"errors": [
{
"code": "ResourceNotFound",
"message": "Cannot find resource by the given URI"
}
]
}
响应示例
Failure (HTTP status code 200) - The test data failed to generate. Refer to the errors array for more information.
{
"transactionStatus":
{
"transactionId": "ee8363d3-d061-4b17-b218-d3c80e014c2f-20220105231359",
"status": "FAILED",
"testCaseData":
{
"scenarios": [
{
"scenarioId": "",
"orders": []
}
]
},
"errors": [
{
"code": "INVALID_WAREHOUSE_CODE",
"details": "Invalid Warehouse Code. Retry request with correct Warehouse code"
}
]
}
}
Updated 20 days ago