Amazon Selling Partner API - spapi.cyou

列表项API v2020-09-01用例指南

亚马逊SPAPI

# 什么是listings items API?

使用Listings Items的销售伙伴API(Listings Items API)，您可以为销售伙伴创建、编辑和删除亚马逊的清单(SKU)，这包括产品事实，如项目标题，以及销售条款，如价格和库存.，请参阅Listings Items API Reference (opens new window)，了解有关Listings Items API操作和相关数据类型和模式的详细信息.

提交给Listings Items API的列表数据符合Selling Partner API for Product Type Definitions (opens new window).提供的JSON模式格式，关于检索支持的亚马逊产品类型的模式以及在使用Listings Items API提交给亚马逊之前验证数据的细节，请参见产品类型定义API文档.

主要特点

创建或完全更新上市项目Listings Items API接受PUT操作来创建一个新的列表或完全替换现有列表的数据.

部分更新列表Listings Items API接受PATCH'操作来更新现有列表的一个或多个单独属性，例如更新价格和数量.此外，Listings Items API接受PATCH'操作来删除现有列表的一个或多个单独属性.

删除列表Listings Items API接受`DELETE'操作，以删除一个现有的列表.

本地化的问题消息列表项目API提供本地化的问题信息，可以是调用应用程序指定的语言，也可以是亚马逊市场的默认语言.

提交验证Listings Items API在接受提交处理之前对提交数据进行验证.阻止进一步处理的验证错误会同步提供给调用的应用程序.

术语

清单亚马逊清单是一个销售伙伴在亚马逊上列出销售的商品，由库存单位(SKU).包含在亚马逊清单中的产品事实被调和到亚马逊目录商品中，由亚马逊标准识别号(ASINs).识别

全面更新对亚马逊清单的全面更新导致对提交的数据进行全面的数据要求验证，并创建一个新的清单或替换现有清单的数据.

部分更新对亚马逊列表的部分更新导致对所提供的属性进行部分数据要求的验证，并更新现有列表的一个或多个属性.

产品类型亚马逊产品类型是亚马逊目录中物品的分级分类.物品数据要求与物品的相关产品类型相联系.

考虑到的问题

1x1更新Listings Items API接受一次一个的列表更新. 对于更适合批量上传的使用-情况，JSON_LISTINGS_FEED馈送类型可与Selling Partner API for Feeds一起使用. JSON_LISTINGS_FEED是Listings Items API的批量等同物，提供与Selling Partner API提供的产品类型定义相同的功能和模式.

完全支持的产品类型Listings Items API还不完全支持所有的亚马逊产品类型.支持的亚马逊产品类型因销售伙伴类型(商家或供应商)和亚马逊市场的不同而不同.请参考销售伙伴API的产品类型定义，了解最新的可用亚马逊产品类型.

部分支持的产品类型对于列表项目API尚未完全支持的亚马逊产品类型，通过使用 "PRODUCT "产品类型，支持对现有ASIN的报价-仅提交和部分更新.

结果和问题来自Listings Items API的回应表明提交是否被接受处理，以及任何阻止提交被接受的问题.回应不包括接受提交处理后发生的问题.Listings Items API的未来版本和相关推送通知将提供接收这些接受后问题的能力.

# Tutorial: 创建或全面更新一个列表

使用本教程为特定的销售伙伴和亚马逊市场创建或全面更新亚马逊清单.

先决条件

要完成本教程，你需要

*来自您为之调用的销售伙伴的授权.更多信息请参见销售伙伴API开发者指南 (opens new window).

# 步骤1.提交列表项目投放请求

调用putListingsItem (opens new window)操作，使用列表项目API创建或完全更新一个列表.

请求参数

路径参数

Parameter Example Description Required
sellerId AXXXXXXXXXXXXX 一个销售伙伴的标识符，如商家账户或供应商代码.

类型: string

 是的
sku ABC123 标识符(库存保持单位)，是销售伙伴独有的列表项目.

类型：字符串

 是的

查询参数

Parameter Example Description Required
marketplaceIds ATVPDKIKX0DER Comma-delimited list of Amazon marketplace identifiers.

参见Selling Partner API Developer Guide中的Amazon marketplace identifiers.

Type< string > array(csv)

 是的
issueLocale en_US 问题本地化的Locale.

默认当没有提供locale时，使用第一个市场的默认locale.当指定的locale中没有本地化的信息时，本地化默认为en_US.

类型: string

 No

主体参数

Parameter Example Description Required
body 见请求实例 putListingsItem操作的请求体模式.

类型ListingsItemPutRequest

 是的

请求示例

PUT https://sellingpartnerapi-na.amazon.com/listings/2020-09-01/items/AXXXXXXXXXXXXX/ABC123
	? marketplaceIds=ATVPDKIKX0DER
	&amp;issueLocale=en_US
1
2
3
{
  "productType": "LUGGAGE",
  "要求": "LISTING",
  "属性": {
    "condition_type": [
      {
        "值": "new_new",
        "marketplace_id": "atvpdkikx0der"
      }
    ],
    "item_name": [
      {
        "价值": "AmazonBasics 16\" Underseat Spinner Carry-On",
        "language_tag": "en_US",
        "marketplace_id": "atvpdkikx0der"
      }
    ],
    ...
  }
}

响应

一个成功的响应包括以下内容

Name Example Description
sku ABC123 标识符(库存保持单位)，是销售伙伴独有的列表项目.

类型：字符串

status ACCEPTED 列表项目的提交状态.

Type: enum(Status)

submissionId f1dc291475dd11eabc550242ac130003 清单项目提交的独特标识符.

类型: string

issues See Example Response 与列表项目提交有关的问题.

Type < Issue> array

示例响应

{
  "sku": "ABC123",
  "status": "INVALID",
  "submissionId": "f1dc291475dd11eabc550242ac130003",
  "问题": [
    {
      "代码": "90220",
      "消息": "'product_description'是必需的，但没有提供."
      "严重程度": "ERROR"
      " attributeName": "product_description"
    
    ...
  ]
}

# Tutorial: 部分更新一个清单

使用本教程为一个给定的销售伙伴和亚马逊市场使用Listings Items API.部分更新一个亚马逊清单

部分更新是以JSON补丁文件的形式提交的.关于JSON补丁文件的更多细节，请参见https://tools.ietf.org/html/rfc6902 (opens new window)_对于亚马逊列表，JSON补丁文件可以添加、替换或删除整个属性.不支持在属性中修补内容.

先决条件

要完成这个教程，你需要

*来自你为之调用的销售伙伴的授权.更多信息请参见销售伙伴API开发者指南 (opens new window).

  • 在您的开发者档案中批准产品列表角色.

  • 在应用程序注册页面中为您的应用程序选择的产品列表角色.

  • 对于属性更新，基于JSON-的列表属性有效载荷，遵守Selling Partner API for Product Type Definitions (opens new window)提供的JSON Schema，用于指定的销售伙伴、亚马逊市场、亚马逊产品类型和属性.

  • 对于属性删除，基于JSON-的列表属性有效载荷，遵守Selling Partner API for Product Type Definitions (opens new window)为给定的销售伙伴、亚马逊市场、亚马逊产品类型和属性提供的JSON模式，并带有要删除的属性的选择器属性.属性不能仅通过名称删除，选择器值确定要删除的属性实例.

# 步骤1.提交listings项目补丁请求

调用patchListingsItem (opens new window)操作，使用Listings Items API部分地更新一个列表.

请求参数

路径参数

Parameter Example Description Required
sellerId AXXXXXXXXXXXXX 一个销售伙伴的标识符，如商家账户或供应商代码.

类型: string

 是的
sku ABC123 标识符(库存保持单位)，是销售伙伴独有的列表项目.

类型：字符串

 是的

查询参数

Parameter Example Description Required
marketplaceIds ATVPDKIKX0DER Comma-delimited list of Amazon marketplace identifiers.

参见Selling Partner API Developer Guide中的Amazon marketplace identifiers.

Type< string > array(csv)

 是的
issueLocale en_US 问题本地化的Locale.

默认当没有提供locale时，使用第一个市场的默认locale.当指定的locale中没有本地化的信息时，本地化默认为en_US.

类型: string

 No

主体参数

Parameter Example Description Required
body See Example Request patchListingsItem操作的请求体模式.

类型ListingsItemPatchRequest

 是的

示例请求

PATCH https://sellingpartnerapi-na.amazon.com/listings/2020-09-01/items/AXXXXXXXXXXXXX/ABC123
	.marketplaceIds=ATVPDKIKX0DER
	&amp;issueLocale=en_US
1
2
3
{
  "productType": "LUGGAGE",
  "补丁":[
    {
      "操作": "替换"
      "path":"/attributes/item_name",
      "值":[
        {
          "值": "AmazonBasics 16\" Underseat Spinner Carry-On"
          "language_tag": "en_US",
          "marketplace_id": "atvpdkikx0der"
        }
      ]
    },
    {
      "操作": "替换"
      "path":"/attributes/purchasable_offer",
      "值":[
        {
          "marketplace_id": "atvpdkikx0der",
          "货币": "USD",
          "our_price": [
            {
              "时间表": [
                {
                  "含税价值": 15.00
                }
              ]
            }
          ]
        }
      ]
    },
    {
      "操作": "删除"
      "路径":"/attributes/item_type_name"
      "值":[
        {
          "marketplace_id": "atvpdkikx0der",
          "language_tag": "en_US"
        }
      ]
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

响应

一个成功的响应包括以下内容

Name Example Description
sku ABC123 标识符(库存保持单位)，是销售伙伴独有的列表项目.

类型：字符串

status ACCEPTED 列表项目的提交状态.

Type: enum(Status)

submissionId f1dc291475dd11eabc550242ac130003 清单项目提交的独特标识符.

类型: string

issues See Example Response 与列表项目提交有关的问题.

Type < Issue> array

示例响应

{
  "sku": "ABC123",
  "status": "ACCEPTED",
  "submissionId": "f1dc291475dd11eabc550242ac130003",
  "问题": []
}
1
2
3
4
5
6

# Tutorial: 删除一个清单

使用本教程为指定的销售伙伴和亚马逊市场使用Listings Items API删除一个亚马逊清单.

先决条件

要完成本教程，你需要

*来自你为之调用的销售伙伴的授权.更多信息请参见销售伙伴API开发者指南 (opens new window)

  • 在您的开发者档案中批准产品列表角色.

  • 在应用程序注册页面中为您的应用程序选择的产品列表角色.

# 步骤1.提交列表项目删除请求

调用deleteListingsItem (opens new window)操作，用Listings Items API删除一个列表.

请求参数

路径参数

Parameter Example Description Required
sellerId AXXXXXXXXXXXXX 一个销售伙伴的标识符，如商家账户或供应商代码.

类型: string

 是的
sku ABC123 标识符(库存保持单位)，是销售伙伴独有的列表项目.

类型：字符串

 是的

查询参数

Parameter Example Description Required
marketplaceIds ATVPDKIKX0DER Comma-delimited list of Amazon marketplace identifiers.

参见Selling Partner API Developer Guide中的Amazon marketplace identifiers.

Type< string > array(csv)

 是的
issueLocale en_US 问题本地化的Locale.

默认当没有提供locale时，使用第一个市场的默认locale.当指定的locale中没有本地化的信息时，本地化默认为en_US.

类型: string

 No

示例请求

DELETE https://sellingpartnerapi-na.amazon.com/listings/2020-09-01/items/AXXXXXXXXXXXXX/ABC123
	.marketplaceIds=ATVPDKIKX0DER
	&amp;issueLocale=en_US
1
2
3

响应

一个成功的响应包括以下内容

Name Example Description
sku ABC123 标识符(库存保持单位)，是销售伙伴独有的列表项目.

类型：字符串

status ACCEPTED 列表项目的提交状态.

Type: enum(Status)

submissionId f1dc291475dd11eabc550242ac130003 清单项目提交的独特标识符.

类型: string

issues See Example Response 与列表项目提交有关的问题.

Type < Issue> array

示例响应

{
  "sku": "ABC123",
  "status": "ACCEPTED",
  "submissionId": "f1dc291475dd11eabc550242ac130003",
  "问题": []
}
1
2
3
4
5
6

# 提交图片和其他媒体属性

Listings Items API接受产品图片和其他媒体内容属性，这些图片和内容由亚马逊从公开访问的AWS S3或AWS CloudFront HTTP或HTTPS URLs.私有AWS S3内容也可以从S3 URLs(e.g. s3: //bucket-name/object-name.jpg). 为了让亚马逊从私有的AWS S3 URL下载，必须允许arn:aws:iam:.GetObject和ListBucket操作 368641386589: role/Media-Download-Role` AWS IAM角色在AWS S3桶上的操作. 请注意，私有的AWS S3内容被视为不可改变的，这意味着不支持改变AWS S3对象密钥的内容(i.e. 新的媒体内容需要一个新的AWS S3对象密钥). 这种惯例的好处是提高了处理时间，避免了在列表提交被重新-处理时的冗余下载成本.

下面是一个AWS S3桶策略的例子，在一个名为bucket-name的桶上启用所需的操作

{
    "版本": "2012-10-17",
    "声明": [
        {
            "Sid": "",
            "行动": [
                "s3:GetObject",
                "s3:ListBucket"
            ],
            "效果": "允许"
            "资源": [
                "arn:aws:s3::bucket-name/*"
                "arn:aws:s3::bucket-name"
            ],
            "校长"{
                "AWS": [
                    "arn:aws:iam::368641386589:role/Media-Download-Role"
                ]
            }
        }
    ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

Listings Items API v2021-08-01