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.requirements ではなく sr.sides にあります。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 でリクエストを拒否します。API キーで認証されるのは intent リクエストのみです。

進捗を確認

提出前にすべての必須画像がアップロードされていることを確認します。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 更新（ステータスを参照）

実装パターン

エラー処理

async function createServiceRequest(itemData) {
  try {
    const response = await fetch('/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) {
    console.error('サービスリクエストの作成に失敗:', error);
    // 再試行ロジックまたはユーザー通知を実装
  }
}

進捗追跡

class AuthenticationProgress {
  constructor(srUuid) {
    this.srUuid = srUuid;
    this.steps = {
      created: false,
      requirements_fetched: false,
      images_uploaded: false,
      validated: false,
      finalized: false
    };
  }

  async checkProgress() {
    const response = await fetch(`/api/side-groups/progress?sr_id=${this.srUuid}`, {
      headers
    });
    const data = await response.json();
    
    this.steps.validated = data.progress.met;
    return this.steps;
  }
}

ベストプラクティス

販売前の最適化

頻繁に使用されるカテゴリの画像要件をキャッシュ
保存前にクライアント側で画像を検証
品質基準を維持しながら画像を圧縮
アイテムが販売されるまで画像をローカルに保存

アップロードの最適化

複数画像には並列アップロードを使用
失敗したアップロードには再試行ロジックを実装
ユーザーにアップロード進捗を表示
続行前にアップロード完了を確認

次のステップ

ワークフロー実装が完了したら：

設定 Webhooks - Webhook 通知とステータス更新処理
サンプルアイテムでエンドツーエンドのワークフローをテスト
認証処理と成功率を監視

​ステップバイステップ実装

​実装パターン

​エラー処理

​進捗追跡

​ベストプラクティス

​販売前の最適化

​アップロードの最適化

​次のステップ

ステップバイステップ実装

実装パターン

エラー処理

進捗追跡

ベストプラクティス

販売前の最適化

アップロードの最適化

次のステップ