Legitmark API Platform Documentation

本指南介绍如何构建可靠的 Webhook 处理程序，包含多种语言的代码示例和生产环境建议。

使用 TypeScript SDK

如果您使用 TypeScript SDK（v0.2.0+），SDK 提供类型化的 Payload 和辅助函数来处理事件解析和状态检查。

import {
  parseWebhookEvent,
  isAuthentic,
  isCounterfeit,
  needsResubmission,
  isCancelled,
} from 'legitmark';

app.post('/webhooks/legitmark', express.json(), (req, res) => {
  const event = parseWebhookEvent(req.body);

  if (isAuthentic(event)) {
    markItemAsAuthentic(event.reference_id);
  } else if (isCounterfeit(event)) {
    flagItem(event.reference_id);
  } else if (needsResubmission(event)) {
    requestNewPhotos(event.reference_id, event.sides);
  } else if (isCancelled(event)) {
    closeCase(event.sr_uuid);
  }

  res.status(200).send('OK');
});

parseWebhookEvent() 验证 Payload 结构并返回类型化的 LegitmarkWebhookEvent。辅助函数检查特定的状态组合：

辅助函数	返回 `true` 的条件
`isAuthentic(event)`	`COMPLETE + APPROVED` — 商品为正品
`isCounterfeit(event)`	`COMPLETE + REJECTED` — 商品非正品
`isCancelled(event)`	`CANCELLED` — 请求已取消
`needsResubmission(event)`	`media_rejected` — 图片需要重新上传
`isQcApproved(event)`	`QC + APPROVED` — 照片通过质量审核
`isAuthenticationInProgress(event)`	`UNDERWAY + ASSIGNED` — 鉴定师正在工作

基础处理程序

如果您未使用 TypeScript SDK，以下是多种语言的示例。

app.post('/webhooks/legitmark', express.json(), (req, res) => {
  const event = req.body;

  switch (event.event_type) {
    case 'state_change':
      if (event.state.primary === 'COMPLETE') {
        updateAuthResult(event.reference_id, event.state.supplement);
      }
      break;

    case 'media_rejected':
      event.sides.forEach(side => {
        flagImageForReupload(event.reference_id, side.side, side.reason);
      });
      break;

    case 'invalidate_sr':
      cancelItem(event.reference_id, event.invalidation_reason.message);
      break;
  }

  res.status(200).send('OK');
});

@app.route('/webhooks/legitmark', methods=['POST'])
def handle_webhook():
    event = request.get_json()

    if event['event_type'] == 'state_change':
        if event['state']['primary'] == 'COMPLETE':
            update_auth_result(event['reference_id'], event['state']['supplement'])

    elif event['event_type'] == 'media_rejected':
        for side in event['sides']:
            flag_for_reupload(event['reference_id'], side['side'], side['reason'])

    elif event['event_type'] == 'invalidate_sr':
        cancel_item(event['reference_id'], event['invalidation_reason']['message'])

    return 'OK', 200

最佳实践

立即返回 200

尽快确认 Webhook。如果处理逻辑复杂或需要调用外部服务，请先将任务加入队列并返回 200。

处理重复投递

您可能会多次收到同一事件。根据 Payload 字段构建去重键：

state_change：sr_uuid + state.primary + state.supplement（同一 SR 会发出多次状态变更）
media_rejected：sr_uuid + event_type
invalidate_sr：sr_uuid + event_type

在生产环境中，请使用持久化存储（数据库、Redis）进行去重。

记录原始 Payload

保存完整的 Webhook Payload 用于调试。出现问题时，拥有原始数据可以大大加快诊断速度。

优雅处理未知事件类型

不要拒绝包含未识别 event_type 值的 Webhook。未来可能会添加新的事件类型。对任何事件都返回 200。

总结

您的 Webhook 处理程序应当：

使用 HTTPS 端点 并在 30 秒内返回 200
保证 幂等性 — 使用 Payload 字段进行去重（不仅仅使用 sr_uuid，因为一个 SR 会发出多个事件）
接受未知事件类型 而不报错（未来可能会添加新事件）
异步处理 复杂逻辑以避免超时

​使用 TypeScript SDK

​基础处理程序

​最佳实践

​总结

使用 TypeScript SDK

基础处理程序

最佳实践

总结