Legitmark API Platform Documentation

分步实施

创建服务请求

当物品准备好进行认证时，创建一个服务请求。这将提供所选物品类别的具体图片要求。API 参考： POST /api/v2/sr必需标头：

const headers = {
  'Authorization': 'Bearer leo_xxxxxxxxx',      // 您的 API 密钥
  'Content-Type': 'application/json'
};

请求数据：

服务 UUID（可选）：合作伙伴服务标识符。如果省略，将根据您的组织和物品类型自动解析。
物品分类体系：来自分类体系映射的类别、类型、品牌 UUID
外部 ID（可选）：用于关联的内部物品标识符

const response = await fetch('https://api.legitmark.com/api/v2/sr', {
  method: 'POST',
  headers,
  body: JSON.stringify({
    // service 可选 - 如果省略将自动解析
    external_id: 'your-internal-ref-123',
    item: {
      category: 'category-uuid',
      type: 'type-uuid',
      brand: 'brand-uuid',
    }
  })
});

const { sr } = await legitmark.sr.create({
  // service 可选 - 如果省略将自动解析
  external_id: 'your-internal-ref-123',
  item: {
    category: 'category-uuid',
    type: 'type-uuid',
    brand: 'brand-uuid',
  },
});

依赖项：

分类体系映射已配置（参见分类体系）

获取图片要求

检索物品类别所需的具体图片面。这会告诉您需要拍摄哪些照片。API 参考： GET /api/v2/sr/{sr_uuid} 带查询参数使用 item=true 和 sides=true 获取服务请求以获得照片列表。如果还需要验证状态对象，请添加 requirements=true：

const response = await fetch(
  `https://api.legitmark.com/api/v2/sr/${srUuid}?item=true&sides=true&requirements=true`,
  { headers }
);
const { sr } = await response.json();

// 面已预先拆分为必需列表和可选列表
for (const side of sr.sides.required) {
  console.log(`${side.name}（${side.side_group_name}）— 必需`);
  console.log(`  ${side.description}`);
  console.log(`  示例: ${side.thumbnail_image}`);
}

for (const side of sr.sides.optional) {
  console.log(`${side.name}（${side.side_group_name}）— 可选`);
}

const { sr } = await legitmark.sr.getWithRequirements(srUuid);

console.log(`必需照片: ${sr.sides.progress.total_required}`);

for (const side of sr.sides.required) {
  console.log(`${side.name}: ${side.description}`);
}

照片要求位于 sr.sides 中，而非 sr.requirements。requirements 对象保存的是验证状态（media_requirements、sides_requirements、item_requirements），不包含照片列表。

响应数据：

sr.sides.required - 认证必须的图片
sr.sides.optional - 提升认证准确度的附加图片
sr.sides.progress - 上传数量和 met 标志
每个面： uuid、name、description、ordinal、required、side_group_name，以及 thumbnail_image / example_image / overlay_image 视觉指南

图片要求：

格式： JPG/JPEG/PNG
尺寸： 最小 600 x 600 像素
文件大小： 每张图片最大 5 MB
质量： 清晰、光线充足、对焦准确的图片

上传图片

使用 Legitmark 的安全 CDN 系统上传图片。对于每个必需面，获取签名 URL 并直接上传到 S3。API 参考： 媒体管理端点

GET https://asset.legitmark.com/intent - 获取预签名上传 URL
PUT /{presigned-url} - 直接 S3 上传

上传流程：

获取上传 URL，使用查询参数：sr（服务请求 UUID）和 side（带文件扩展名的面 UUID）
直接上传到预签名 S3 URL，使用 PUT 请求和二进制数据

// 步骤 1：获取预签名上传 URL
const intentResponse = await fetch(
  `https://asset.legitmark.com/intent?sr=${srUuid}&side=${sideUuid}.jpg`,
  { headers }
);
const { url: presignedUrl } = await intentResponse.json();

// 步骤 2：上传二进制图片数据到预签名 URL
await fetch(presignedUrl, {
  method: 'PUT',
  body: imageFile,
  headers: { 'Content-Type': 'image/jpeg' }
});

// 从文件路径上传
await legitmark.images.uploadForSide(srUuid, sideUuid, './photo.jpg');

// 或从缓冲区上传
await legitmark.images.uploadForSide(srUuid, sideUuid, imageBuffer);

请勿在向预签名 URL 发送的 PUT 请求中携带 Authorization 头。该 URL 已经过签名，如果存在 Authorization 头，S3 会以 400 拒绝请求。只有 intent 请求需要使用 API 密钥进行认证。

检查进度

在提交之前验证所有必需图片已上传。使用 item=true 和 sides=true 获取服务请求以获取当前进度，包括已上传的必需和可选图片数量：

const response = await fetch(
  `https://api.legitmark.com/api/v2/sr/${srUuid}?item=true&sides=true`,
  { headers }
);
const { sr } = await response.json();

const progress = sr.sides.progress;
console.log(`已上传: ${progress.current_required}/${progress.total_required}`);
console.log(`准备提交: ${progress.met}`);

const progress = await legitmark.sr.getProgress(srUuid);

console.log(`已上传: ${progress.current_required}/${progress.total_required}`);
console.log(`准备提交: ${progress.met}`);

进度响应：

{
  "current_required": 8,
  "exempted_required": 0,
  "total_required": 8,
  "current_optional": 0,
  "total_optional": 5,
  "met": true
}

exempted_required 是 current_required 中通过豁免而非上传照片来满足的部分。当 met 为 true 时，所有必需面均已满足，服务请求可以提交。

提交认证

一旦进度要求满足，将服务请求提交给专家进行认证。API 参考： POST /api/v2/sr/{sr_uuid}/submit

const response = await fetch(
  `https://api.legitmark.com/api/v2/sr/${srUuid}/submit`,
  { method: 'POST', headers }
);
const { sr } = await response.json();
console.log(`已提交！状态: ${sr.state.primary}/${sr.state.supplement}`);

const progress = await legitmark.sr.getProgress(srUuid);

if (progress.met) {
  const { sr } = await legitmark.sr.submit(srUuid);
  console.log(`已提交！状态: ${sr.state.primary}/${sr.state.supplement}`);
}

提交后流程：

质量控制审核：图片和数据验证
认证审核：专家进行认证
结果通知：每个阶段的 Webhook 更新（参见状态）

实施模式

错误处理

使用 SDK 的内置重试功能或实施您自己的逻辑来处理临时故障：

async function createServiceRequest(itemData) {
  const maxRetries = 3;
  let lastError;

  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch('https://api.legitmark.com/api/v2/sr', {
        method: 'POST',
        headers,
        body: JSON.stringify(itemData)
      });

      if (!response.ok) {
        const error = await response.json();
        throw new Error(`服务请求失败: ${error.message}`);
      }

      return await response.json();
    } catch (error) {
      lastError = error;
      if (attempt < maxRetries) {
        await new Promise(r => setTimeout(r, 1000 * attempt)); // 指数退避
      }
    }
  }
  
  throw lastError;
}

// SDK 自动处理重试
const { sr } = await legitmark.sr.create(itemData, {
  retry: {
    maxRetries: 3,
    backoffMs: 1000,
  }
});

批量图片上传

async function uploadAllImages(srUuid, imagesToUpload) {
  const uploadPromises = imagesToUpload.map(async ({ sideUuid, imageFile }) => {
    // 获取预签名 URL
    const intentRes = await fetch(
      `https://asset.legitmark.com/intent?sr=${srUuid}&side=${sideUuid}.jpg`,
      { headers }
    );
    const { url } = await intentRes.json();

    // 上传图片
    await fetch(url, {
      method: 'PUT',
      body: imageFile,
      headers: { 'Content-Type': 'image/jpeg' }
    });

    return { sideUuid, success: true };
  });

  return Promise.all(uploadPromises);
}

最佳实践

售前优化

缓存图片要求用于常用类别
客户端验证图片在存储前
压缩图片同时保持质量标准

上传优化

使用并行上传处理多张图片
实施重试逻辑处理失败的上传
显示上传进度给用户
验证上传完成后再继续

后续步骤

工作流程实施完成后：

设置 Webhooks - Webhook 通知和状态更新处理
测试端到端工作流程与示例物品
监控认证处理和成功率

​分步实施

​实施模式

​错误处理

​批量图片上传

​最佳实践

​售前优化

​上传优化

​后续步骤

分步实施

实施模式

错误处理

批量图片上传

最佳实践

售前优化

上传优化

后续步骤