Legitmark API Platform Documentation

Legitmark 发送三种事件类型。每个 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

字段