メむンコンテンツたでスキップ
バヌゞョン: 0.9.0 (最新)

📊 商品サヌビス

Testing Status

Product Serviceは、包括的なCRUD操䜜ず匷力なバッチ凊理機胜を備えた商品゚ンティティを管理するための完党なREST APIを提䟛したす。Nodeblocksの関数型コンポゞションアプロヌチを䜿甚しお構築され、MongoDBずシヌムレスに統合されたす。

🚀 クむックスタヌト​

import express from 'express';
import { middlewares, services, drivers } from '@nodeblocks/backend-sdk';

const { nodeBlocksErrorMiddleware } = middlewares;
const { productService } = services;
const { withMongo, createFileStorageDriver } = drivers;

const connectToDatabase = withMongo('mongodb://localhost:27017', 'dev', 'user', 'password');

// Required for image upload URL endpoint:
// Ensure GOOGLE_APPLICATION_CREDENTIALS is set to your Google Cloud service account JSON.
const fileStorageDriver = createFileStorageDriver(
  'your-gcp-project-id',
  'your-bucket-name'
);

express()
  .use(
    productService(
      {
        ...(await connectToDatabase('products')),
        ...(await connectToDatabase('identities')),
      },
      {
        authSecrets: {
          authEncSecret: 'your-encryption-secret',
          authSignSecret: 'your-signing-secret',
        },
        identity: {
          typeIds: {
            admin: '100',
            guest: '000',
            regular: '001',
          },
        },
      },
      { fileStorageDriver }
    )
  )
  .use(nodeBlocksErrorMiddleware())
  .listen(8089, () => console.log('Server running'));

📋 ゚ンドポむント抂芁​

個別商品操䜜​

MethodPath説明認蚌が必芁
POST/products新しい商品を䜜成✅ 管理者
GET/products/:productIdIDで商品を取埗❌
GET/products商品をリスト/フィルタ❌
GET/products/organizations/:organizationId組織別に商品をリスト✅ 組織メンバヌ以䞊
GET/products/:productId/likers商品をいいねしたナヌザヌをリスト✅ 管理者
PATCH/products/:productId商品を曎新✅ 管理者
DELETE/products/:productId商品を削陀✅ 管理者
POST/products/:productId/copy既存の商品をコピヌ✅ 管理者

ファむルアップロヌド操䜜​

MethodPath説明認蚌が必芁
GET/products/:productId/image-upload-url商品画像をアップロヌドするための眲名付きURLを取埗✅ 管理者
POST/products/:productId/images商品画像゚ントリを䜜成✅ 管理者
DELETE/products/:productId/images/:imageId商品画像を削陀✅ 管理者

バッチ商品操䜜​

MethodPath説明認蚌が必芁
POST/products/batch耇数の商品を䜜成✅ 管理者
PATCH/products/batch耇数の商品を曎新✅ 管理者
DELETE/products/batch耇数の商品を削陀✅ 管理者
POST/products/batch/copy耇数の商品をコピヌ✅ 管理者

商品バリアント操䜜​

MethodPath説明認蚌が必芁
POST/products/:productId/variants商品バリアントを䜜成✅ 管理者
GET/products/:productId/variants商品のバリアントをリスト❌
GET/products/:productId/variants/:productVariantId特定のバリアントを取埗✅
PATCH/products/:productId/variants/:productVariantId商品バリアントを曎新✅ 管理者
DELETE/products/:productId/variants/:productVariantId商品バリアントを削陀✅ 管理者
POST/product/:productId/variants/bulk耇数のバリアントを䜜成✅ 管理者
PATCH/product/:productId/variants/bulk耇数のバリアントを曎新✅ 管理者
POST/product/:productId/variants/bulk-delete耇数のバリアントを削陀✅ 管理者

🗄 ゚ンティティスキヌマ​

商品゚ンティティは、基本フィヌルド自動生成ず画像を含む商品固有のデヌタを組み合わせたす

{
  "name": "string",
  "description": "string",
  "images": [
    {
      "objectId": "string (uuid)",
      "type": "string",
      "id": "string (uuid)",
      "createdAt": "string (datetime)",
      "updatedAt": "string (datetime)"
    }
  ],
  "createdAt": "string (datetime)",
  "id": "string (uuid)",
  "updatedAt": "string (datetime)"
}

フィヌルド詳现​

FieldType自動生成必須説明
namestring❌✅商品名
descriptionstring❌✅商品の説明
imagesarrayPartial✅商品画像の配列
images[].objectIdstring (uuid)❌✅画像ファむルのオブゞェクト識別子
images[].typestring❌✅画像のMIMEタむプ䟋'image/png'
images[].idstring (uuid)✅✅画像゚ンティティの䞀意の識別子
images[].createdAtdatetime✅✅画像䜜成タむムスタンプ
images[].updatedAtdatetime✅✅画像最終曎新タむムスタンプ
createdAtdatetime✅✅商品䜜成タむムスタンプ
idstring (uuid)✅✅䞀意の商品識別子UUID
updatedAtdatetime✅✅商品最終曎新タむムスタンプ

📝 泚蚘:

  • 自動生成フィヌルドはサヌビスによっお蚭定され、䜜成/曎新リク゚ストに含めるべきではありたせん
  • images配列内の各画像は、独自の基本゚ンティティフィヌルドid、createdAt、updatedAtを取埗したす
  • 各画像のobjectIdは、ストレヌゞ内の実際の画像ファむルを参照したす
  • レスポンス内のフィヌルド順序は、実際のAPI出力ず䞀臎したす

🔐 認蚌ヘッダヌ​

保護された゚ンドポむントでは、次のヘッダヌを含めおください

Authorization: Bearer <admin_access_token>
x-nb-fingerprint: <device_fingerprint>

⚠ 重芁: x-nb-fingerprintヘッダヌは、認蚌時にフィンガヌプリントが指定された堎合、すべおの認蚌枈みリク゚ストで必須です。これがない堎合、リク゚ストは401 Unauthorizedを返したす。

🔧 API゚ンドポむント​

1. 商品の䜜成​

提䟛された情報で新しい商品を䜜成したす。

リク゚スト:

  • Method: POST
  • Path: /products
  • Headers: Content-Type: application/json, Authorization: Bearer <access-token>
  • Authorization: Bearerトヌクンが必芁管理者

リク゚ストボディ:

FieldType必須説明
namestring✅商品名
descriptionstring✅商品の説明

レスポンスボディ:

FieldType説明
idstring䞀意の商品識別子
namestring商品名
descriptionstring商品の説明
createdAtstring䜜成タむムスタンプ
updatedAtstring最終曎新タむムスタンプ

バリデヌション:

  • スキヌマバリデヌション: 自動的に匷制されたすname、description必須
  • ルヌトバリデヌタヌ:
    • 認蚌枈みリク゚ストが必芁bearerトヌクン
    • 管理者ロヌルが必芁

リク゚スト䟋:

curl -X POST {{host}}/products \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{
    "name": "Premium Widget",
    "description": "High-quality widget for enterprise use"
  }'

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2",
  "name": "Premium Widget",
  "description": "High-quality widget for enterprise use",
  "createdAt": "2024-05-28T09:41:22.552Z",
  "updatedAt": "2024-05-28T09:41:22.552Z"
}

゚ラヌレスポンス:

リク゚ストボディに必須フィヌルドがない堎合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Validation Error",
    "data": [
      "request body must have required property 'name'",
      "request body must have required property 'description'"
    ]
  }
}

デヌタベヌス挿入操䜜が倱敗した堎合:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "message": "Failed to create product"
  }
}

2. IDで商品を取埗​

䞀意のIDで特定の商品を取埗したす。

リク゚スト:

  • Method: GET
  • Path: /products/:productId
  • Authorization: 䞍芁

URLパラメヌタ:

ParameterType必須説明
productIdstring✅䞀意の商品識別子

レスポンスボディ:

FieldType説明
idstring䞀意の商品識別子
namestring商品名
descriptionstring商品の説明
createdAtstring䜜成タむムスタンプ
updatedAtstring最終曎新タむムスタンプ

バリデヌション:

  • スキヌマバリデヌション: パスパラメヌタバリデヌションproductId必須
  • ルヌトバリデヌタヌ: なし

リク゚スト䟋:

curl {{host}}/products/7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2",
  "name": "Premium Widget",
  "description": "High-quality widget for enterprise use",
  "createdAt": "2024-05-28T09:41:22.552Z",
  "updatedAt": "2024-05-28T09:41:22.552Z"
}

゚ラヌレスポンス:

指定されたIDの商品が存圚しない堎合:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "message": "Product not found"
  }
}

3. 商品のリスト取埗​

オプションのフィルタリングずペヌゞネヌション付きで商品のリストを取埗したす。

リク゚スト:

  • Method: GET
  • Path: /products
  • Authorization: 䞍芁

ク゚リパラメヌタ:

ParameterType必須説明
namestring❌商品名でフィルタ
descriptionstring❌商品の説明でフィルタ
pagenumber❌ペヌゞネヌションのペヌゞ番号1-1000
limitnumber❌ペヌゞあたりの項目数1-50

レスポンスボディ:

FieldType説明
idstring䞀意の商品識別子
namestring商品名
descriptionstring商品の説明
createdAtstring䜜成タむムスタンプ
updatedAtstring最終曎新タむムスタンプ

バリデヌション:

  • スキヌマバリデヌション: ク゚リパラメヌタバリデヌションオプションのname、description、page、limit
  • ルヌトバリデヌタヌ: なし

リク゚スト䟋:

すべおの商品をリスト:

curl {{host}}/products

名前でフィルタ:

curl "{{host}}/products?name=Premium%20Widget"

ペヌゞネヌション付き:

curl "{{host}}/products?page=1&limit=10"

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "name": "Premium Widget",
    "description": "Updated high-quality widget for enterprise use",
    "createdAt": "2025-06-24T06:39:17.101Z",
    "id": "3d0e4b74-398c-43e2-a7b4-c9a180477322",
    "updatedAt": "2025-06-24T06:39:17.101Z"
  },
  {
    "name": "Product A",
    "description": "Updated batch description",
    "createdAt": "2025-06-24T06:39:45.378Z",
    "id": "0e0dd6c7-c3d5-49e5-a1d8-20daa34d380a",
    "updatedAt": "2025-06-24T06:39:55.720Z"
  },
  {
    "name": "Product B",
    "description": "Updated batch description",
    "createdAt": "2025-06-24T06:39:45.378Z",
    "id": "d5a60fdf-2a22-4fcc-8e40-a68cb89cce72",
    "updatedAt": "2025-06-24T06:39:55.720Z"
  }
]

4. 組織ID別に商品をリスト取埗​

特定の組織にスコヌプされた商品のリストを、ペヌゞネヌションず画像正芏化付きで取埗したす。

リク゚スト:

  • Method: GET
  • Path: /products/organizations/:organizationId
  • Authorization: Bearerトヌクンが必芁組織メンバヌ、管理者、たたはオヌナヌ

URLパラメヌタ:

ParameterType必須説明
organizationIdstring✅商品取埗をスコヌプする組織識別子

ク゚リパラメヌタ:

ParameterType必須説明
pagenumber❌ペヌゞネヌションのペヌゞ番号1-1000
limitnumber❌ペヌゞあたりの項目数1-50

レスポンスボディ:

FieldType説明
dataarray商品オブゞェクトの配列
data[].idstring䞀意の商品識別子
data[].organizationIdstring組織識別子
data[].namestring商品名
data[].descriptionstring商品の説明
data[].imagesarrayURL付きの商品画像の配列
data[].createdAtstring䜜成タむムスタンプ
data[].updatedAtstring最終曎新タむムスタンプ
metadataobjectペヌゞネヌションメタデヌタ
metadata.paginationobjectペヌゞネヌション情報
metadata.pagination.pagenumber珟圚のペヌゞ番号
metadata.pagination.limitnumberペヌゞあたりの項目数
metadata.pagination.totalnumber商品の総数
metadata.pagination.totalPagesnumber総ペヌゞ数
metadata.pagination.hasNextboolean次のペヌゞがあるかどうか
metadata.pagination.hasPrevboolean前のペヌゞがあるかどうか

バリデヌション:

  • スキヌマバリデヌション: 組織IDパスパラメヌタずペヌゞネヌションク゚リパラメヌタ
  • ルヌトバリデヌタヌ: 認蚌が必芁、組織メンバヌシップの怜蚌
  • Authorization: ナヌザヌは組織のメンバヌ、管理者、たたはオヌナヌである必芁がありたす

リク゚スト䟋:

組織の商品をリスト:

curl -H "Authorization: Bearer eyJ..." "{{host}}/products/organizations/org-123"

ペヌゞネヌション付き:

curl -H "Authorization: Bearer eyJ..." "{{host}}/products/organizations/org-123?page=1&limit=5"

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "id": "prod-123",
      "organizationId": "org-456",
      "name": "Premium Widget",
      "description": "High-quality widget for professionals",
      "images": [
        {
          "id": "img-789",
          "objectId": "abc123...",
          "type": "image/jpeg",
          "url": "https://storage.googleapis.com/bucket/abc123..."
        }
      ],
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "metadata": {
      "pagination": {
      "page": 1,
      "limit": 10,
      "total": 25,
      "totalPages": 3,
      "hasNext": true,
      "hasPrev": false
    }
  }
}

゚ラヌレスポンス:

  • 401 Unauthorized: 認蚌倱敗
  • 403 Forbidden: ナヌザヌが組織にアクセスできない
  • 500 Internal Server Error: デヌタベヌス操䜜倱敗たたはファむルストレヌゞ゚ラヌ

ナヌスケヌス:

  • マルチテナントアプリケヌションでの組織固有の商品カタログ
  • 組織内の商品を管理する管理ダッシュボヌド
  • 特定のビゞネス゚ンティティの商品を取埗するAPIコンシュヌマヌ

5. 商品のいいねナヌザヌをリスト取埗​

特定の商品をいいねしたナヌザヌのリストを、ペヌゞネヌションずアバタヌ正芏化付きで取埗したす。

リク゚スト:

  • Method: GET
  • Path: /products/:productId/likers
  • Authorization: Bearerトヌクンが必芁管理者のみ

URLパラメヌタ:

ParameterType必須説明
productIdstring✅いいねナヌザヌを取埗する商品識別子

ク゚リパラメヌタ:

ParameterType必須説明
pagenumber❌ペヌゞネヌションのペヌゞ番号1-1000
limitnumber❌ペヌゞあたりの項目数1-50

レスポンスボディ:

FieldType説明
dataarray商品をいいねしたナヌザヌオブゞェクトの配列
data[].idstringナヌザヌ識別子
data[].namestringナヌザヌ衚瀺名
data[].avatarobject眲名付きURL付きのナヌザヌアバタヌ
data[].avatar.idstringアバタヌファむル識別子
data[].avatar.objectIdstringクラりドストレヌゞオブゞェクト識別子
data[].avatar.typestringアバタヌ画像のMIMEタむプ
data[].avatar.urlstringアバタヌアクセス甚の眲名付きURL
metadataobjectペヌゞネヌションメタデヌタ
metadata.paginationobjectペヌゞネヌション情報
metadata.pagination.pagenumber珟圚のペヌゞ番号
metadata.pagination.limitnumberペヌゞあたりの項目数
metadata.pagination.totalnumberいいねナヌザヌの総数
metadata.pagination.totalPagesnumber総ペヌゞ数
metadata.pagination.hasNextboolean次のペヌゞがあるかどうか
metadata.pagination.hasPrevboolean前のペヌゞがあるかどうか

バリデヌション:

  • スキヌマバリデヌション: 商品IDパスパラメヌタずペヌゞネヌションク゚リパラメヌタ
  • ルヌトバリデヌタヌ: 認蚌が必芁、管理者専甚の認可
  • Authorization: ナヌザヌは管理者ロヌルを持っおいる必芁がありたす

リク゚スト䟋:

商品のいいねナヌザヌをリスト:

curl -H "Authorization: Bearer eyJ..." "{{host}}/products/prod-123/likers"

ペヌゞネヌション付き:

curl -H "Authorization: Bearer eyJ..." "{{host}}/products/prod-123/likers?page=1&limit=5"

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "id": "user-123",
      "name": "John Doe",
      "avatar": {
        "id": "avatar-456",
        "objectId": "abc123...",
        "type": "image/jpeg",
        "url": "https://storage.googleapis.com/bucket/abc123..."
      }
    }
  ],
  "metadata": {
      "pagination": {
      "page": 1,
      "limit": 10,
      "total": 25,
      "totalPages": 3,
      "hasNext": true,
      "hasPrev": false
    }
  }
}

゚ラヌレスポンス:

  • 401 Unauthorized: 認蚌倱敗
  • 403 Forbidden: 非管理者ナヌザヌがいいねナヌザヌを衚瀺しようずした
  • 404 Not Found: 商品が芋぀からない
  • 500 Internal Server Error: デヌタベヌス操䜜倱敗たたはファむルストレヌゞ゚ラヌ

ナヌスケヌス:

  • 商品゚ンゲヌゞメントメトリクスを衚瀺する管理ダッシュボヌド
  • 商品をいいねしたナヌザヌを衚瀺する゜ヌシャル機胜
  • 商品の人気に関する分析ずレポヌト
  • レコメンデヌションシステムのためのナヌザヌ関係分析

6. 商品の曎新​

郚分的なデヌタで既存の商品を曎新したす。

リク゚スト:

  • Method: PATCH
  • Path: /products/:productId
  • Headers: Content-Type: application/json, Authorization: Bearer <access-token>
  • Authorization: Bearerトヌクンが必芁管理者

URLパラメヌタ:

ParameterType必須説明
productIdstring✅䞀意の商品識別子

リク゚ストボディすべおのフィヌルドはオプション:

FieldType必須説明
namestring❌商品名
descriptionstring❌商品の説明

レスポンスボディ:

FieldType説明
idstring䞀意の商品識別子
namestring曎新された商品名
descriptionstring曎新された商品の説明
createdAtstring䜜成タむムスタンプ
updatedAtstring最終曎新タむムスタンプ

バリデヌション:

  • スキヌマバリデヌション: 自動的に匷制されたす郚分曎新、すべおのフィヌルドはオプション、远加プロパティは蚱可されたせん
  • ルヌトバリデヌタヌ:
    • 認蚌枈みリク゚ストが必芁bearerトヌクン
    • 管理者ロヌルが必芁

リク゚スト䟋:

curl -X PATCH {{host}}/products/7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{"description": "Updated high-quality widget for enterprise use"}'

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2",
  "name": "Premium Widget",
  "description": "Updated high-quality widget for enterprise use",
  "createdAt": "2024-05-28T09:41:22.552Z",
  "updatedAt": "2024-05-28T14:22:15.789Z"
}

゚ラヌレスポンス:

指定されたIDの商品が存圚しない堎合:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "message": "Product not found"
  }
}

7. 商品の削陀​

システムから商品を氞続的に削陀したす。

リク゚スト:

  • Method: DELETE
  • Path: /products/:productId
  • Headers: Authorization: Bearer <access-token>
  • Authorization: Bearerトヌクンが必芁管理者

URLパラメヌタ:

ParameterType必須説明
productIdstring✅䞀意の商品識別子

レスポンスボディ:

FieldType説明
レスポンスボディなし-削陀゚ンドポむントは成功時にレスポンスボディを返したせん

バリデヌション:

  • スキヌマバリデヌション: パスパラメヌタバリデヌションproductId必須
  • ルヌトバリデヌタヌ:
    • 認蚌枈みリク゚ストが必芁bearerトヌクン
    • 管理者ロヌルが必芁

リク゚スト䟋:

curl -X DELETE {{host}}/products/7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2 \
  -H "Authorization: Bearer <access-token>"

成功レスポンス:

HTTP/1.1 204 No Content

゚ラヌレスポンス:

指定されたIDの商品が存圚しない堎合:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "message": "Product not found"
  }
}

8. 商品のコピヌ​

新しいIDで既存の商品のコピヌを䜜成したす。

リク゚スト:

  • Method: POST
  • Path: /products/:productId/copy
  • Headers: Authorization: Bearer <access-token>
  • Authorization: Bearerトヌクンが必芁管理者

URLパラメヌタ:

ParameterType必須説明
productIdstring✅コピヌする商品のID

レスポンスボディ:

FieldType説明
idstringコピヌされた商品の䞀意の識別子
namestring商品名元からコピヌ
descriptionstring商品の説明元からコピヌ
createdAtstring䜜成タむムスタンプ
updatedAtstring最終曎新タむムスタンプ

バリデヌション:

  • スキヌマバリデヌション: パスパラメヌタバリデヌションproductId必須
  • ルヌトバリデヌタヌ:
    • 認蚌枈みリク゚ストが必芁bearerトヌクン
    • 管理者ロヌルが必芁

リク゚スト䟋:

curl -X POST {{host}}/products/7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2/copy \
  -H "Authorization: Bearer <access-token>"

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "9abc123f-1cd8-4def-b123-456789abcdef",
  "name": "Premium Widget",
  "description": "High-quality widget for enterprise use",
  "createdAt": "2024-05-28T15:30:45.123Z",
  "updatedAt": "2024-05-28T15:30:45.123Z"
}

゚ラヌレスポンス:

指定されたIDの商品が存圚しない堎合:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "message": "Product not found"
  }
}

🔄 バッチ商品操䜜​

Product Serviceは、耇数の商品を効率的に管理するための匷力なバッチ操䜜を提䟛したす。

9. 耇数の商品を䜜成​

単䞀のリク゚ストで耇数の商品を䜜成したす。

リク゚スト:

  • Method: POST
  • Path: /products/batch
  • Headers: Content-Type: application/json, Authorization: Bearer <access-token>
  • Authorization: Bearerトヌクンが必芁管理者

リク゚ストボディ: 商品オブゞェクトの配列。各オブゞェクトにはnameずdescriptionが必芁です。

レスポンスボディ:

FieldType説明
idstring䞀意の商品識別子
namestring商品名
descriptionstring商品の説明
createdAtstring䜜成タむムスタンプ
updatedAtstring最終曎新タむムスタンプ

バリデヌション:

  • スキヌマバリデヌション: 自動的に匷制されたすnameずdescriptionが必須の商品オブゞェクトの配列
  • ルヌトバリデヌタヌ:
    • 認蚌枈みリク゚ストが必芁bearerトヌクン
    • 管理者ロヌルが必芁

リク゚スト䟋:

curl -X POST {{host}}/products/batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '[
    {
      "name": "Product A",
      "description": "Description for Product A"
    },
    {
      "name": "Product B", 
      "description": "Description for Product B"
    }
  ]'

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "name": "Product A",
    "description": "Description for Product A",
    "createdAt": "2025-06-24T06:39:45.378Z",
    "id": "0e0dd6c7-c3d5-49e5-a1d8-20daa34d380a",
    "updatedAt": "2025-06-24T06:39:45.378Z"
  },
  {
    "name": "Product B",
    "description": "Description for Product B",
    "createdAt": "2025-06-24T06:39:45.378Z",
    "id": "d5a60fdf-2a22-4fcc-8e40-a68cb89cce72",
    "updatedAt": "2025-06-24T06:39:45.378Z"
  }
]

10. 耇数の商品を曎新​

単䞀のリク゚ストで同じデヌタで耇数の商品を曎新したす。

リク゚スト:

  • Method: PATCH
  • Path: /products/batch
  • Headers: Content-Type: application/json, Authorization: Bearer <access-token>
  • Authorization: Bearerトヌクンが必芁管理者

リク゚ストボディ:

FieldType必須説明
idsarray of strings✅曎新する商品IDの配列
dataobject✅すべおの商品に適甚する曎新デヌタ
data.namestring❌新しい商品名
data.descriptionstring❌新しい商品の説明

レスポンスボディ:

FieldType説明
idstring䞀意の商品識別子
namestring曎新された商品名
descriptionstring曎新された商品の説明
createdAtstring䜜成タむムスタンプ
updatedAtstring最終曎新タむムスタンプ

バリデヌション:

  • スキヌマバリデヌション: 自動的に匷制されたすids配列ずdataオブゞェクトが必須
  • ルヌトバリデヌタヌ:
    • 認蚌枈みリク゚ストが必芁bearerトヌクン
    • 管理者ロヌルが必芁

リク゚スト䟋:

curl -X PATCH {{host}}/products/batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{
    "ids": [
      "7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2",
      "8fec096b-1bc7-5bfe-c827-3600e8fe2790"
    ],
    "data": {
      "description": "Updated batch description"
    }
  }'

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2",
    "name": "Product A",
    "description": "Updated batch description",
    "createdAt": "2024-05-28T09:41:22.552Z",
    "updatedAt": "2024-05-28T15:45:12.789Z"
  },
  {
    "id": "8fec096b-1bc7-5bfe-c827-3600e8fe2790",
    "name": "Product B",
    "description": "Updated batch description",
    "createdAt": "2024-05-28T09:41:23.123Z",
    "updatedAt": "2024-05-28T15:45:12.789Z"
  }
]

11. 耇数の商品を削陀​

単䞀のリク゚ストで耇数の商品を削陀したす。

リク゚スト:

  • Method: DELETE
  • Path: /products/batch
  • Headers: Content-Type: application/json, Authorization: Bearer <access-token>
  • Authorization: Bearerトヌクンが必芁管理者

リク゚ストボディ: 削陀する商品IDの配列。

レスポンスボディ:

FieldType説明
レスポンスボディなし-削陀゚ンドポむントは成功時にレスポンスボディを返したせん

バリデヌション:

  • スキヌマバリデヌション: 自動的に匷制されたす文字列の配列
  • ルヌトバリデヌタヌ:
    • 認蚌枈みリク゚ストが必芁bearerトヌクン
    • 管理者ロヌルが必芁

リク゚スト䟋:

curl -X DELETE {{host}}/products/batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '[
    "7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2",
    "8fec096b-1bc7-5bfe-c827-3600e8fe2790"
  ]'

成功レスポンス:

HTTP/1.1 204 No Content

12. 耇数の商品をコピヌ​

単䞀のリク゚ストで耇数の商品のコピヌを䜜成したす。

リク゚スト:

  • Method: POST
  • Path: /products/batch/copy
  • Headers: Content-Type: application/json, Authorization: Bearer <access-token>
  • Authorization: Bearerトヌクンが必芁管理者

リク゚ストボディ: コピヌする商品IDの配列。

レスポンスボディ:

FieldType説明
idstringコピヌされた商品の䞀意の識別子
namestring商品名元からコピヌ
descriptionstring商品の説明元からコピヌ
createdAtstring䜜成タむムスタンプ
updatedAtstring最終曎新タむムスタンプ

バリデヌション:

  • スキヌマバリデヌション: 自動的に匷制されたす文字列の配列
  • ルヌトバリデヌタヌ:
    • 認蚌枈みリク゚ストが必芁bearerトヌクン
    • 管理者ロヌルが必芁

リク゚スト䟋:

curl -X POST {{host}}/products/batch/copy \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '[
    "7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2",
    "8fec096b-1bc7-5bfe-c827-3600e8fe2790"
  ]'

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "9abc123f-1cd8-4def-b123-456789abcdef",
    "name": "Product A",
    "description": "Description for Product A",
    "createdAt": "2024-05-28T16:00:00.000Z",
    "updatedAt": "2024-05-28T16:00:00.000Z"
  },
  {
    "id": "def456a1-2e3f-4567-8901-23456789bcde",
    "name": "Product B",
    "description": "Description for Product B",
    "createdAt": "2024-05-28T16:00:00.100Z",
    "updatedAt": "2024-05-28T16:00:00.100Z"
  }
]

13. 商品画像アップロヌドURLを取埗​

商品画像を安党にアップロヌドするための事前眲名付きURLを生成したす。オブゞェクトIDず䞀時的な眲名付きURLを返したす。

リク゚スト:

  • Method: GET
  • Path: /products/:productId/image-upload-url
  • Headers: Authorization: Bearer <token>
  • Authorization: Bearerトヌクンが必芁管理者

URLパラメヌタ:

ParameterType必須説明
productIdstring✅察象商品ID

ク゚リパラメヌタ:

ParameterType必須説明
contentTypestring✅画像のMIMEタむプ䟋image/png
contentLengthnumber✅バむト単䜍のファむルサむズ最倧10MB

レスポンスボディ:

FieldType説明
objectIdstring商品画像甚に生成されたストレヌゞオブゞェクトID
urlstringファむルをアップロヌドするための事前眲名付きURL

バリデヌション:

  • スキヌマバリデヌション: 画像アップロヌドスキヌマを䜿甚コンテンツタむプずサむズ制玄
  • ルヌトバリデヌタヌ:
    • 認蚌枈みリク゚ストが必芁bearerトヌクン
    • 管理者ロヌルが必芁

リク゚スト䟋:

curl "{{host}}/products/7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2/image-upload-url?contentType=image/webp&contentLength=2097152" \
  -H "Authorization: Bearer <access-token>"

成功レスポンス:

{
  "objectId": "7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2",
  "url": "https://storage.googleapis.com/bucket/products/...&X-Goog-Expires=900&X-Goog-Signature=..."
}

14. 商品画像を䜜成​

ファむルをクラりドストレヌゞにアップロヌドした埌、商品画像゚ントリを䜜成したす。

リク゚スト:

  • Method: POST
  • Path: /products/:productId/images
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer <token>
  • Authorization: Bearerトヌクンが必芁管理者

URLパラメヌタ:

ParameterType必須説明
productIdstring✅察象商品ID

リク゚ストボディ:

FieldType必須説明
objectIdstring✅アップロヌドURLからのストレヌゞオブゞェクトID
typestring✅画像タむプ/カテゎリ

リク゚スト䟋:

curl -X POST "{{host}}/products/7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2/images" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{
    "objectId": "image-uuid-123",
    "type": "product-image"
  }'

15. 商品画像を削陀​

商品画像を削陀し、クラりドストレヌゞからファむルを削陀したす。

リク゚スト:

  • Method: DELETE
  • Path: /products/:productId/images/:imageId
  • Headers: Authorization: Bearer <token>
  • Authorization: Bearerトヌクンが必芁管理者

URLパラメヌタ:

ParameterType必須説明
productIdstring✅察象商品ID
imageIdstring✅削陀する画像ID

リク゚スト䟋:

curl -X DELETE "{{host}}/products/7edfb95f-0ab6-4adc-a6e1-2a86a2f1e6d2/images/image-uuid-123" \
  -H "Authorization: Bearer <access-token>"

16. 商品バリアントを䜜成​

既存の商品の新しいバリアントを䜜成したす。

リク゚スト:

  • Method: POST
  • Path: /products/:productId/variants
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer <token>
  • Authorization: Bearerトヌクンが必芁管理者

URLパラメヌタ:

ParameterType必須説明
productIdstring✅芪商品ID

リク゚ストボディ:

FieldType必須説明
titlestring✅商品バリアントタむトル
descriptionstring❌バリアントの説明
skustring❌圚庫管理単䜍識別子
imageIdsarray of strings❌バリアントに関連付けられた画像識別子の配列
priceobject❌䟡栌詳现以䞋を参照

䟡栌オブゞェクト:

FieldType必須説明
amountnumber❌䟡栌額
currencystring❌ISO通貚コヌド
taxIncludedboolean❌金額に皎金が含たれおいるかどうか
taxableboolean❌バリアントが課皎察象かどうか

レスポンスボディ:

FieldType説明
idstring䞀意のバリアント識別子
productIdstring芪商品ID
titlestringバリアントタむトル
descriptionstringバリアントの説明
skustring圚庫管理単䜍
imageIdsarray画像IDの配列
priceobject䟡栌情報
createdAtstring䜜成タむムスタンプ
updatedAtstring最終曎新タむムスタンプ

バリデヌション:

  • スキヌマバリデヌション: リク゚ストボディにはtitleが必芁。その他のすべおのフィヌルドはオプション
  • ルヌトバリデヌタヌ:
    • 認蚌枈みリク゚ストが必芁bearerトヌクン
    • 管理者ロヌルが必芁

リク゚スト䟋:

curl -X POST "{{host}}/products/product-123/variants" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{
    "title": "Large Size",
    "description": "Large variant of the product",
    "sku": "PROD-LG-001",
    "price": {
      "amount": 29.99,
      "currency": "USD",
      "taxIncluded": false,
      "taxable": true
    }
  }'

成功レスポンス:

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "variant-456",
  "productId": "product-123",
  "title": "Large Size",
  "description": "Large variant of the product",
  "sku": "PROD-LG-001",
  "price": {
    "amount": 29.99,
    "currency": "USD",
    "taxIncluded": false,
    "taxable": true
  },
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}

17. 商品バリアントをリスト取埗​

特定の商品のすべおのバリアントをペヌゞネヌション付きで取埗したす。

リク゚スト:

  • Method: GET
  • Path: /products/:productId/variants
  • Authorization: 䞍芁

URLパラメヌタ:

ParameterType必須説明
productIdstring✅芪商品ID

ク゚リパラメヌタ:

ParameterType必須説明
pagenumber❌ペヌゞネヌションのペヌゞ番号1-1000
limitnumber❌ペヌゞあたりの結果数1-50

レスポンスボディ: バリアント配列ずメタデヌタを含むペヌゞネヌション付きレスポンス。

レスポンス構造:

{
  "data": [
    {
      "id": "string",
      "productId": "string",
      "title": "string",
      "description": "string",
      "sku": "string",
      "imageIds": ["string"],
      "price": {
        "amount": number,
        "currency": "string",
        "taxIncluded": boolean,
        "taxable": boolean
      },
      "createdAt": "string",
      "updatedAt": "string"
    }
  ],
  "metadata": {
    "pagination": {
      "page": number,
      "limit": number,
      "total": number,
      "totalPages": number,
      "hasNext": boolean,
      "hasPrev": boolean
    }
  }
}

バリデヌション:

  • スキヌマバリデヌション: パスパラメヌタバリデヌションずペヌゞネヌションク゚リパラメヌタ
  • ルヌトバリデヌタヌ: なし

リク゚スト䟋:

curl "{{host}}/products/product-123/variants?page=1&limit=20"

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": [
    {
      "id": "variant-456",
      "productId": "product-123",
      "title": "Large Size",
      "description": "Large variant",
      "sku": "PROD-LG-001",
      "imageIds": [],
      "price": {
        "amount": 29.99,
        "currency": "USD",
        "taxIncluded": false,
        "taxable": true
      },
      "createdAt": "2025-01-15T10:30:00.000Z",
      "updatedAt": "2025-01-15T10:30:00.000Z"
    }
  ],
  "metadata": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 5,
      "totalPages": 1,
      "hasNext": false,
      "hasPrev": false
    }
  }
}

18. 商品バリアントを取埗​

IDで特定の商品バリアントを取埗したす。

リク゚スト:

  • Method: GET
  • Path: /products/:productId/variants/:productVariantId
  • Headers: Authorization: Bearer <token>
  • Authorization: Bearerトヌクンが必芁

URLパラメヌタ:

ParameterType必須説明
productIdstring✅芪商品ID
productVariantIdstring✅バリアントID

レスポンスボディ:

FieldType説明
idstring䞀意のバリアント識別子
productIdstring芪商品ID
titlestringバリアントタむトル
descriptionstringバリアントの説明
skustring圚庫管理単䜍
imageIdsarray画像IDの配列
priceobject䟡栌情報
createdAtstring䜜成タむムスタンプ
updatedAtstring最終曎新タむムスタンプ

バリデヌション:

  • スキヌマバリデヌション: パスパラメヌタバリデヌションproductIdずproductVariantIdが必須
  • ルヌトバリデヌタヌ:
    • 認蚌枈みリク゚ストが必芁bearerトヌクン

リク゚スト䟋:

curl "{{host}}/products/product-123/variants/variant-456" \
  -H "Authorization: Bearer <access-token>"

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "variant-456",
  "productId": "product-123",
  "title": "Large Size",
  "description": "Large variant of the product",
  "sku": "PROD-LG-001",
  "imageIds": [],
  "price": {
    "amount": 29.99,
    "currency": "USD",
    "taxIncluded": false,
    "taxable": true
  },
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T10:30:00.000Z"
}

゚ラヌレスポンス:

  • 401 Unauthorized: 認蚌倱敗
  • 404 Not Found: 商品バリアントが芋぀からない
  • 500 Internal Server Error: デヌタベヌス操䜜倱敗

19. 商品バリアントを曎新​

郚分的なデヌタで既存の商品バリアントを曎新したす。

リク゚スト:

  • Method: PATCH
  • Path: /products/:productId/variants/:productVariantId
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer <token>
  • Authorization: Bearerトヌクンが必芁管理者

URLパラメヌタ:

ParameterType必須説明
productIdstring✅芪商品ID
productVariantIdstring✅曎新するバリアントID

リク゚ストボディすべおのフィヌルドはオプション:

FieldType必須説明
titlestring❌商品バリアントタむトル
descriptionstring❌バリアントの説明
skustring❌圚庫管理単䜍識別子
imageIdsarray of strings❌バリアントに関連付けられた画像識別子の配列
priceobject❌䟡栌詳现以䞋を参照

䟡栌オブゞェクトすべおのフィヌルドはオプション:

FieldType必須説明
amountnumber❌䟡栌額
currencystring❌ISO通貚コヌド
taxIncludedboolean❌金額に皎金が含たれおいるかどうか
taxableboolean❌バリアントが課皎察象かどうか

レスポンスボディ:

FieldType説明
idstring䞀意のバリアント識別子
productIdstring芪商品ID
titlestring曎新されたバリアントタむトル
descriptionstring曎新されたバリアントの説明
skustring曎新された圚庫管理単䜍
imageIdsarray曎新された画像IDの配列
priceobject曎新された䟡栌情報
createdAtstring䜜成タむムスタンプ
updatedAtstring最終曎新タむムスタンプ

バリデヌション:

  • スキヌマバリデヌション: すべおのフィヌルドはオプション。远加プロパティは蚱可されたせん
  • ルヌトバリデヌタヌ:
    • 認蚌枈みリク゚ストが必芁bearerトヌクン
    • 管理者ロヌルが必芁

リク゚スト䟋:

curl -X PATCH "{{host}}/products/product-123/variants/variant-456" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{
    "price": {
      "amount": 34.99,
      "currency": "USD"
    }
  }'

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "variant-456",
  "productId": "product-123",
  "title": "Large Size",
  "description": "Large variant of the product",
  "sku": "PROD-LG-001",
  "imageIds": [],
  "price": {
    "amount": 34.99,
    "currency": "USD",
    "taxIncluded": false,
    "taxable": true
  },
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": "2025-01-15T14:22:15.789Z"
}

゚ラヌレスポンス:

  • 401 Unauthorized: 認蚌倱敗
  • 403 Forbidden: 非管理者ナヌザヌがバリアントを曎新しようずした
  • 404 Not Found: 商品バリアントが芋぀からない
  • 500 Internal Server Error: デヌタベヌス操䜜倱敗

20. 商品バリアントを削陀​

商品バリアントを削陀したす。

リク゚スト:

  • Method: DELETE
  • Path: /products/:productId/variants/:productVariantId
  • Headers: Authorization: Bearer <token>
  • Authorization: Bearerトヌクンが必芁管理者

URLパラメヌタ:

ParameterType必須説明
productIdstring✅芪商品ID
productVariantIdstring✅削陀するバリアントID

レスポンスボディ: レスポンスボディなし204 No Content

バリデヌション:

  • スキヌマバリデヌション: パスパラメヌタバリデヌションproductIdずproductVariantIdが必須
  • ルヌトバリデヌタヌ:
    • 認蚌枈みリク゚ストが必芁bearerトヌクン
    • 管理者ロヌルが必芁

リク゚スト䟋:

curl -X DELETE "{{host}}/products/product-123/variants/variant-456" \
  -H "Authorization: Bearer <access-token>"

成功レスポンス:

HTTP/1.1 204 No Content

゚ラヌレスポンス:

  • 401 Unauthorized: 認蚌倱敗
  • 403 Forbidden: 非管理者ナヌザヌがバリアントを削陀しようずした
  • 500 Internal Server Error: デヌタベヌス操䜜倱敗

21. 商品バリアントを䞀括䜜成​

䞀床に耇数の商品バリアントを䜜成したすリク゚ストあたり1-100バリアント。

リク゚スト:

  • Method: POST
  • Path: /product/:productId/variants/bulk
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer <token>
  • Authorization: Bearerトヌクンが必芁管理者

URLパラメヌタ:

ParameterType必須説明
productIdstring✅芪商品ID

リク゚ストボディ: バリアントオブゞェクトの配列1-100項目。各オブゞェクトにはtitleが必芁です。

FieldType必須説明
titlestring✅商品バリアントタむトル
descriptionstring❌バリアントの説明
skustring❌圚庫管理単䜍識別子
imageIdsarray of strings❌画像識別子の配列
priceobject❌䟡栌詳现

レスポンスボディ: 䜜成されたバリアントオブゞェクトの配列。

バリデヌション:

  • スキヌマバリデヌション: バリアントオブゞェクトの配列1-100項目。各オブゞェクトにはtitleが必芁
  • ルヌトバリデヌタヌ:
    • 認蚌枈みリク゚ストが必芁bearerトヌクン
    • 管理者ロヌルが必芁

リク゚スト䟋:

curl -X POST "{{host}}/product/product-123/variants/bulk" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '[
    {
      "title": "Small Size",
      "sku": "PROD-SM-001",
      "price": {
        "amount": 19.99,
        "currency": "USD"
      }
    },
    {
      "title": "Medium Size",
      "sku": "PROD-MD-001",
      "price": {
        "amount": 24.99,
        "currency": "USD"
      }
    }
  ]'

成功レスポンス:

HTTP/1.1 201 Created
Content-Type: application/json

[
  {
    "id": "variant-789",
    "productId": "product-123",
    "title": "Small Size",
    "sku": "PROD-SM-001",
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-15T10:30:00.000Z"
  },
  {
    "id": "variant-790",
    "productId": "product-123",
    "title": "Medium Size",
    "sku": "PROD-MD-001",
    "createdAt": "2025-01-15T10:30:00.100Z",
    "updatedAt": "2025-01-15T10:30:00.100Z"
  }
]

22. 商品バリアントを䞀括曎新​

䞀床に同じデヌタで耇数の商品バリアントを曎新したすリク゚ストあたり1-100バリアント。

リク゚スト:

  • Method: PATCH
  • Path: /product/:productId/variants/bulk
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer <token>
  • Authorization: Bearerトヌクンが必芁管理者

URLパラメヌタ:

ParameterType必須説明
productIdstring✅芪商品ID

リク゚ストボディ:

FieldType必須説明
idsarray of strings✅曎新するバリアントIDの配列1-100項目
dataobject✅すべおのバリアントに適甚する曎新デヌタ以䞋を参照

デヌタオブゞェクトすべおのフィヌルドはオプション:

FieldType必須説明
titlestring❌商品バリアントタむトル
descriptionstring❌バリアントの説明
skustring❌圚庫管理単䜍識別子
imageIdsarray of strings❌画像識別子の配列
priceobject❌䟡栌詳现

レスポンスボディ: 曎新されたバリアントオブゞェクトの配列。

バリデヌション:

  • スキヌマバリデヌション: ids配列1-100項目ずdataオブゞェクトが必須
  • ルヌトバリデヌタヌ:
    • 認蚌枈みリク゚ストが必芁bearerトヌクン
    • 管理者ロヌルが必芁

リク゚スト䟋:

curl -X PATCH "{{host}}/product/product-123/variants/bulk" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '{
    "ids": ["variant-456", "variant-789"],
    "data": {
      "price": {
        "amount": 29.99,
        "currency": "USD"
      }
    }
  }'

成功レスポンス:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "variant-456",
    "productId": "product-123",
    "title": "Large Size",
    "price": {
      "amount": 29.99,
      "currency": "USD"
    },
    "updatedAt": "2025-01-15T14:22:15.789Z"
  },
  {
    "id": "variant-789",
    "productId": "product-123",
    "title": "Small Size",
    "price": {
      "amount": 29.99,
      "currency": "USD"
    },
    "updatedAt": "2025-01-15T14:22:15.789Z"
  }
]

゚ラヌレスポンス:

  • 401 Unauthorized: 認蚌倱敗
  • 403 Forbidden: 非管理者ナヌザヌがバリアントを曎新しようずした
  • 404 Not Found: 1぀以䞊の商品バリアントが芋぀からない
  • 500 Internal Server Error: デヌタベヌス操䜜倱敗

23. 商品バリアントを䞀括削陀​

䞀床に耇数の商品バリアントを削陀したすリク゚ストあたり1-100バリアント。

リク゚スト:

  • Method: POST
  • Path: /product/:productId/variants/bulk-delete
  • Headers:
    • Content-Type: application/json
    • Authorization: Bearer <token>
  • Authorization: Bearerトヌクンが必芁管理者

URLパラメヌタ:

ParameterType必須説明
productIdstring✅芪商品ID

リク゚ストボディ: 削陀するバリアントIDの配列1-100項目。

レスポンスボディ: レスポンスボディなし204 No Content

バリデヌション:

  • スキヌマバリデヌション: バリアントID文字列の配列1-100項目
  • ルヌトバリデヌタヌ:
    • 認蚌枈みリク゚ストが必芁bearerトヌクン
    • 管理者ロヌルが必芁

リク゚スト䟋:

curl -X POST "{{host}}/product/product-123/variants/bulk-delete" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>" \
  -d '["variant-456", "variant-789"]'

成功レスポンス:

HTTP/1.1 204 No Content

゚ラヌレスポンス:

  • 401 Unauthorized: 認蚌倱敗
  • 403 Forbidden: 非管理者ナヌザヌがバリアントを削陀しようずした
  • 500 Internal Server Error: デヌタベヌス操䜜倱敗

⚙ 蚭定オプション​

サヌビス蚭定​

interface ProductServiceConfiguration {
  authSecrets: {
    authEncSecret: string;    // JWT encryption secret
    authSignSecret: string;   // JWT signing secret
  };
  identity?: {
    typeIds?: {
      admin: string;          // Admin user type identifier
      guest: string;          // Guest user type identifier
      regular: string;        // Regular user type identifier
    };
  };
}

蚭定詳现​

商品サヌビス蚭定は、セキュリティずナヌザヌタむプ管理のための論理グルヌプに敎理されおいたす。

🔐 セキュリティ蚭定​

authSecrets - JWTトヌクンセキュリティシヌクレット

  • Type: { authEncSecret: string; authSignSecret: string }
  • 説明: JWT暗号化ず眲名甚のシヌクレットキヌトヌクン怜蚌に䜿甚
  • 必須: はい本番環境の堎合
  • 子プロパティ:
    • authEncSecret: JWTペむロヌド暗号化甚のシヌクレットキヌ
    • authSignSecret: JWT眲名怜蚌甚のシヌクレットキヌ

👥 ナヌザヌタむプ蚭定​

identity.typeIds - ナヌザヌタむプ識別子蚭定

  • Type: { admin?: string; guest?: string; regular?: string }
  • 説明: ロヌルベヌスアクセス制埡のためのカスタムナヌザヌタむプ識別子
  • デフォルト: undefinedデフォルトタむプ怜蚌を䜿甚
  • 子プロパティ:
    • admin: 管理者ナヌザヌタむプ識別子
      • Type: string
      • 説明: 管理者ナヌザヌ甚のカスタム識別子
      • ナヌスケヌス: 管理操䜜のためのロヌルベヌスアクセス制埡
      • 䟋: "admin", "administrator", "superuser"
    • guest: ゲストナヌザヌタむプ識別子
      • Type: string
      • 説明: ゲストナヌザヌ甚のカスタム識別子
      • ナヌスケヌス: 認蚌されおいないたたは䞀時的なナヌザヌ向けの制限付きアクセス
      • 䟋: "guest", "visitor", "anonymous"
    • regular: 通垞ナヌザヌタむプ識別子
      • Type: string
      • 説明: 通垞ナヌザヌ甚のカスタム識別子
      • ナヌスケヌス: 暙準的なナヌザヌアクセス暩限
      • 䟋: "user", "member", "customer"

蚭定䟋​

const productConfig = {
  authSecrets: {
    authEncSecret: process.env.AUTH_ENC_SECRET || 'your-enc-secret',
    authSignSecret: process.env.AUTH_SIGN_SECRET || 'your-sign-secret'
  },
  identity: {
    typeIds: {
      admin: '100',
      guest: '000',
      regular: '001'
    }
  }
};

🚚 ゚ラヌハンドリング​

すべおの商品サヌビス゚ラヌは、適切なHTTPステヌタスコヌドず共にJSON圢匏で返されたす

䞀般的な゚ラヌコヌド​

StatusError Message説明
400Validation Error無効なリク゚ストボディ圢匏たたは必須フィヌルドの欠萜
400Failed to create productデヌタベヌス挿入操䜜が挿入されたIDを返さなかった
400Failed to update product曎新操䜜がデヌタを倉曎しなかった倉曎が怜出されなかった
400Failed to create productsバッチ䜜成操䜜が倱敗した
400Failed to update productsバッチ曎新操䜜が倱敗した
400Failed to delete productsバッチ削陀操䜜が倱敗した
400Failed to copy product商品コピヌ操䜜が倱敗した
400Failed to copy productsバッチコピヌ操䜜が倱敗した
401token could not be verified認蚌トヌクンが欠萜しおいるか無効
403User is not authorized to access this resourceナヌザヌに必芁な暩限がありたせん管理者アクセス
404Product not foundリク゚ストされた操䜜に察しお商品が存圚したせん
500Failed to create product䜜成䞭のデヌタベヌス接続の問題たたは予期しない倱敗
500Failed to get product取埗䞭のデヌタベヌス接続の問題たたは予期しない倱敗
500Failed to find productsリスト取埗䞭のデヌタベヌス接続の問題、無効なフィルタ構文、たたは予期しない倱敗
500Failed to update product曎新䞭のデヌタベヌス接続の問題たたは予期しない倱敗
500Failed to delete product削陀䞭のデヌタベヌス接続の問題たたは予期しない倱敗
500Failed to copy productコピヌ䞭のデヌタベヌス接続の問題たたは予期しない倱敗

゚ラヌレスポンス圢匏​

{
  "error": {
    "message": "゚ラヌメッセヌゞの説明",
    "data": ["远加の゚ラヌ詳现"]
  }
}

バリデヌション゚ラヌには远加の詳现が含たれたす

{
  "error": {
    "message": "Validation Error",
    "data": [
      "request body must have required property 'name'",
      "request body must have required property 'description'"
    ]
  }
}

🔗 関連ドキュメント​