Legitmark API Platform Documentation

Legitmark は 3 種類のイベントタイプを送信します。すべての Webhook 送信先は自動的にすべてのイベントを受信します。

state_change

サービスリクエストが新しいステータスに遷移したときに送信されます。鑑定の進捗と結果を追跡するための主要なイベントです。

Payload

{
  "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"
}

フィールド

string

必須

常に "state_change" です。

string

必須

サービスリクエスト UUID。

string | null

貴社の内部商品 ID — サービスリクエスト作成時に設定した external_id。

object

必須

表示 state プロパティ

string

必須

サービスリクエストの主要ステータス。

string | null

追加のコンテキストを提供する補足ステータス。

string

必須

ステータス変更が発生した時点の ISO 8601 タイムスタンプ。

ステータス遷移

以下の表は、処理すべき最も一般的なステータス遷移を示しています：

`state.primary`	`state.supplement`	意味
`QC`	`PENDING`	写真が送信され、品質審査中
`QC`	`REJECTED`	写真が品質審査に不合格 — 詳細を含む `media_rejected` イベントが続きます
`QC`	`APPROVED`	写真が品質審査を通過、鑑定開始
`UNDERWAY`	`ASSIGNED`	鑑定士が割り当てられた
`COMPLETE`	`APPROVED`	商品は本物
`COMPLETE`	`REJECTED`	商品は本物ではない

最も重要なステータス遷移は COMPLETE + APPROVED または COMPLETE + REJECTED です — これが最終鑑定結果です。完全なステートマシンについてはサービスリクエストのステータスをご覧ください。TypeScript SDK（v0.2.0+）を使用すると、文字列を手動で比較する代わりに isAuthentic(event) と isCounterfeit(event) でチェックできます。Webhook 処理ガイドを参照してください。

media_rejected

アップロードされた画像が品質管理に通らなかった場合に送信されます。拒否された各画像には面の名前と拒否理由が含まれており、ユーザーに特定の写真の再アップロードを促すことができます。

Payload

{
  "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"
}

フィールド

string

必須

常に "media_rejected" です。

string

必須

サービスリクエスト UUID。

string | null

貴社の内部商品 ID。

array

必須

拒否された画像と理由の配列。

表示 sides[] プロパティ

string

必須

拒否された面の名前（例："Front"、"Label"、"Back"）。

string

必須

拒否理由。Legitmark の理由データベースからの人間が読める文字列です（例："画像がぼやけている"、"照明不足"）。新しい理由が追加されると値が変わる可能性があります。

string

ユーザーが問題を修正するためのガイダンスを含む詳細な説明。

string

必須

ISO 8601 タイムスタンプ。

media_rejected イベントを受信した場合、サービスリクエストを続行するには、ユーザーが拒否された特定の面の画像を再アップロードする必要があります。最適なユーザー体験のために、side の名前と message を使ってユーザーに通知してください。

TypeScript SDK を使用すると、needsResubmission(event) がこのイベントタイプに対して true を返します。Webhook 処理ガイドを参照してください。

invalidate_sr

サービスリクエストがキャンセルされた場合に送信されます。

Payload

{
  "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"
}

フィールド

string

必須

常に "invalidate_sr" です。

string

必須

サービスリクエスト UUID。

string | null

貴社の内部商品 ID。

object

必須

表示 invalidation_reason プロパティ

string

必須

理由コード。現在は常に "CANCELLED" です。将来、追加のコードが導入される可能性があります。

string

必須

具体的なキャンセル理由。一般的な値：

"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"（画像品質が低いまたは使用不可のメディア）

カスタムのフリーテキスト理由も表示される場合があります。

string

必須

ISO 8601 タイムスタンプ。

​state_change

​Payload

​フィールド

​ステータス遷移

​media_rejected

​Payload

​フィールド

​invalidate_sr

​Payload

​フィールド

state_change

Payload

フィールド

ステータス遷移

media_rejected

Payload

フィールド

invalidate_sr

Payload

フィールド