> ## 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 イベントの詳細なペイロード構造とフィールドリファレンス。

Legitmark は 3 種類のイベントタイプを送信します。すべての 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` です — これが**最終鑑定結果**です。完全なステートマシンについては[サービスリクエストのステータス](/ja/partner/service-request-states)をご覧ください。

  TypeScript SDK（`v0.2.0+`）を使用すると、文字列を手動で比較する代わりに `isAuthentic(event)` と `isCounterfeit(event)` でチェックできます。[Webhook 処理ガイド](/ja/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 処理ガイド](/ja/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>