亚马逊刊登业务文档

# 一. 亚马逊
整个文档是介绍公司亚马逊平台内部流程。从店铺授权 -> 基础信息 -> 刊登 -> 同步商品 -> 拉取订单 -> 解析订单 -> 发货整个大概流程说明

# 二. 亚马逊授权

## 1. 简介
亚马逊授权是用的Oauth2授权码模式。这种授权模式需要分两步，所以我们需要提供两个接口，一个接口是给用户输入授权信息获取授权url，第二个接口是提供给平台进行回调

## 2. 授权流程示意图
![](https://amazon-professionnal-1253885479.cos.ap-hongkong.myqcloud.com/20221130/sync_1669809467792.png)

# 三. 亚马逊刊登前置内容
	
## 1. 什么是UPC
UPC条码全名为Universal Product Code(统一商品码),普遍使用于美洲一带。而这个UPC不是AMAZON生成的，是由美国一个代码管理协会颁发的，只不过国内的人破解了这个UPC的规则。而在亚马逊平台商品使用的是自身编码ASIN，在刊登商品时需要**ASIN码与UPC码做对应**才行
	
## 2. 主,子商品
亚马逊平台商品是区分主商品和变种子商品。主商品就类似我们平时购买的一个iphone 手机。变种子商品就是在这个主商品的维度上增加了其它属性。比如128G，黑色，三网通等等等等。一个主商品是可以对应**多个**变种子商品的。 当然也可以**一个单品主商品**直接刊登

## 3. 什么是刊登
首先，刊登不是商品上下架。一定要和商品上下架区分开。商品上下架是要依托于系统店铺内已经录入好的商品信息来做操作。但是刊登是系统店铺中并没有该商品。那么就需要把商品信息通过马帮平台录入到对方平台店铺中。这个**录入**的操作就叫做刊登

# 四. 亚马逊基础数据

## 1. 简介
亚马逊的基础信息是通过一个个的**站点模板excel文件**来存储的。这些基础信息数据是用来辅助商品进行刊登。每个excel文件分别会存储**字段元数据(dataDefinitions),商品刊登模板(template)以及商品类型额外值(valid Values)。** 除此之外，亚马逊还有**专门的类目xml文件，里面存放的是categoryId**。这个categoryId在**美国站点**刊登时,需要通过categoryId去获取对应的itemType。而这个itemType也是由亚马逊的额外node节点excel文件存储。最后会把**字段元数据,类目数据通过RocketMQ(香港)->RabbitMQ(广州)的方式给到PHP**

## 2. 字段元数据
**各个国家**站点模板文件里面有一个Sheet叫Data Defnition(**不同的站点sheet有可能不一样**, 具体情况具体分析)。这个Sheet里面是存放该站点该分类商品刊登时所需要填写的字段, 字段对应的含义, 字段描述, 是否必填等相关信息
	
## 3. productType
**各个国家**站点模板文件里面有一个Sheet叫Valid values(**不同的站点sheet有可能不一样**, 具体情况具体分析)。这个Sheet里面存放的是刊登模板选择不同productType让某些字段展示下拉选项值。怎么去对应字段元数据？**通过字段元数据里Local Label Name来对应**

## 4. categoryId
categoryId就是在刊登时选择刊登商品时所属类目的树型菜单数据携带的id, 这个需要解析类目xml文件

## 5. itemType
itemType是**美国站点**刊登时需要注意的点。在刊登之前，需要先把所有亚马逊的额外node节点excel文件解析到数据库中, 再通过上述categoryId去获取对应的值。最后在刊登时把值放入item_type字段
	
## 6. 字段规则
- ### 单品商品字段规则 & 主商品与子商品字段规则
#### 单品商品必填字段:
feed_product_type, item_sku	brand_name, external_product_id_type, item_name, manufacturer, standard_price, quantity, parent_child
#### 变种主商品必填字段:
feed_product_type,item_sku,brand_name,external_product_id_type,item_name, manufacturer, parent_child, variation_theme
#### 变种子商品必填字段:
feed_product_type,item_sku,brand_name,external_product_id_type,item_name, manufacturer, standard_price, quantity, parent_child, parent_sku, relationship_type(Variation)

- ### 字段元数据之间的规则交叉
刊登时常常会有填写了一个字段,另一个字段就会必填。因此把这方面的校验规则放在**mdc_platform_meta_base.amazon_field_relationship**数据表里

- ### productType额外必填字段
刊登时经常会出现选择了productType以后会有额外必填字段。因此把这方面的校验规则放在**mdc_platform_meta_base.amazon_category_extra_field**数据表里

- ### publicTemplateField必填字段
刊登时有些站点和模板会有专属的必填字段。因此把这方面的校验规则放在**mdc_platform_meta_base.amazon_template_public_field**数据表里

# 五. 亚马逊刊登流程
mdc-product-amazon项目是专门用来和亚马逊平台方进行API交互，主要用于**刊登,  同步, 商品操作, 跟卖**等功能。该项目的入口都是通过**调度中心**项目发送RocketMQ消息来进行触发。

## 1. 流程简介
刊登的流程分为以下几个步骤：
- 用户登陆马帮后台管理系统页面
- 选择要刊登的平台(比如亚马逊,新蛋,lazada等)
- 在页面上录入需要刊登的商品信息
- PHP直接调用调度中心接口
- 调度中心再根据传递过来的平台分发到对应平台服务做刊登处理，并根据MQ消息把结果告知PHP

## 2. 接口说明
### 接口createFeedDocument(/feeds/2021-06-30/documents)
#### 描述:
亚马逊Feed API模块的createFeedDocument接口(/feeds/2021-06-30/documents)。该接口的作用是返回平台侧文件URL,以供客户端进行上传文件与URL绑定
#### 入参解析:
contentType: 告知亚马逊上传文件格式类型
#### 响应解析:
feedDocumentId: 亚马逊上传文件id
url: 上传亚马逊url

### UploadFile SDK代码(亚马逊官方API有)
#### 描述:
亚马逊UploadFile SDK代码(亚马逊官方有Demo,直接传递createFeedDocument上的url和上传文本byte字节数组)。通过把客户端文件HTTP调用上一步获取的文件URL进行绑定上传
#### 入参解析:
无
#### 响应解析:
无

### 接口createFeed(/feeds/2021-06-30/feeds)
#### 描述:
调用亚马逊CreateFeed接口(/feeds/2021-06-30/feeds)，获取FeedId。这个FeedId其实就是亚马逊平台侧标识报告任务Id。同时也会轮询该接口获取任务状态是否处理完毕
#### 入参解析:
contentType: 告知亚马逊上传文件格式类型
marketplaceIds: 市场id
inputFeedDocumentId: 传入createFeedDocument接口返回的feedDocumentId
#### 响应解析:
feedId: 处理文件id
feedType: 处理文件类型
processingStatus: 处理文件状态(CANCELLED, DONE, FATAL, IN_PROGRESS, IN_QUEUE)
resultFeedDocumentId: 获取处理文件结果id

### 接口getFeedDocument(/feeds/2021-06-30/documents/${FeedDocumentId})
#### 描述:
任务状态处理完毕, 拿到FeedDocumentId。调用亚马逊FeedDocument接口获取下载地址(/feeds/2021-06-30/documents/${FeedDocumentId})
#### 入参解析:
feedDocumentId: 接口createFeed返回的feedId
#### 响应解析:
feedDocumentId: 结果文件文档id
url: 结果文件文档下载url地址
compressionAlgorithm: 下载时传入的压缩算法

### DownloadFile SDK代码(亚马逊官方API有)
#### 描述:
根据上一步接口getFeedDocument提供的下载地址,调用亚马逊官方提供SDK代码(亚马逊官方API有)把文件字节流下载到程序内部进行解析
#### 入参解析:
无
#### 响应解析:
无

## 3. 接口调用示意图
![](https://amazon-professionnal-1253885479.cos.ap-hongkong.myqcloud.com/20221128/sync_1669619685829.png)

# 六. 亚马逊同步店铺流程

## 1. 流程简介
- 用户登陆马帮后台管理系统页面
- 选择要同步的平台(比如亚马逊,新蛋,lazada等)
- 在页面上选择自己店铺进行店铺同步或商品同步(有些平台只有店铺同步, 例如亚马逊)
- 根据页面上的操作PHP直接调用调度中心接口
- 调度中心再根据传递过来的平台分发到对应平台服务做同步处理，并根据MQ消息把结果告知PHP

## 2. 接口说明
### 接口createReport接口(/reports/2021-06-30/reports)
#### 描述:
亚马逊REPORTS API模块的createReport接口(/reports/2021-06-30/reports)。该接口的作用是获取店铺刊登所有商品(PS: 这个接口不止是获取刊登所有商品，是根据你传递的Type类型来获取对应报告)
#### 入参解析:
reportType: 创建亚马逊报告类型(https://developer-docs.amazon.com/sp-api/docs/report-type-values)
marketplaceIds: 市场id
#### 响应解析:
reportId: 报告id

### 接口ReportId(/reports/2021-06-30/reports/${ReportId})
#### 描述:
轮询上一步ReportId任务接口(/reports/2021-06-30/reports/${ReportId}), 获取任务状态是否处理完毕
#### 入参解析:
reportId: 报告id
#### 响应解析:
reportDocumentId: 报告文档id
reportType: 报告类型
processingStatus: 报告任务状态

### 接口ReportDocument(/reports/2021-06-30/documents/${reportDocumentId})
#### 描述:
轮询上一步ReportId任务接口(/reports/2021-06-30/reports/${ReportId}), 获取任务状态是否处理完毕
#### 入参解析:
reportDocumentId: 报告文档id
#### 响应解析:
reportDocumentId: 报告文档id
url: 结果文件文档下载url地址
compressionAlgorithm: 下载时传入的压缩算法

### DownloadFile SDK代码(亚马逊官方API有)
#### 描述:
根据上一步接口getFeedDocument提供的下载地址,调用亚马逊官方提供SDK代码(亚马逊官方API有)把文件字节流下载到程序内部进行解析
#### 入参解析:
无
#### 响应解析:
无

### 接口商品详情(/catalog/2022-04-01/items)
#### 描述:
最后根据商品维度获取商品详情(/catalog/2022-04-01/items),发送给PHP
#### 入参解析:
marketplaceIds: 市场id
identifiers: ASIN集合 | SKU集合 | EAN集合 | UPC集合
identifiersType: 类型(ASIN, EAN, SKU, UPC, GTIN....)
includedData: 返回商品详情内容(attributes, dimensions, identifiers, images, productTypes, relationships, salesRanks, summaries, vendorDetails)
pageSize: 返回数量, 最大20条
#### 响应解析:
numberOfResults: 返回结果数
**返回商品结果集合(具体内容取决于入参includedData)如下:**
asin: 商品ASIN码
attributes： 发布属性
dimensions:  尺寸
identifiers: ASIN，SKU,EAN,UPC都会在这个字段(前提有)
images: 商品图片数组
productTypes: 商品类型
relationships: 商品父子关系
salesRanks: 销售评分
summaries: 汇总摘要
vendorDetails: 供应商详细信息

## 3. 接口调用示意图
![](https://amazon-professionnal-1253885479.cos.ap-hongkong.myqcloud.com/20221128/sync_1669619742848.png)

# 七. 亚马逊拉单流程

## 1. 流程简介
- mps-order-pull-***服务接收拉单消息
- 接收拉单消息后调用亚马逊拉取订单列表接口(/orders/v0/orders)
- 拉取到订单数据后保存原始数据到mps-order-meta中间表内并发送消息到mps-task-distribution服务处理
- 最后拿到响应,重新重置任务状态、下次运行时间、下次拉单起始时间

## 2. 接口说明
### list接口(GET /orders/v0/orders)
#### 描述:
亚马逊ORDERS API模块订单list接口(GET /orders/v0/orders)。该接口作用是获取店铺一段时间内某些状态的订单列表
#### 入参解析:
MarketplaceIds： 市场id
CreatedAfter,CreatedBefore: 创建时间范围区间
LastUpdatedAfter, LastUpdatedBefore: 更新时间范围区间
OrderStatuses: 订单状态(PendingAvailability, Pending, Unshipped, PartiallyShipped, InvoiceUnconfirmed, Canceled, Unfulfillable)
SellerOrderId: 售卖订单号
MaxResultsPerPage: 最大结果页
AmazonOrderIds: 亚马逊订单号
#### 响应解析:
**订单数组中每一个订单对象如下(比较重要字段):**
AmazonOrderId: 亚马逊订单号
SellerOrderId: 销售订单号
PurchaseDate: 创建时间
LastUpdateDate: 上次更新时间
OrderStatus: 订单状态
FulfillmentChannel: 履行渠道
ShippingAddress: 配送地址
BuyerInfo: 买家信息
MarketplaceTaxInfo: 市场税率
OrderType: 订单类型
EasyShipShipmentStatus: 发货状态
PaymentMethod: 支付方式
PaymentExecutionDetail: 付款详细信息
OrderTotal: 订单金额
ElectronicInvoiceStatus: 电子发票状态
....

## 3. 接口调用示意图
![](https://amazon-professionnal-1253885479.cos.ap-hongkong.myqcloud.com/20221130/sync_1669809520572.png)

# 八. 亚马逊解析订单流程

## 1. 流程简介
- mps-order-detail-***接收到上述流程mps-task-distribution服务分发处理消息
- 调用亚马逊订单详情接口[**订单商品详情-商品详情不完整**, **订单买方详情(GET /orders/v0/orders/{orderId}/buyerInfo)**, **订单地址详情(GET /orders/v0/orders/{orderId}/address)**, **获取具体商品详情（GET /catalog/2022-04-01/items/{asin}）**] , 进行汇总
- 调用mps-order-meta服务接口，保存订单详情
- 最后删除中间表数据

## 2. 接口说明
### 接口订单商品详情(GET /orders/v0/orders/{orderId}/orderItems)
#### 描述:
获取订单商品详情
#### 入参解析:
orderId：亚马逊订单id
#### 响应解析:
**订单商品数组:**
ASIN: 商品ASIN
SellerSKU： 商品SKU
OrderItemId: 订单itemId
Title: item标题
QuantityOrdered: 订单item数量
ItemPrice: item价格
ShippingPrice: 配送价
ItemTax: item税费
ShippingTax: 配送税费
ShippingDiscount: 配送折扣
ShippingDiscountTax: 配送折扣税
PromotionDiscount: 活动折扣
PromotionDiscountTax: 活动折扣税
PromotionIds: 参与促销活动数组id
IsGift: item是否赠品
BuyerInfo: item对应的买家信息
.....

### 接口订单买方详情(GET /orders/v0/orders/{orderId}/buyerInfo)
#### 描述:
获取订单买方详情
#### 入参解析:
orderId：亚马逊订单id
#### 响应解析:
AmazonOrderId: 亚马逊订单id
BuyerEmail: 买方email
BuyerName: 买方名
BuyerCounty: 买方城市
BuyerTaxInfo: 买方税费
PurchaseOrderNumber: 采购订单编号

### 接口订单地址详情(GET /orders/v0/orders/{orderId}/address)
#### 描述:
获取订单地址详情
#### 入参解析:
orderId：亚马逊订单id
#### 响应解析:
AmazonOrderId: 亚马逊订单id
Name: 地址名
AddressLine1: 街道地址
City: 城市
County: 县
District: 地区
Municipality: 直辖市
StateOrRegion: 州或地区
PostalCode: 邮政编码
CountryCode: 城市编码
......

### 接口商品详情(/catalog/2022-04-01/items)
#### 描述:
最后根据商品维度获取商品详情(/catalog/2022-04-01/items/{asin}),发送给PHP
#### 入参解析:
asin: 商品ASIN码
marketplaceIds: 市场id
includedData: 返回商品详情内容(attributes, dimensions, identifiers, images, productTypes, 
#### 响应解析:
asin: 商品ASIN码
attributes： 发布属性
dimensions:  尺寸
identifiers: ASIN，SKU,EAN,UPC都会在这个字段(前提有)
images: 商品图片数组
productTypes: 商品类型
relationships: 商品父子关系
salesRanks: 销售评分
summaries: 汇总摘要
vendorDetails: 供应商详细信息

## 3. 接口调用示意图
![](https://amazon-professionnal-1253885479.cos.ap-hongkong.myqcloud.com/20221130/sync_1669809583967.png)

# 九. 亚马逊发货流程

## 1. 流程简介
- 第一步就是将发货信息根据亚马逊提供的xsd生成对应的xml文件上传到亚马逊，亚马逊会返回一个feedId给调用方，这时候不代表成功，需要等待大概1分钟
- 第二步根据feedId调用亚马逊的接口获取结果，结果也是一个xml文件，xml文件就会告诉我们结果，如果我们上传上去的xml有问题，这个结果xml文件也会告诉我们

## 2. 接口说明
参考商品刊登

## 3. 接口调用示意图
![](https://amazon-professionnal-1253885479.cos.ap-hongkong.myqcloud.com/20221202/sync_1669978043031.png)