> ## Documentation Index
> Fetch the complete documentation index at: https://docs.legitmark.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 事件类型

> 每种 Legitmark Webhook 事件的详细 Payload 结构和字段说明。

Legitmark 发送三种事件类型。每个 Webhook 目标地址自动接收所有事件。

## state\_change

当服务请求转换到新状态时发送。这是跟踪鉴定进度和结果的主要事件。

### Payload

```json theme={null}
{
  "event_type": "state_change",
  "sr_uuid": "b16c763b-1723-455d-ba29-164418044886",
  "reference_id": "YOUR-INTERNAL-ITEM-ID",
  "state": {
    "primary": "COMPLETE",
    "supplement": "APPROVED"
  },
  "timestamp": "2026-02-10T12:00:00.000Z"
}
```

### 字段

<ResponseField name="event_type" type="string" required>
  固定为 `"state_change"`。
</ResponseField>

<ResponseField name="sr_uuid" type="string" required>
  服务请求 UUID。
</ResponseField>

<ResponseField name="reference_id" type="string | null">
  您的内部商品 ID — 创建服务请求时设置的 `external_id`。
</ResponseField>

<ResponseField name="state" type="object" required>
  <Expandable title="state 属性">
    <ResponseField name="primary" type="string" required>
      服务请求的主要状态。
    </ResponseField>

    <ResponseField name="supplement" type="string | null">
      提供额外上下文的补充状态详情。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="timestamp" type="string" required>
  状态变更发生时的 ISO 8601 时间戳。
</ResponseField>

### 状态转换

下表列出了您应该处理的最常见状态转换：

| `state.primary` | `state.supplement` | 含义                                         |
| --------------- | ------------------ | ------------------------------------------ |
| `QC`            | `PENDING`          | 照片已提交，正在质量审核中                              |
| `QC`            | `REJECTED`         | 照片未通过质量审核 — 随后会收到包含详情的 `media_rejected` 事件 |
| `QC`            | `APPROVED`         | 照片通过质量审核，鉴定开始                              |
| `UNDERWAY`      | `ASSIGNED`         | 鉴定师已分配                                     |
| `COMPLETE`      | `APPROVED`         | 商品为正品                                      |
| `COMPLETE`      | `REJECTED`         | 商品非正品                                      |

<Tip>
  最重要的状态转换是 `COMPLETE` + `APPROVED` 或 `COMPLETE` + `REJECTED` — 这是**最终鉴定结果**。参阅[服务请求状态](/cn/partner/service-request-states)了解完整的状态机。

  使用 TypeScript SDK（`v0.2.0+`），您可以使用 `isAuthentic(event)` 和 `isCounterfeit(event)` 来检查这些状态，而无需手动比较字符串。参阅 [Webhook 处理指南](/cn/webhook-reference/handling)。
</Tip>

***

## media\_rejected

当上传的图片未通过质量审核时发送。每张被拒绝的图片都包含面名称和拒绝原因，以便您提示用户重新上传特定照片。

### Payload

```json theme={null}
{
  "event_type": "media_rejected",
  "sr_uuid": "b16c763b-1723-455d-ba29-164418044886",
  "reference_id": "YOUR-INTERNAL-ITEM-ID",
  "sides": [
    {
      "side": "Front",
      "reason": "图像模糊",
      "message": "提交的图像太模糊。请拍摄更清晰的照片，确保最小的运动以提高准确性。"
    },
    {
      "side": "Interior",
      "reason": "光线不足",
      "message": "提交的图像光线不足。请拍摄一张光线更好的新照片以提高可见度。"
    }
  ],
  "timestamp": "2026-02-10T12:15:00.000Z"
}
```

### 字段

<ResponseField name="event_type" type="string" required>
  固定为 `"media_rejected"`。
</ResponseField>

<ResponseField name="sr_uuid" type="string" required>
  服务请求 UUID。
</ResponseField>

<ResponseField name="reference_id" type="string | null">
  您的内部商品 ID。
</ResponseField>

<ResponseField name="sides" type="array" required>
  被拒绝图片及原因的数组。

  <Expandable title="sides[] 属性">
    <ResponseField name="side" type="string" required>
      被拒绝面的名称（例如 `"Front"`、`"Label"`、`"Back"`）。
    </ResponseField>

    <ResponseField name="reason" type="string" required>
      拒绝原因。这些是来自 Legitmark 原因数据库的人类可读字符串（例如 `"图像模糊"`、`"光线不足"`）。随着新原因的添加，值可能会变化。
    </ResponseField>

    <ResponseField name="message" type="string">
      包含用户修复建议的详细描述。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="timestamp" type="string" required>
  ISO 8601 时间戳。
</ResponseField>

<Warning>
  收到 `media_rejected` 事件时，用户需要重新上传被拒绝的特定面的图片，服务请求才能继续。请使用 `side` 名称和 `message` 提示用户，以提供最佳体验。
</Warning>

<Tip>
  使用 TypeScript SDK，`needsResubmission(event)` 对此事件类型返回 `true`。参阅 [Webhook 处理指南](/cn/webhook-reference/handling)。
</Tip>

***

## invalidate\_sr

当服务请求被取消时发送。

### Payload

```json theme={null}
{
  "event_type": "invalidate_sr",
  "sr_uuid": "b16c763b-1723-455d-ba29-164418044886",
  "reference_id": "YOUR-INTERNAL-ITEM-ID",
  "invalidation_reason": {
    "code": "CANCELLED",
    "message": "Unsupported Product or SKU. The product or SKU provided isn't supported under our current service guidelines."
  },
  "timestamp": "2026-02-10T14:30:00.000Z"
}
```

### 字段

<ResponseField name="event_type" type="string" required>
  固定为 `"invalidate_sr"`。
</ResponseField>

<ResponseField name="sr_uuid" type="string" required>
  服务请求 UUID。
</ResponseField>

<ResponseField name="reference_id" type="string | null">
  您的内部商品 ID。
</ResponseField>

<ResponseField name="invalidation_reason" type="object" required>
  <Expandable title="invalidation_reason 属性">
    <ResponseField name="code" type="string" required>
      原因代码。目前固定为 `"CANCELLED"`。未来可能会增加其他代码。
    </ResponseField>

    <ResponseField name="message" type="string" required>
      具体的取消原因。常见值包括：

      * `"Unsupported Product or SKU"`（不支持的产品或SKU）
      * `"Unsupported Channel"`（不支持的渠道）
      * `"Service Request Inactivity"`（服务请求不活跃）
      * `"Duplicate Service Request"`（重复的服务请求）
      * `"Insufficient Product Information"`（产品信息不足）
      * `"Customer Requested Cancellation"`（客户请求取消）
      * `"Poor Image Quality or Unusable Media"`（图像质量差或不可用的媒体）

      也可能出现自定义的文本原因。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="timestamp" type="string" required>
  ISO 8601 时间戳。
</ResponseField>