# Webhook 消息格式 (https://sellersheetai.com/zh/help/app/settings/webhooks-schema)

> SellerSheet Webhook HTTPS 推送（schemaVersion 1）的每个字段——请求头、推送、每条消息、店铺、亚马逊原始通知，以及目前推送的每类通知各自的 summary。



[HTTPS Webhook](/zh/help/app/settings/webhooks#https-body) 收到的内容，逐字段说明。同样的内容以 JSON Schema（draft 2020-12）发布在 [sellersheetai.com/schemas/webhooks-v1.json](https://sellersheetai.com/schemas/webhooks-v1.json)，每类通知的示例推送在 [sellersheetai.com/schemas/webhooks-v1-samples.json](https://sellersheetai.com/schemas/webhooks-v1-samples.json)。本页所有数值均为虚构。

处处适用的规则：

* 键名为 camelCase；[`amazon`](#amazon) 内部保留亚马逊自己的写法。
* 每个键都会发送。下表的“必填”是 Schema 要求的字段；非必填的键没有值时发送 `null`（或 `[]`、`{}`）。
* 对象不封闭：`schemaVersion` 1 之内以后可能出现新的键——不认识的键直接忽略。
* 时间为 UTC 的 ISO 8601 日期时间（`2026-10-27T09:28:33Z`）；`amazon` 内部保留亚马逊的原文。

## 请求头 [#headers]

| 请求头                         | 示例                                     | 含义                                                                                                                     |
| --------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `Content-Type`              | `application/json`                     | 始终是 JSON。                                                                                                              |
| `X-SellerSheet-Webhook-Id`  | `0c6f2a8e-4d1b-4e7a-9b35-6e8d2f1a4c90` | Webhook——等于 `webhookId`。                                                                                               |
| `X-SellerSheet-Delivery-Id` | `dlv_8f3a1c9e2b7d4e6fa0b1c2d3e4f5a6b7` | 这次推送——等于 `deliveryId`，每次重试都相同。                                                                                         |
| `X-SellerSheet-Timestamp`   | `1793092113`                           | 这次尝试发出时的 Unix 秒数。                                                                                                      |
| `X-SellerSheet-Signature`   | `sha256=2225d8c4…`                     | `sha256=` 加上以签名密钥为 key、对“时间戳、一个 `.`、原始请求体”计算的十六进制 HMAC-SHA256。[如何校验](/zh/help/app/settings/webhooks#verify-signature)。 |
| `X-SellerSheet-Test`        | `false`                                | **发送测试** 时为 `true`：消息是虚构店铺 `SampleStore` 的示例。                                                                          |

## 推送 [#delivery]

一个请求的请求体：最多 100 条消息，不超过 1 MB。

| 字段               | 类型               | 必填 | 含义                      | 示例                                     |
| ---------------- | ---------------- | -- | ----------------------- | -------------------------------------- |
| `deliveryId`     | string           | 是  | 这次推送。每次重试都相同。           | `dlv_8f3a1c9e2b7d4e6fa0b1c2d3e4f5a6b7` |
| `webhookId`      | string           | 是  | 推送到的 Webhook。           | `0c6f2a8e-4d1b-4e7a-9b35-6e8d2f1a4c90` |
| `organizationId` | string           | 是  | 你的工作区。                  | `7b2e9c41-0d3a-4f6b-8e15-9c2a4d6f8b30` |
| `sentAt`         | date-time        | 是  | 这次尝试发出的时间。              | `2026-10-27T09:28:33Z`                 |
| `attempt`        | integer ≥ 1      | 是  | 第几次尝试：1、2 或 3。          | `1`                                    |
| `schemaVersion`  | integer，`1`      | 否  | 本格式的版本——始终为 `1`。        | `1`                                    |
| `messages`       | [消息](#message)数组 | 是  | 消息，按 SellerSheet 收到的顺序。 |                                        |

## 消息 [#message]

一条亚马逊通知。

| 字段            | 类型                  | 必填 | 含义                                                               | 示例                                     |
| ------------- | ------------------- | -- | ---------------------------------------------------------------- | -------------------------------------- |
| `messageId`   | string              | 是  | 亚马逊的 NotificationId。已处理过的就丢弃。                                    | `5c0e8f4a-2b7d-4e91-a3c6-000000000001` |
| `messageType` | string              | 是  | 亚马逊的通知类型；决定 [`summary`](#summary) 的结构。`schemaVersion` 1 内可能新增类型。 | `LISTINGS_ITEM_ISSUES_CHANGE`          |
| `fingerprint` | string 或 null       | 否  | `sha256:` 加 64 位十六进制字符；亚马逊以新的 `messageId` 再次发布同一变化时，它保持相同。       | `sha256:af6e358a…`                     |
| `store`       | [店铺](#store)或 null  | 否  | 你的店铺和这条消息涉及的站点。送达的消息总是指向你的某个店铺。                                  |                                        |
| `eventTime`   | date-time 或 null    | 否  | 变化发生的时间（亚马逊的 EventTime）。                                         | `2026-10-27T09:14:03Z`                 |
| `publishTime` | date-time 或 null    | 否  | 亚马逊发出的时间。                                                        | `2026-10-27T09:28:30Z`                 |
| `receivedAt`  | date-time           | 是  | SellerSheet 收到的时间。                                               | `2026-10-27T09:28:32Z`                 |
| `summary`     | [summary](#summary) | 是  | SellerSheet 对这条消息的解读，结构由 `messageType` 决定。                       |                                        |
| `amazon`      | [amazon](#amazon)   | 是  | 亚马逊的通知，每个值都与亚马逊发送的一致。                                            |                                        |

## store [#store]

| 字段              | 类型            | 必填 | 含义                                                     | 示例                                     |
| --------------- | ------------- | -- | ------------------------------------------------------ | -------------------------------------- |
| `storeId`       | string        | 是  | SellerSheet 中店铺的 ID。                                   | `3f6c2a9e-5b1d-4c8e-9a7f-2d4e6b8c0a11` |
| `ref`           | string        | 是  | 店铺 ref `<store>-<CC>`：店铺名称加消息涉及的站点。                    | `myStore-US`                           |
| `sellerId`      | string 或 null | 否  | 亚马逊的卖家 ID。                                             | `A1EXAMPLESELLER`                      |
| `marketplaceId` | string 或 null | 否  | 亚马逊的站点 ID——亚马逊没有给出站点时为 `null`（账户健康、报告、上传文件等针对整个账户的消息）。 | `ATVPDKIKX0DER`                        |
| `countryCode`   | string 或 null | 否  | 站点的国家代码。                                               | `US`                                   |
| `connected`     | boolean       | 是  | 店铺没有在 SellerSheet 中连接这个站点时为 `false`。                   | `true`                                 |

## amazon [#amazon]

亚马逊的通知——事实来源。顶层名称固定；每个值都与亚马逊发送的完全一致，保留亚马逊自己的大小写（有些通知是 PascalCase，有些是 camelCase）：两种写法都要能读。

| 字段                     | 类型            | 必填 | 含义                                                                                 | 示例                            |
| ---------------------- | ------------- | -- | ---------------------------------------------------------------------------------- | ----------------------------- |
| `notificationType`     | string        | 是  | 亚马逊的 NotificationType。                                                             | `LISTINGS_ITEM_ISSUES_CHANGE` |
| `notificationVersion`  | string 或 null | 否  | 亚马逊的 NotificationVersion。                                                          | `1.0`                         |
| `payloadVersion`       | string 或 null | 否  | 亚马逊的 PayloadVersion——决定 `payload` 的结构。                                             | `2023-12-13`                  |
| `eventTime`            | string 或 null | 否  | 亚马逊的 EventTime，保留亚马逊的原文。                                                           | `2026-10-27T09:14:03.000Z`    |
| `notificationMetadata` | object        | 否  | 亚马逊的 NotificationMetadata：ApplicationId、SubscriptionId、PublishTime、NotificationId。 |                               |
| `payload`              | object        | 否  | 亚马逊的 Payload，原样不变。                                                                 |                               |

每类通知的 `payload` 由亚马逊在 Selling Partner API 的通知类型参考文档中说明。

## summary [#summary]

每个 summary 都有这四个字段：

| 字段         | 类型                                           | 必填 | 含义                                                                       | 示例                                                                                                                                    |
| ---------- | -------------------------------------------- | -- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `text`     | string                                       | 是  | 一行可读文字：商品和站点、通俗说明，然后是亚马逊的字段名和值。                                          | `SKU SKU-EXAMPLE-01 (B0EXAMPLE01) on US: Listing not buyable (suppressed) · Severities=ERROR · EnforcementActions=LISTING_SUPPRESSED` |
| `severity` | `critical` · `warning` · `info` · `recovery` | 是  | 严重程度——聊天卡片上分别为红、橙、蓝、绿。[各自何时出现](/zh/help/app/settings/webhooks#severity)。 | `critical`                                                                                                                            |
| `sku`      | string 或 null                                | 否  | SKU，亚马逊发送了才有。                                                            | `SKU-EXAMPLE-01`                                                                                                                      |
| `asin`     | string 或 null                                | 否  | ASIN，亚马逊发送了才有。                                                           | `B0EXAMPLE01`                                                                                                                         |

此外是该 `messageType` 自己的字段，见下文，顺序与 Webhook 推送页面一致。本页未列出的类型只带这四个字段。每类通知都有一份完整的示例推送，均通过 Schema 校验：[webhooks-v1-samples.json](https://sellersheetai.com/schemas/webhooks-v1-samples.json)。

| `messageType`                                 | 通知                                            |
| --------------------------------------------- | --------------------------------------------- |
| `LISTINGS_ITEM_ISSUES_CHANGE`                 | [商品问题](#listing-issues)                       |
| `LISTINGS_ITEM_STATUS_CHANGE`                 | [商品状态](#listing-status)                       |
| `BRANDED_ITEM_CONTENT_CHANGE`                 | [品牌内容](#brand-content)                        |
| `ITEM_PRODUCT_TYPE_CHANGE`                    | [商品类型变更](#product-type-change)                |
| `LISTINGS_ITEM_MFN_QUANTITY_CHANGE`           | [自发货库存数量](#self-fulfilled-quantity)           |
| `PRODUCT_TYPE_DEFINITIONS_CHANGE`             | [商品类型定义](#product-type-definitions)           |
| `PRICING_HEALTH`                              | [价格健康](#pricing-health)                       |
| `ANY_OFFER_CHANGED`                           | [竞争报价](#competing-offers)                     |
| `B2B_ANY_OFFER_CHANGED`                       | [企业购报价](#business-offers)                     |
| `FEE_PROMOTION`                               | [费用促销](#fee-promotions)                       |
| `ORDER_CHANGE`                                | [订单变更](#order-changes)                        |
| `FULFILLMENT_ORDER_STATUS`                    | [多渠道配送订单](#mcf-orders)                        |
| `FBA_OUTBOUND_SHIPMENT_STATUS`                | [FBA Onsite 货件（巴西）](#fba-onsite-shipments)    |
| `EXTERNAL_FULFILLMENT_SHIPMENT_STATUS_CHANGE` | [外部仓发货](#external-shipments)                  |
| `FBA_INVENTORY_AVAILABILITY_CHANGES`          | [FBA 库存](#fba-inventory)                      |
| `ITEM_INVENTORY_EVENT_CHANGE`                 | [每小时库存](#hourly-inventory)                    |
| `ITEM_SALES_EVENT_CHANGE`                     | [每小时销售](#hourly-sales)                        |
| `DETAIL_PAGE_TRAFFIC_EVENT`                   | [每小时页面浏览](#hourly-page-views)                 |
| `TRANSACTION_UPDATE`                          | [交易](#transactions)                           |
| `ACCOUNT_STATUS_CHANGED`                      | [账户健康](#account-health)                       |
| `REPORT_PROCESSING_FINISHED`                  | [报告完成](#report-finished)                      |
| `FEED_PROCESSING_FINISHED`                    | [上传文件处理完成](#feed-finished)                    |
| `DATA_KIOSK_QUERY_PROCESSING_FINISHED`        | [Data Kiosk 查询完成](#data-kiosk-query-finished) |

### 商品问题 [#listing-issues]

`LISTINGS_ITEM_ISSUES_CHANGE`——listing 当前生效的问题。亚马逊从不发送问题的具体文字：请在卖家平台打开该 SKU 查看。

| 字段                   | 类型             | 含义                                                                                                                                                             |
| -------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `severities`         | string 数组      | 亚马逊的 Severities：`ERROR`、`WARNING`（不含 `NONE`）。                                                                                                                  |
| `enforcementActions` | string 数组      | 亚马逊的 EnforcementActions：`LISTING_SUPPRESSED`（不可购买）、`ATTRIBUTE_SUPPRESSED`（某个属性值被拒）、`CATALOG_ITEM_REMOVED`（商品目录条目已失效，其上所有报价都不可购买）、`SEARCH_SUPPRESSED`（在搜索中被隐藏）。 |
| `cleared`            | boolean 或 null | 没有任何问题时为 `true`。                                                                                                                                               |

```json
{
  "text": "SKU SKU-EXAMPLE-01 (B0EXAMPLE01) on US: Listing not buyable (suppressed) · Severities=ERROR · EnforcementActions=LISTING_SUPPRESSED",
  "severity": "critical",
  "sku": "SKU-EXAMPLE-01",
  "asin": "B0EXAMPLE01",
  "severities": ["ERROR"],
  "enforcementActions": ["LISTING_SUPPRESSED"],
  "cleared": false
}
```

### 商品状态 [#listing-status]

`LISTINGS_ITEM_STATUS_CHANGE`——listing 当前的状态集合。缺少某个状态即表示相反：没有 `BUYABLE` 表示不可购买，没有 `DISCOVERABLE` 表示不出现在搜索结果中。

| 字段             | 类型             | 含义                                              |
| -------------- | -------------- | ----------------------------------------------- |
| `status`       | string 数组      | 亚马逊的 Status：`BUYABLE`、`DISCOVERABLE`、`DELETED`。 |
| `buyable`      | boolean 或 null | 集合中有 `BUYABLE`。                                 |
| `discoverable` | boolean 或 null | 集合中有 `DISCOVERABLE`。                            |
| `deleted`      | boolean 或 null | 集合中有 `DELETED`。                                 |

```json
{
  "text": "SKU SKU-EXAMPLE-02 (B0EXAMPLE02) on US: Buyable · Status=BUYABLE,DISCOVERABLE",
  "severity": "recovery",
  "sku": "SKU-EXAMPLE-02",
  "asin": "B0EXAMPLE02",
  "status": ["BUYABLE", "DISCOVERABLE"],
  "buyable": true,
  "discoverable": true,
  "deleted": false
}
```

### 品牌内容 [#brand-content]

`BRANDED_ITEM_CONTENT_CHANGE`——你品牌下某个商品目录条目的哪些属性发生了变化。没有 SKU。Webhook 接收的每个品牌所有者店铺各收到一份。

| 字段                  | 类型            | 含义                                   |
| ------------------- | ------------- | ------------------------------------ |
| `brandName`         | string 或 null | 亚马逊的 BrandName。                      |
| `attributesChanged` | string 数组     | 亚马逊的 AttributesChanged——属性名保持亚马逊的写法。 |

```json
{
  "text": "ASIN B0EXAMPLE04 on US: Changed: item_name, bullet_point · AttributesChanged=item_name,bullet_point · BrandName=MyBrand",
  "severity": "info",
  "sku": null,
  "asin": "B0EXAMPLE04",
  "brandName": "MyBrand",
  "attributesChanged": ["item_name", "bullet_point"]
}
```

### 商品类型变更 [#product-type-change]

`ITEM_PRODUCT_TYPE_CHANGE`——某个 ASIN 变化前后的商品类型。它的 listing 需要填写的内容可能随之变化。没有 SKU。

| 字段                    | 类型            | 含义                 |
| --------------------- | ------------- | ------------------ |
| `previousProductType` | string 或 null | 变化前的商品类型，保持亚马逊的写法。 |
| `currentProductType`  | string 或 null | 现在的商品类型。           |

### 自发货库存数量 [#self-fulfilled-quantity]

`LISTINGS_ITEM_MFN_QUANTITY_CHANGE`——某个 SKU 当前的自发货库存数量。没有 ASIN，也不涉及具体站点：这是整个卖家账户的数量。

| 字段                       | 类型             | 含义                                                        |
| ------------------------ | -------------- | --------------------------------------------------------- |
| `quantity`               | integer 或 null | 当前数量；`0` 即缺货。                                             |
| `fulfillmentChannelCode` | string 或 null  | 亚马逊的 FulfillmentChannelCode：`DEFAULT` 是你自己配送；其他代码指某个供货来源。 |

### 商品类型定义 [#product-type-definitions]

`PRODUCT_TYPE_DEFINITIONS_CHANGE`——某个站点商品类型定义的新版本。没有 SKU 和 ASIN。Webhook 接收的每个店铺各收到一份。

| 字段                   | 类型            | 含义                       |
| -------------------- | ------------- | ------------------------ |
| `productTypeVersion` | string 或 null | 亚马逊的 ProductTypeVersion。 |
| `newProductTypes`    | string 数组     | 这个版本新增的商品类型。             |

### 价格健康 [#pricing-health]

`PRICING_HEALTH`——你的报价为什么不能成为推荐报价，以及亚马逊的参考价格。没有 SKU：亚马逊只发送 ASIN。

| 字段                          | 类型                 | 含义                                                                                                        |
| --------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------- |
| `issueType`                 | string 或 null      | 亚马逊的 issueType，例如 `BuyBoxDisqualification`。                                                               |
| `yourPrice`                 | [金额](#money)或 null | 你的到手价：售价加运费。                                                                                              |
| `fulfillmentType`           | string 或 null      | `AFN`（FBA）或 `MFN`（FBM）。                                                                                   |
| `competitivePriceThreshold` | [金额](#money)或 null | 亚马逊的竞争价格阈值。                                                                                               |
| `referencePrices`           | [金额](#money)对象     | 亚马逊发送的每个参考价格，使用亚马逊的名称：`competitivePriceThreshold`、`averageSellingPrice`、`retailOfferPrice`、`msrpPrice` 等。 |

```json
{
  "text": "ASIN B0EXAMPLE03 on US: Not eligible for the featured offer · issueType=BuyBoxDisqualification · yours 29.99 USD, FBA (fulfillmentType=AFN) · competitivePriceThreshold=24.99 USD · averageSellingPrice=26.50 USD",
  "severity": "warning",
  "sku": null,
  "asin": "B0EXAMPLE03",
  "issueType": "BuyBoxDisqualification",
  "yourPrice": { "amount": 29.99, "currencyCode": "USD" },
  "fulfillmentType": "AFN",
  "competitivePriceThreshold": { "amount": 24.99, "currencyCode": "USD" },
  "referencePrices": {
    "competitivePriceThreshold": { "amount": 24.99, "currencyCode": "USD" },
    "averageSellingPrice": { "amount": 26.5, "currencyCode": "USD" }
  }
}
```

### 竞争报价 [#competing-offers]

`ANY_OFFER_CHANGED`——有其他卖家的 ASIN 上的购物车、你的报价，以及最多五个其他卖家的报价。亚马逊只给卖家 ID，从不给名称，也没有 SKU。

| 字段                    | 类型                    | 含义                                  |
| --------------------- | --------------------- | ----------------------------------- |
| `changeType`          | string 或 null         | 亚马逊的 OfferChangeType，例如 `External`。 |
| `buyBox`              | [购物车](#buy-box)或 null | 购物车价格和持有者。                          |
| `yourOffer`           | [报价](#offer)或 null    | 你自己的报价，在亚马逊列出的报价中时才有。               |
| `competitors`         | [报价](#offer)数组，最多 5 个 | 其他卖家的报价，按亚马逊的顺序。                    |
| `numberOfOffers`      | integer 或 null        | ASIN 上的全部报价数，包含所有成色和配送渠道。           |
| `sellersChanged`      | boolean 或 null        | ASIN 上的卖家与上一条相关消息不同。第一条消息为 `true`。  |
| `buyBoxWinnerChanged` | boolean 或 null        | 购物车赢家与上一条相关消息不同。第一条消息为 `true`。      |

```json
{
  "text": "ASIN B0EXAMPLE05 on US: 1 other seller: A2EXAMPLEOTHER 19.99 USD FBM, Buy Box, 95% of 120 · you 21.49 USD FBA, 99% of 812 · OfferChangeType=External · BuyBoxPrice=19.99 USD · NumberOfOffers=new Merchant 1,new Amazon 1",
  "severity": "warning",
  "sku": null,
  "asin": "B0EXAMPLE05",
  "changeType": "External",
  "buyBox": {
    "price": { "amount": 19.99, "currencyCode": "USD" },
    "sellerId": "A2EXAMPLEOTHER",
    "isYours": false
  },
  "yourOffer": {
    "sellerId": "A1EXAMPLESELLER",
    "price": { "amount": 21.49, "currencyCode": "USD" },
    "shipping": { "amount": 0.0, "currencyCode": "USD" },
    "fulfillment": "FBA",
    "isBuyBoxWinner": false,
    "feedbackRating": 99,
    "feedbackCount": 812
  },
  "competitors": [
    {
      "sellerId": "A2EXAMPLEOTHER",
      "price": { "amount": 19.99, "currencyCode": "USD" },
      "shipping": { "amount": 0.0, "currencyCode": "USD" },
      "fulfillment": "FBM",
      "isBuyBoxWinner": true,
      "feedbackRating": 95,
      "feedbackCount": 120
    }
  ],
  "numberOfOffers": 2,
  "sellersChanged": true,
  "buyBoxWinnerChanged": true
}
```

### 企业购报价 [#business-offers]

`B2B_ANY_OFFER_CHANGED`——与[竞争报价](#competing-offers)相同，针对 ASIN 上的企业购（B2B）报价。没有 `changeType`、`sellersChanged` 和 `buyBoxWinnerChanged`。

| 字段               | 类型                    | 含义                       |
| ---------------- | --------------------- | ------------------------ |
| `buyBox`         | [购物车](#buy-box)或 null | 企业购购物车的价格和持有者。           |
| `yourOffer`      | [报价](#offer)或 null    | 你自己的企业购报价，在亚马逊列出的报价中时才有。 |
| `competitors`    | [报价](#offer)数组，最多 5 个 | 其他卖家的企业购报价，按亚马逊的顺序。      |
| `numberOfOffers` | integer 或 null        | ASIN 上的全部企业购报价数。         |

### 费用促销 [#fee-promotions]

`FEE_PROMOTION`——亚马逊为你提供的费用促销：内容、时间，以及第一项折扣。只涉及一个商品时带 `sku` 或 `asin`。

| 字段                 | 类型                 | 含义                                        |
| ------------------ | ------------------ | ----------------------------------------- |
| `promotionType`    | string 或 null      | 亚马逊的 FeePromotionType。                    |
| `description`      | string 或 null      | 亚马逊对这项促销的说明（FeePromotionTypeDescription）。 |
| `effectiveFrom`    | date-time 或 null   | 开始时间。                                     |
| `effectiveThrough` | date-time 或 null   | 结束时间。                                     |
| `feeType`          | string 或 null      | 打折的费用，例如 `ReferralFee`。                   |
| `discountType`     | string 或 null      | 亚马逊的 FeeDiscountType，例如 `PERCENTAGE`。     |
| `discountValue`    | number 或 null      | 亚马逊的 FeeDiscountValue。                    |
| `discountAmount`   | [金额](#money)或 null | 折扣金额，亚马逊给出时才有。                            |

### 订单变更 [#order-changes]

`ORDER_CHANGE`——订单当前的状态和变化内容。订单只有一个 SKU 时带 `sku`。

| 字段                     | 类型             | 含义                                                                                   |
| ---------------------- | -------------- | ------------------------------------------------------------------------------------ |
| `amazonOrderId`        | string 或 null  | 订单号。                                                                                 |
| `changeType`           | string 或 null  | 亚马逊的 OrderChangeType：`BuyerRequestedChange`、`OrderStatusChange`、`DeliveryTipChange`。 |
| `changeReason`         | string 或 null  | 亚马逊的 ChangeReason，例如 `Buyer Requested Cancel`。                                       |
| `orderStatus`          | string 或 null  | 订单当前的状态，例如 `Unshipped`。                                                              |
| `fulfillmentType`      | string 或 null  | `AFN`（FBA）或 `MFN`（FBM）。                                                              |
| `buyerRequestedCancel` | boolean 或 null | 订单中有商品标明买家申请取消。                                                                      |
| `sellerSkus`           | string 数组      | 订单里的 SKU。                                                                            |

### 多渠道配送订单 [#mcf-orders]

`FULFILLMENT_ORDER_STATUS`——多渠道配送订单、它的包裹和物流单号。亚马逊不给出站点。订单只有一个 SKU 时带 `sku`。

| 字段           | 类型                       | 含义                                                                                |
| ------------ | ------------------------ | --------------------------------------------------------------------------------- |
| `orderId`    | string 或 null            | 配送订单号。                                                                            |
| `eventType`  | string 或 null            | 亚马逊的 eventType，例如 `ORDER_STATUS_CHANGED`。                                         |
| `status`     | string 或 null            | `PROCESSING`、`COMPLETE`、`COMPLETE_PARTIAL`、`CANCELLED`、`UNFULFILLABLE`、`INVALID`。 |
| `sellerSkus` | string 数组                | 订单里的 SKU。                                                                         |
| `packages`   | [包裹](#package)数组，最多 20 个 | 各货件的包裹，附承运商的物流单号。                                                                 |

### FBA Onsite 货件（巴西） [#fba-onsite-shipments]

`FBA_OUTBOUND_SHIPMENT_STATUS`——亚马逊为某个订单创建或取消的货件。仅限巴西。

| 字段                 | 类型            | 含义                                           |
| ------------------ | ------------- | -------------------------------------------- |
| `amazonOrderId`    | string 或 null | 订单号。                                         |
| `amazonShipmentId` | string 或 null | 货件。                                          |
| `shipmentStatus`   | string 或 null | 亚马逊的 ShipmentStatus：`Created` 或 `Cancelled`。 |

### 外部仓发货 [#external-shipments]

`EXTERNAL_FULFILLMENT_SHIPMENT_STATUS_CHANGE`——你自己的配送仓里某个货件的状态变化。亚马逊不给出站点。

| 字段               | 类型            | 含义                               |
| ---------------- | ------------- | -------------------------------- |
| `shipmentId`     | string 或 null | 货件。                              |
| `shipmentStatus` | string 或 null | 当前状态，例如 `CREATED` 或 `CANCELLED`。 |
| `channelName`    | string 或 null | 亚马逊的 channelName。                |
| `locationId`     | string 或 null | 你的配送仓。                           |

### FBA 库存 [#fba-inventory]

`FBA_INVENTORY_AVAILABILITY_CHANGES`——某个 SKU 的 FBA 库存数量，汇总亚马逊列出的所有站点，并按站点列出。消息的站点是列出的第一个站点。

| 字段              | 类型                               | 含义                 |
| --------------- | -------------------------------- | ------------------ |
| `fnsku`         | string 或 null                    | 亚马逊的 FNSKU。        |
| `fulfillable`   | integer 或 null                   | 可售件数；`0` 即 FBA 缺货。 |
| `inbound`       | integer 或 null                   | 处理中 + 已发货 + 接收中。   |
| `reserved`      | integer 或 null                   | 所有预留数量。            |
| `unfulfillable` | integer 或 null                   | 不可售件数。             |
| `marketplaces`  | [站点库存](#marketplace-inventory)数组 | 按站点列出的同样数量。        |

### 每小时库存 [#hourly-inventory]

`ITEM_INVENTORY_EVENT_CHANGE`——一小时内的高可用库存，汇总亚马逊列出的所有 ASIN。只列出一个 ASIN 时带 `asin`。

| 字段                         | 类型               | 含义             |
| -------------------------- | ---------------- | -------------- |
| `startTime`                | date-time 或 null | 这一小时的开始。       |
| `endTime`                  | date-time 或 null | 这一小时的结束。       |
| `asinCount`                | integer 或 null   | 亚马逊列出的 ASIN 数。 |
| `highlyAvailableInventory` | integer 或 null   | 高可用库存件数。       |

### 每小时销售 [#hourly-sales]

`ITEM_SALES_EVENT_CHANGE`——一小时内的订购件数和销售额，汇总亚马逊列出的所有 ASIN。只列出一个 ASIN 时带 `asin`。

| 字段               | 类型               | 含义             |
| ---------------- | ---------------- | -------------- |
| `startTime`      | date-time 或 null | 这一小时的开始。       |
| `endTime`        | date-time 或 null | 这一小时的结束。       |
| `asinCount`      | integer 或 null   | 亚马逊列出的 ASIN 数。 |
| `orderedUnits`   | integer 或 null   | 订购件数。          |
| `orderedRevenue` | [金额](#money)数组   | 订购销售额，每个币种一项。  |

### 每小时页面浏览 [#hourly-page-views]

`DETAIL_PAGE_TRAFFIC_EVENT`——一小时内的详情页浏览量，汇总亚马逊列出的所有 ASIN。只列出一个 ASIN 时带 `asin`。

| 字段            | 类型               | 含义                        |
| ------------- | ---------------- | ------------------------- |
| `startTime`   | date-time 或 null | 这一小时的开始。                  |
| `endTime`     | date-time 或 null | 这一小时的结束。                  |
| `asinCount`   | integer 或 null   | 亚马逊列出的 ASIN 数。            |
| `glanceViews` | integer 或 null   | 详情页浏览量（亚马逊的 GlanceViews）。 |

### 交易 [#transactions]

`TRANSACTION_UPDATE`——一笔记入你账户的交易。

| 字段                   | 类型                 | 含义                                           |
| -------------------- | ------------------ | -------------------------------------------- |
| `transactionType`    | string 或 null      | 亚马逊的 TransactionType，例如 `Shipment`。          |
| `postedDate`         | date-time 或 null   | 入账时间。                                        |
| `totalAmount`        | [金额](#money)或 null | 总金额。                                         |
| `accountType`        | string 或 null      | 亚马逊的 AccountType，例如 `PAYABLE`。               |
| `relatedIdentifiers` | string 对象          | 亚马逊的 RelatedIdentifiers，名称 → 值（`OrderId` 等）。 |

### 账户健康 [#account-health]

`ACCOUNT_STATUS_CHANGED`——卖家账户的状态。不涉及商品；消息的 `store` 是你的店铺及其第一个站点。

| 字段               | 类型            | 含义                                  |
| ---------------- | ------------- | ----------------------------------- |
| `previousStatus` | string 或 null | `NORMAL`、`AT_RISK` 或 `DEACTIVATED`。 |
| `currentStatus`  | string 或 null | `NORMAL`、`AT_RISK` 或 `DEACTIVATED`。 |

```json
{
  "text": "Account at risk · PreviousAccountStatus=NORMAL · CurrentAccountStatus=AT_RISK",
  "severity": "warning",
  "sku": null,
  "asin": null,
  "previousStatus": "NORMAL",
  "currentStatus": "AT_RISK"
}
```

### 报告完成 [#report-finished]

`REPORT_PROCESSING_FINISHED`——报告请求处理结束。包括 SellerSheet 为同步你店铺数据而请求的报告。亚马逊不给出站点。

| 字段                 | 类型            | 含义                                           |
| ------------------ | ------------- | -------------------------------------------- |
| `reportId`         | string 或 null | 报告。                                          |
| `reportType`       | string 或 null | 亚马逊的 reportType。                             |
| `processingStatus` | string 或 null | `DONE`、`CANCELLED`（亚马逊没有数据，或请求被取消）或 `FATAL`。 |
| `reportDocumentId` | string 或 null | 要下载的文档，`DONE` 时才有。                           |

### 上传文件处理完成 [#feed-finished]

`FEED_PROCESSING_FINISHED`——上传文件（feed）处理结束。亚马逊不给出站点。

| 字段                     | 类型            | 含义                                     |
| ---------------------- | ------------- | -------------------------------------- |
| `feedId`               | string 或 null | 上传文件。                                  |
| `feedType`             | string 或 null | 亚马逊的 feedType，例如 `JSON_LISTINGS_FEED`。 |
| `processingStatus`     | string 或 null | `DONE`、`CANCELLED` 或 `FATAL`。          |
| `resultFeedDocumentId` | string 或 null | 处理报告的文档，`DONE` 时才有。                    |

### Data Kiosk 查询完成 [#data-kiosk-query-finished]

`DATA_KIOSK_QUERY_PROCESSING_FINISHED`——Data Kiosk 查询结束。亚马逊不给出站点。

| 字段                 | 类型            | 含义                            |
| ------------------ | ------------- | ----------------------------- |
| `queryId`          | string 或 null | 查询。                           |
| `processingStatus` | string 或 null | `DONE`、`CANCELLED` 或 `FATAL`。 |
| `dataDocumentId`   | string 或 null | 数据文档；查询没有匹配到数据时为 `null`。      |
| `errorDocumentId`  | string 或 null | 错误文档，`FATAL` 时才有。             |
| `nextToken`        | string 或 null | 结果还有下一页时才有。                   |

## 对象 [#objects]

### 金额 [#money]

| 字段             | 类型            | 必填 | 含义           |
| -------------- | ------------- | -- | ------------ |
| `amount`       | number        | 是  | 金额。          |
| `currencyCode` | string 或 null | 否  | 币种，例如 `USD`。 |

### 报价 [#offer]

| 字段               | 类型                   | 必填            | 含义         |
| ---------------- | -------------------- | ------------- | ---------- |
| `sellerId`       | string               | 是             | 亚马逊的卖家 ID。 |
| `price`          | [金额](#money)或 null   | 否             | 售价。        |
| `shipping`       | [金额](#money)或 null   | 否             | 运费。        |
| `fulfillment`    | `FBA` · `FBM` 或 null | 否             | 由谁配送。      |
| `isBuyBoxWinner` | boolean              | 否（默认 `false`） | 这个报价持有购物车。 |
| `feedbackRating` | integer 或 null       | 否             | 好评率，百分比。   |
| `feedbackCount`  | integer 或 null       | 否             | 评分数量。      |

### 购物车 [#buy-box]

| 字段         | 类型                 | 必填 | 含义                          |
| ---------- | ------------------ | -- | --------------------------- |
| `price`    | [金额](#money)或 null | 否  | 购物车到手价。                     |
| `sellerId` | string 或 null      | 否  | 持有购物车的卖家，当亚马逊列出的某个报价持有它时才有。 |
| `isYours`  | boolean 或 null     | 否  | 购物车在你手上。                    |

### 包裹 [#package]

| 字段               | 类型            | 必填 | 含义                   |
| ---------------- | ------------- | -- | -------------------- |
| `packageId`      | string 或 null | 否  | 包裹。                  |
| `status`         | string 或 null | 否  | 包裹状态，例如 `DELIVERED`。 |
| `carrierCode`    | string 或 null | 否  | 承运商，例如 `FEDEX`。      |
| `trackingNumber` | string 或 null | 否  | 承运商的物流单号。            |

### 站点库存 [#marketplace-inventory]

| 字段              | 类型            | 必填        | 含义               |
| --------------- | ------------- | --------- | ---------------- |
| `marketplaceId` | string 或 null | 否         | 亚马逊的站点 ID。       |
| `countryCode`   | string 或 null | 否         | 站点的国家代码。         |
| `fulfillable`   | integer       | 否（默认 `0`） | 可售件数。            |
| `inbound`       | integer       | 否（默认 `0`） | 处理中 + 已发货 + 接收中。 |
| `reserved`      | integer       | 否（默认 `0`） | 所有预留数量。          |
| `unfulfillable` | integer       | 否（默认 `0`） | 不可售件数。           |

## 校验 [#validating]

任何支持 JSON Schema draft 2020-12 的校验器都能用 [webhooks-v1.json](https://sellersheetai.com/schemas/webhooks-v1.json) 校验请求体。Schema 按 `messageType` 确定 `summary` 的结构（每类通知一条“如果 `messageType` 是这个类型，那么 `summary` 就是这个结构”的规则），所以校验器会按每条消息自己的类型检查它的 summary。