深度探索亚马逊刊登 Listing Api(一)

背景

亚马逊的刊登可以用excel、xml和json三种数据格式，很多卖家和开发者在之前几乎使用excel操作刊登，一份文件可以通过后台或者Feed API POST_FLAT_FILE_LISTINGS_DATA操作刊登，安静美好的岁月在2024.04(文末通告链接)被官方打破，一文政策通告开发者将在一年后停止使用这种方式操作，开发者需切换到以json格式的刊登，json格式的好处无需多说，缺点吗！嗯~~~感谢亚马逊赏饭吃(kpi)。但是要重新打造实现这个整个刊登流程，一众自研卖家和ERP不脱层皮也得掉一大把头发。亚马逊刊登是我见过最复杂的了！

在开始之前，默认你已经了解亚马逊的刊登excel、xml和json三种数据格式，如果你还对Listing Api的刊登和后台excel模板刊登有和差异还有问题的地方，请移步此文了解：

苏坡面：亚马逊(Listing)刊登-笔记梳理4 赞同 · 4 评论文章

本系列文章跟着亚马逊的政策使用json方式刊登

Listing详情

出单第一步，Listing商品详情页是关键。Listing 由分类节点、搜索关键词、图片、标题、商品要点、商品描述、A+/高级 A+、品牌名称等8个基本要素及其他要素组成，一个高质量的Listing能为出单提示销量。

Listing 的8大基本要素

完成一个上架的Asin页面主要有以上模块信息，主要涉及业务场景有：上架，下架，修改，拆分，合并

Listing API概览

定义和功能

官网链接：Listings Items API v2021-08-01 reference (amazon.com )

官方提供了四个接口操作：

getListingsItem(获取SKU)
putListingsItem(创建SKU)
deleteListingsItem(删除SKU)
patchListingsItem(修改SKU)

我们重点关注的是putListingsItem接口，json怎么传才是关键。

数据结构

我们以putListingsItem body官方例子解释说明

{
  //选择的类目
  "productType": "LUGGAGE",
  "requirements": "LISTING",
  //以下是商品信息的属性结构，可以看到有两种情况的属性，一种是带 "language_tag": "en_US",一种又是不带的。
  "attributes": {
    "condition_type": [
      {
        "value": "new_new",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    "item_name": [
      {
        "value": "AmazonBasics 16\" Underseat Spinner Carry-On",
        "language_tag": "en_US",
        "marketplace_id": "ATVPDKIKX0DER"
      }
    ],
    ...
  }
}

这类目怎么来？属性有多少？还有哪些是必填的？哪些属性带 "language_tag": "en_US"？哪些不带？看得我眼花缭乱的！！！

晕死了

不好意思，晕死是这个类目JsonSchema

jsonSchema

实践Listing API

流程梳理

如果我们需要正常的完成一个商品信息提交，前发现置的工作越来越多，事情好像越来越复杂了

官方给刊登流程

前置数据

1.类目结构信息：通过Report API的GET_XML_BROWSE_TREE_DATA

2.获取类目Schema：通过Product Type Definitions的get Definitions Product Type获取

亚马逊刊登 Listing API

通过这个schema Url获取到类目的jsonSchema。通过这个类目jsonSchema就能知道属性有多少，有哪些是必填的，哪些属性带 "language_tag": "en_US"，哪些不带！

提醒：如果你对jsonSchema不熟的话，找个文档看一下。甚至我建议你也别去熟悉了，大概率你对前端已经忘记了或者就不会。这玩意丢给前端去研究。

实操调试

流程我都懂了，接下来简单调试一下先，弄个店铺直接开干

根据官方的示例，我现填充部分熟悉数据

Listing API

这属性数据你咋知道填的对不对？

如果你直接提交，亚马逊服务自己也会校验你填充的body是否正确

添加图片注释，不超过 140 字（可选）

这不是我们正常的作业逻辑，我们得先把数据在自己本地校验正常才去提交。

我们把jsonSchema和body复制到在线的jsonschema validator https://www.jsonschemavalidator.net/s/ttYPYIKR

亚马逊刊登 Listing API

这样一看就明白异常信息的缺失或异常。根据异常信息修改body

正常是提示【No errors found. JSON validates against the schema】，然后才能通告Listing正常提交，提交完成之后你会收到提交成功的提示，这并不意味着产品创建成功了，等待5-10分钟后通过get Listings Item 查看issues是否有异常提示。

jsonSchema

落地方案研究

商品类目

以上通过手动操作调通了整个流程，接下来该考虑如何落地方案。咱不会不要紧，市场上找些已落地的ERP学习一下，最后发现赛狐(店小秘)已经实现了，那就参考下他是怎么做的吧。

类目选择，看着蛮简单的，赛狐自己做了中文翻译。

亚马逊刊登 Listing API

类目信息可以通过报告接口把所有站点的类目数据扒拉下来，为此我从头开始花了不少时间去梳理这份数据和数据结构。

亚马逊刊登 Listing API

获取所有类目JsonSchema

为了消除差异，多做点，把每个站点类目的JsonSchema都取回来存储。有好的方案欢迎指正讨论。

表单渲染

接下来我犯难了，不同类目的必填属性是不一样的，在前端如何设计动态表单？

然后在这一块又花了不少人力去研究，最后我们选择了Ajv：Ajv JSON schema validator ，直接拿亚马逊返回的schema是用不了的，需要前端简单处理一下转换符合框架的逻辑。

必填属性，联动属性

动态表单可以渲染了，接下来要处理必填属性标*的问题，属性联动的问题

一开始的方向跑偏了，一直在后端捣鼓这些，想着把不同类目Schema的必填属性都获取到存下来，告诉前端哪些是必填的，这方面赛狐就是这样的，所以思路也是跟着这个在走，看着官方也给出了校验示例java networknt/json-schema-validator校验，NND就没有正常过，使用networknt/json-schema-validator 校验的时候，看报错会从官方schema.json文件里读取schema的url信息，然后这个地址( https://schemas.amazon.com/selling-partners/definitions/product-types/meta-schema/v1)文档说是不能读取的，这尼玛玩呢。官网给的示例也是没法用，可能也是我菜吧~~~有谁用官网示例schema校验调通了的请赐教。

亚马逊刊登 Listing API

很奇葩的是，通过网友的提示，把schema里的schema，和id属性删掉，居然就可以了，这样 networknt就不会去判断schema url是否存在。但这有点反常呀~~~ 但是如何校验的时候不请求json里的$schema url，我在源码里没看懂怎么去用，后面跑到github去提了这个问题，很快获得了官方的专业回答，nice