Easy Ship API v2022-03-23 用例指南
如何使用 Easy Ship API。
API 版本:v2022-03-23
什么是 Easy Ship API?
您可以使用适用于 Easy Ship 的卖家合作伙伴 API 来构建应用程序,供卖家管理和配送亚马逊 Easy Ship 订单的包裹。
主要功能
- 获取可用时段。
- 为 Easy Ship 订单安排和重新安排 Easy Ship 包裹。
- 打印货件标签、发票和保修文件。
教程:安排 Easy Ship 包裹
了解如何使用 Easy Ship API 为 Easy Ship 订单安排包裹。
步骤 1. 获取可用时段
调用 listHandoverSlots
操作以获取尚未安排的 Easy Ship 订单的可用时段列表。请确保以下几点:
- 指定的亚马逊订单编号应为 Easy Ship 订单且处于未配送状态。
- 请求中应包括所需的包裹重量和尺寸。
非 Easy Ship 订单和处于“待处理”状态的订单将返回错误响应。
请求
调用 listHandoverSlots
操作。
请求示例:
POST https://sellingpartnerapi-eu.amazon.com/easyShip/2022-03-23/timeSlot
{
"amazonOrderId": "933-1443575-9112638",
"marketplaceId": "A21TJRUUN4KGV",
"packageDimensions": {
"length": 20.0,
"width": 10.0,
"height": 12.0,
"unit": "Cm",
"identifier": "test"
},
"packageWeight": {
"value": 100.0,
"unit": "G"
}
}
响应
成功的响应包括可用时段列表。每个时段都将指定卖家将包裹交给亚马逊承运人需要采用的方式。有关详细信息,请参阅支持的移交方法。请确保为下一步保存所需时段的 slotId
、startTime
和 endTime
。
响应示例:
{
"amazonOrderId": "933-1443575-9112638",
"timeSlots": [
{
"handoverMethod": "Pickup",
"slotId": "AQc48yxSAAAAADZG0qQAAAAA6kkAAAAAAAA=",
"startTime": "2022-03-09T23:30:00Z",
"endTime": "2022-03-10T02:00:00Z"
},
{
"handoverMethod": "Pickup",
"slotId": "AQef4K2CAAAAAGdIAEAAAAAA6kkAAAAAAAA=",
"startTime": "2022-03-10T02:00:00Z",
"endTime": "2022-03-10T04:30:00Z"
}
]
}
步骤 2. 创建 Easy Ship 包裹
调用 createScheduledPackage
操作为尚未安排的 Easy Ship 订单创建包裹。请确保以下几点:
- 指定的亚马逊订单编号应为 Easy Ship 订单且处于未配送状态。
- 请求中应包括所需的包裹重量和尺寸。
非 Easy Ship 订单和处于“待处理”状态的订单将返回错误响应。
请求
调用 createScheduledPackage
操作。
请求示例:
POST https://sellingpartnerapi-eu.amazon.com/easyShip/2022-03-23/package
{
"amazonOrderId": "933-1443575-9112638",
"marketplaceId": "A21TJRUUN4KGV",
"packageDetails": {
"packageTimeSlot": {
"slotId": "AQc48yxSAAAAADZG0qQAAAAA6kkAAAAAAAA=",
"startTime": "2022-03-09T23:30:00Z",
"endTime": "2022-03-10T02:00:00Z"
}
}
}
响应
成功的响应包括包裹的重量和尺寸、发票详情(如果有)、所选时段以及包裹的状态。
响应示例:
{
"packageDimensions": {
"identifier": "test",
"unit": "Cm",
"length": 20,
"width": 10,
"height": 12
},
"packageWeight": {
"unit": "G",
"value": 50
},
"invoice": {
"invoiceNumber": "IN-456",
"invoiceDate": "1.636404098172E9"
},
"scheduledPackageId": {
"amazonOrderId": "933-1443575-9112638",
"packageId": "b4be5116-98b1-6f20-a47b-03de178cfb4f"
},
"packageStatus": "ReadyForPickup",
"packageTimeSlot": {
"slotId": "AQc48yxSAAAAADZG0qQAAAAA6kkAAAAAAAA=",
"startTime": "2022-03-09T23:30:00Z",
"endTime": "2022-03-10T02:00:00Z"
},
"trackingDetails": {
"trackingId": "2045079155"
}
}
教程:重新安排 Easy Ship 包裹
了解如何使用 Easy Ship API 为 Easy Ship 订单重新安排包裹。要使用 listHandoverSlots
和 updateScheduledPackages
操作,包含指定内容的亚马逊订单 orderId
必须预定,Easy Ship 包裹的状态必须有效。请参阅 教程:查看 Easy Ship 包裹的状态 了解更多详情。
提示
只有卖家才能更新 Easy Ship 包裹的选定时段。
步骤 1. 获取可重新安排的时段
调用 listHandoverSlots
操作以获取已安排 Easy Ship 订单的可用时段列表。
请求
调用 listHandoverSlots
操作。
请求示例:
POST https://sellingpartnerapi-eu.amazon.com/easyShip/2022-03-23/timeSlot
{
"amazonOrderId": "933-1443575-9112638",
"marketplaceId": "A21TJRUUN4KGV",
"packageDimensions": {
"length": 20.0,
"width": 10.0,
"height": 12.0,
"unit": "Cm",
"identifier": "test"
},
"packageWeight": {
"value": 100.0,
"unit": "G"
}
}
响应
成功的响应包括可用时段列表。请确保为下一步保存所需时段的 slotId
、startTime
和 endTime
。
响应示例:
{
"amazonOrderId": "933-1443575-9112638",
"timeSlots": [
{
"handoverMethod": "Pickup",
"slotId": "AQc48yxSAAAAADZG0qQAAAAA6kkAAAAAAAA=",
"startTime": "2022-03-09T23:30:00Z",
"endTime": "2022-03-10T02:00:00Z"
},
{
"handoverMethod": "Pickup",
"slotId": "AQef4K2CAAAAAGdIAEAAAAAA6kkAAAAAAAA=",
"startTime": "2022-03-10T02:00:00Z",
"endTime": "2022-03-10T04:30:00Z"
}
]
}
步骤 2. 更新 Easy Ship 包裹
调用 updateScheduledPackages
操作以更新 Easy Ship 包裹的时段。
请求
调用 updateScheduledPackages
操作。
请求示例:
PATCH https://sellingpartnerapi-eu.amazon.com/easyShip/2022-03-23/package
{
"marketplaceId":"A21TJRUUN4KGV",
"updatePackageDetailsList":[
{
"scheduledPackageId":{
"amazonOrderId":"933-1443575-9112638",
"packageId":"b4be5116-98b1-6f20-a47b-03de178cfb4f"
},
"packageTimeSlot":{
"slotId": "AQef4K2CAAAAAGdIAEAAAAAA6kkAAAAAAAA=",
"startTime": "2022-03-10T02:00:00Z",
"endTime": "2022-03-10T04:30:00Z"
}
}
]
}
响应
成功的响应包括包裹详情和更新的时段。
响应示例:
{
"packages": [
{
"packageDimensions": {
"identifier": "test",
"unit": "Cm",
"length": 20,
"width": 10,
"height": 12
},
"packageWeight": {
"unit": "G",
"value": 50
},
"invoice": {
"invoiceNumber": "IN-456",
"invoiceDate": "1.636404098172E9"
},
"scheduledPackageId": {
"amazonOrderId": "933-1443575-9112638",
"packageId": "b4be5116-98b1-6f20-a47b-03de178cfb4f"
},
"packageStatus": "ReadyForPickup",
"packageTimeSlot": {
"slotId": "AQef4K2CAAAAAGdIAEAAAAAA6kkAAAAAAAA=",
"startTime": "2022-03-10T02:00:00Z",
"endTime": "2022-03-10T04:30:00Z"
},
"trackingDetails": {
"trackingId": "2045079155"
}
}
]
}
教程:查看 Easy Ship 包裹的状态
了解如何使用 Easy Ship API 查看 Easy Ship 包裹的状态。此操作允许卖家查看 Easy Ship 包裹的指定重量、尺寸、时段和其他详细信息。
包裹的状态会随着包裹发生的事件而更新。这些事件包括
- 包裹提供给亚马逊承运人。
- 包裹已配送给买家。
- 包裹已取消。
- 包裹在运输途中丢失。
在重新安排之前检查包裹的当前状态非常有用,因为包裹在移交给亚马逊承运人后无法重新安排。如果尝试对处于无效状态的 Easy Ship 包裹进行重新安排操作,该操作将失败并显示 InvalidOrderState
代码。有关包裹的所有不同状态,请参阅 packageStatus
。
步骤 1. 获取 Easy Ship 包裹
调用 getScheduledPackage
操作以获取 Easy Ship 包裹的详细信息。
请求
调用 getScheduledPackage
操作。
请求示例:
GET https://sellingpartnerapi-eu.amazon.com/easyShip/2022-03-23/package?marketplaceId=A21TJRUUN4KGV&amazonOrderId=933-6451079-5067861
响应
成功的响应包括包裹详情。
响应示例:
{
"packageDimensions":{
"unit":"Cm",
"length":20,
"width":10,
"height":12
},
"packageWeight":{
"unit":"G",
"value":50
},
"invoice":{
"invoiceNumber":"IN-442"
},
"scheduledPackageId":{
"amazonOrderId":"933-6451079-5067861",
"packageId":"88be1771-923c-d581-5e29-e8a310916185"
},
"packageStatus":"ReadyForPickup",
"packageTimeSlot":{
"slotId": "AQef4K2CAAAAAGdIAEAAAAAA6kkAAAAAAAA=",
"startTime": "2022-03-10T02:00:00Z",
"endTime": "2022-03-10T04:30:00Z"
},
"trackingDetails": {
"trackingId": "2045079155"
}
}
教程:处理需要序列号的订单商品
亚马逊 Easy Ship 订单中的某些商品需要序列号,以便亚马逊可以为其生成保修文件。了解如何使用 Easy Ship API 来了解哪些物品需要序列号。
步骤 1. 获取需要序列号的订单列表
调用 getOrderItems
操作,指定要安排包裹的订单的亚马逊订单编号。
亚马逊按顺序返回商品,在需要序列号的商品上标记 SerialNumberRequired
=true
。
步骤 2. 使用序列号安排 Easy Ship 包裹
使用 PackageItems
调用 createScheduledPackage
操作,为步骤 1 中标记了 SerialNumberRequired
=true
的所有商品指定序列号。不要为标记了 SerialNumberRequired
=false
的商品指定序列号。
亚马逊会为您指定序列号的商品生成保修文件。有关获取亚马逊在您安排包裹时生成的文档的信息,请参阅 如何获取发票、货件标签和保修文件。
教程:获取发货标签、发票和保修文件
当买家在印度下亚马逊n Easy Ship 订单时,亚马逊会生成发票。当您调用 CreateScheduledPackage
操作为订单安排亚马逊 Easy Ship 时段时,亚马逊会生成货件标签。如果您在调用 CreateScheduledPackage
时包括您指定的商品的序列号,亚马逊还会为这些商品生成保修文件。本主题介绍如何获取已安排的亚马逊 Easy Ship 订单的发票、货件标签和保修。
步骤 1. 提交 Easy Ship 上传数据请求
提交上传数据请求,索取所需的 Easy Ship 订单的文件。成功处理上传数据请求后,您可以下载处理报告以获取报告参考编号。然后可以在下一步中使用它来下载请求的 Easy Ship 文档。
-
按照教程:提交上传数据提交 Easy Ship 上传数据。本教程介绍了从提交上传数据文档到验证上传数据请求已成功完成的所有步骤。
FeedContent.
使用EasyshipDocuments.xsd
构成 Feed 文档的内容。FeedType.
调用createFeed
操作时指定POST_EASYSHIP_DOCUMENTS
。ReportReferenceId.
如果上传数据处理报告中没有错误,则返回的值可以在下一步中使用。
Easy Ship 上传数据文档示例:
<AmazonEnvelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="amzn-envelope.xsd"> <Header> <DocumentVersion>1.01</DocumentVersion> <MerchantIdentifier>ABCDEFG007V</MerchantIdentifier> </Header> <MessageType>EasyShipDocument</MessageType> <Message> <MessageID>1</MessageID> <EasyShipDocument> <AmazonOrderID>933-6451079-5067861</AmazonOrderID> <DocumentType>ShippingLabel</DocumentType> <DocumentType>Invoice</DocumentType> <DocumentType>Warranty</DocumentType> </EasyShipDocument> </Message> </AmazonEnvelope>Easy Ship 上传数据处理报告示例:
<EasyShipProcessingReport> <FeedSubmissionID>98765432100</FeedSubmissionID> <MessagesProcessed>1</MessagesProcessed> <MessagesSuccessful>1</MessagesSuccessful> <MessagesWithError>0</MessagesWithError> <DocumentReportReferenceID>123456789000</DocumentReportReferenceID> </EasyShipProcessingReport>
步骤 2. 获取 PDF
获取包含亚马逊 Easy Ship 订单的发票、货件标签和保修文件(如果有)的 PDF。
-
调用
getReport
操作。指定reportId
参数时,使用步骤 1. 提交 Easy Ship 上传数据请求中的ReportReferenceId
值。该操作会返回一个
reportDocumentId
值,您可以在下一步中将该值传递给getReportDocument
操作。 -
调用
getReportDocument
操作,指定上一步中的reportDocumentId
。有关详细信息,请参阅检索报告。
市场支持
Easy Ship 操作仅在部分商城可用,每个商城对特定操作的支持各不相同。有关商城支持的操作,请参阅下表。
商城 | 区域 | Supported handover methods | Get time slots | Create package | Update package | Get package status | Shipping label | 发票 | 保修 | Bulk Package Scheduling |
---|---|---|---|---|---|---|---|---|---|---|
墨西哥 | NA | Pickup and Dropoff | 仅限计划外订单 | 支持的 | 不支持 | 支持的 | 支持的 | 不支持 | 不支持 | 不支持 |
印度 | EU | Pickup 或者全部 | 计划内和计划外订单 | 支持的 | 支持的 | 支持的 | 支持的 | 支持的 | 支持的 | 不支持 |
土耳其 | EU | Pickup and Dropoff | 仅限计划外订单 | 支持的 | 不支持 | 支持的 | 支持的 | 不支持 | 不支持 | 不支持 |
澳大利亚 | FE | Pickup 或者全部 | 仅限计划外订单 | 支持的 | 不支持 | 支持的 | 支持的 | 不支持 | 不支持 | 不支持 |
新加坡 | FE | Pickup 或者全部 | 仅限计划外订单 | 支持的 | 不支持 | 支持的 | 支持的 | 不支持 | 不支持 | 不支持 |
日本 | FE | Pickup 或者全部 | 仅限计划外订单 | 支持的 | 不支持 | 支持的 | 支持的 | 不支持 | 不支持 | 不支持 |
荷兰 | EU | Dropoff 或者全部 | 不支持 | 不支持 | 不支持 | 不支持 | 不支持 | 不支持 | 不支持 | 支持的 |
波兰 | EU | Pickup 或者全部 | 不支持 | 不支持 | 不支持 | 不支持 | 不支持 | 不支持 | 不支持 | 支持的 |
Updated 3 months ago