API Reference

Common Convention

Base URL

https://openapi.gency.ai

Content-Type

すべてのリクエストとレスポンスは application/json 形式を使用します。

認証

すべての API リクエストには、次のいずれかの認証ヘッダーが必要です。

方式	ヘッダー	説明
OAuth2 Token	`Authorization: Bearer {access_token}`	OAuth フローで発行されたトークン
API Key	`X-API-Key: {api_key}`	API センターで発行されたキー

成功レスポンス

すべての API の成功レスポンスは {"data": ...} の形にラップされます。

{
  "data": {
    // 리소스 데이터
  }
}

エラーレスポンス

エラー発生時は次の形式で返されます。

{
  "status": 400,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "요청이 올바르지 않습니다."
  },
  "data": null,
  "timestamp": "2025-01-01T00:00:00.000Z"
}

フィールド	タイプ	説明
`status`	Integer	HTTP ステータスコード
`error.code`	String	エラーコード
`error.message`	String	エラーメッセージ
`data`	Any	追加のエラーデータ (任意)
`timestamp`	String	エラー発生時刻 (ISO 8601, UTC)

Team (チーム)

自分のチーム情報の照会

GET /openapi/v1/teams/me

Required Scope: team:read

Response:

{
  "data": {
    "teamId": "01HABC...",
    "teamName": "김젠시의 팀",
    "plan": "MASTER_PLAN_01"
  }
}

フィールド	タイプ	説明
`teamId`	String	チーム ID
`teamName`	String	チーム名
`plan`	String	プラン (`BASIC`: ベーシック, `ENTERPRISE`: エンタープライズ)

クレジットの照会

GET /openapi/v1/usage/credits

Required Scope: team:read

Response:

{
"data": {
    "credit": 100
  }
}

フィールド	タイプ	説明
`credit`	Integer	クレジット

Workspaces (ワークスペース)

ワークスペース一覧の照会

GET /openapi/v1/workspaces

Required Scope: team:read

Response:

{
  "data": {
    "workspaces": [
      {
        "workspaceId": "01HXYZ...",
        "workspaceName": "My Workspace",
        "createdAt": "2025-01-01T00:00:00+09:00"
      }
    ]
  }
}

ワークスペースの作成

POST /openapi/v1/workspaces

Required Scope: team:write

Request Body:

{
  "name": "New Workspace"
}

フィールド	タイプ	必須	説明
`name`	String	O	ワークスペース名 (最大100文字)

ワークスペース名の変更

PATCH /openapi/v1/workspaces/{workspaceId}

Required Scope: team:write

Request Body:

{
  "name": "Updated Name"
}

Templates (テンプレート)

テンプレート一覧の照会

GET /openapi/v1/templates?workspaceId={workspaceId}&productType={productType}

Required Scope: product:read

Query Parameters:

パラメータ	タイプ	必須	説明
`workspaceId`	String	O	ワークスペース ID
`productType`	String	X	商品タイプ (デフォルト値: `FASHION`)

Response:

{
  "data": {
    "templateIds": ["template_01", "template_02"]
  }
}

Products (商品)

商品一覧の照会

GET /openapi/v1/products?workspaceId={workspaceId}

Required Scope: product:read

Query Parameters:

パラメータ	タイプ	必須	説明
`workspaceId`	String	O	ワークスペース ID

Response:

{
  "data": {
    "products": [
      {
        "productId": "01HXYZ...",
        "workspaceId": "01HABC...",
        "projectId": "01HDEF...",
        "name": "상품명",
        "titleImageId": "01HIMG...",
        "status": "REVIEW_COMPLETE",
        "categoryId": "01HCAT...",
        "productType": "FASHION",
        "createdId": "01HUSR...",
        "updatedId": "01HUSR...",
        "createdAt": "2025-01-01T00:00:00+09:00",
        "updatedAt": "2025-01-02T00:00:00+09:00"
      }
    ]
  }
}

商品詳細の照会

GET /openapi/v1/products/{productId}

Required Scope: product:read

Response:

{
  "data": {
    "productId": "01HXYZ...",
    "workspaceId": "01HABC...",
    "projectId": "01HDEF...",
    "name": "상품명",
    "titleImageId": "01HIMG...",
    "status": "REVIEW_COMPLETE",
    "categoryId": "01HCAT...",
    "productType": "FASHION",
    "createdId": "01HUSR...",
    "updatedId": "01HUSR...",
    "createdAt": "2025-01-01T00:00:00+09:00",
    "updatedAt": "2025-01-02T00:00:00+09:00"
  }
}

商品の作成

POST /openapi/v1/products

Required Scope: product:write

Request Body:

{
  "workspaceId": "01HABC...",
  "products": [
    {
      "category": "TOP",
      "images": ["01HIMG..."],
      "projectId": "01HDEF...",
      "productNameKo": "상품명(한국어)",
      "productNameEn": "Product Name",
      "colors": ["BLACK", "WHITE"],
      "fabrics": ["COTTON"],
      "templateId": "TEMPLATE_01",
      "additionalInfo": {
        "features": ["스트레치 소재"],
        "laundryTips": ["드라이클리닝"],
        "sizeName": "FREE",
        "sizeTables": [["사이즈","어깨","기장"],["S", "55", "80"], ["M", "60", "85"]],
        "manufactureDate": "2025-01",
        "manufactureCountry": "대한민국",
        "certificationNumber": "KC-12345"
      }
    }
  ]
}

Request Fields

フィールド	タイプ	必須	説明
`workspaceId`	string	O	ワークスペース ID
`products`	array	O	商品メタデータの配列 (最小1個)
`products[].category`	string	O	商品カテゴリ (下記参照)
`products[].images`	array	O	画像 ID の配列 (最小6個、アップロード URL で事前アップロードが必要)
`products[].projectId`	string		管理名 (プロジェクト ID)
`products[].productName`	string		商品名
`products[].productNameKo`	string		商品名 (韓国語)
`products[].productNameEn`	string		商品名 (英語)
`products[].colors`	array	O	色の一覧
`products[].fabrics`	array	O	素材の一覧
`products[].templateId`	string	O	テンプレート ID
`products[].additionalInfo`	object		追加情報
`products[].additionalInfo.features`	array		特徴
`products[].additionalInfo.laundryTips`	array		洗濯情報
`products[].additionalInfo.sizeName`	string		サイズ名
`products[].additionalInfo.sizeTables`	array		サイズテーブル (2次元配列、先頭行はヘッダー情報)
`products[].additionalInfo.manufactureDate`	string		製造日
`products[].additionalInfo.manufactureCountry`	string		製造国
`products[].additionalInfo.certificationNumber`	string		認証番号

Category 値

CLOTHING のみサポート、今後拡張予定

Response:

{
  "data": {
    "productIds": ["01HXYZ...", "01HABC..."]
  }
}

商品の検収状態変更

PATCH /openapi/v1/products/{productId}/status

Required Scope: product:write

Request Body:

{
  "status": "IN_REVIEW"
}

フィールド	タイプ	必須	説明
`status`	String	O	変更する状態

設定可能な状態値:

状態	説明
`BEFORE_REVIEW`	検収前
`IN_REVIEW`	検収中
`REVIEW_COMPLETE`	検収完了

参考: 検収前/検収中/検収完了の状態のときのみ変更可能です。

Users (ユーザー)

自分の情報の照会

GET /openapi/v1/users/me

Required Scope: user:read

Response:

{
  "data": {
    "userId": "01HXYZ...",
    "email": "user@example.com",
    "name": "김젠시",
    "permission": "MANAGER",
    "createdAt": "2025-01-01T00:00:00+09:00"
  }
}

フィールド	タイプ	説明
`userId`	String	ユーザー ID
`email`	String	メールアドレス
`name`	String	ユーザー名
`permission`	String	権限 (`OWNER`: オーナー, `MANAGER`: マネージャー, `MEMBER`: メンバー)
`createdAt`	String	登録日時 (ISO 8601)

メンバー情報の照会

GET /openapi/v1/users/{userId}

Required Scope: user:read

Path Parameters:

パラメータ	タイプ	必須	説明
`userId`	String	O	照会するユーザー ID

参考: 同じチーム(マスター)に所属するユーザーのみ照会できます。

Response:

{
  "data": {
    "userId": "01HXYZ...",
    "email": "user@example.com",
    "name": "김젠시",
    "permission": "MANAGER",
    "createdAt": "2025-01-01T00:00:00+09:00"
  }
}

チームメンバー一覧の照会

GET /openapi/v1/users

Required Scope: user:read

Response:

{
  "data": {
    "members": [
      {
        "userId": "01HXYZ...",
        "userName": "김젠시",
        "email": "user@example.com",
        "permission": "OWNER",
        "createdAt": "2025-01-01T00:00:00+09:00"
      }
    ]
  }
}

Images (画像)

アップロード URL の発行

POST /openapi/v1/images/upload-url

Required Scope: product:write

Request Body:

{
  "workspaceId": "01HABC...",
  "extension": "png"
}

フィールド	タイプ	必須	説明
`workspaceId`	String	O	ワークスペース ID
`extension`	String	O	ファイル拡張子 (`png`, `jpg`, `jpeg`, `webp`)

Response:

{
  "data": {
    "imageId": "01HXYZ...",
    "uploadUrl": "https://s3.amazonaws.com/..."
  }
}

フィールド	タイプ	説明
`imageId`	String	画像識別子 (商品作成時に使用)
`uploadUrl`	String	S3 Presigned URL (1時間有効)

商品画像のダウンロード

GET /openapi/v1/images/download/{productId}?templateId={templateId}

Required Scope: product:read

Query Parameters:

パラメータ	タイプ	必須	説明
`templateId`	String	X	テンプレート ID

Response: PNG 画像ファイル (binary)

全エンドポイントの要約

機能	Method	Endpoint	Scope
チーム情報の照会	GET	`/openapi/v1/team`	`team:read`
クレジットの照会	GET	`/openapi/v1/usage/credits`	`team:read`
ワークスペース一覧	GET	`/openapi/v1/workspaces`	`team:read`
ワークスペース作成	POST	`/openapi/v1/workspaces`	`team:write`
ワークスペース修正	PATCH	`/openapi/v1/workspaces/{workspaceId}`	`team:write`
テンプレート一覧	GET	`/openapi/v1/templates`	`product:read`
商品一覧	GET	`/openapi/v1/products`	`product:read`
商品詳細	GET	`/openapi/v1/products/{productId}`	`product:read`
衣類商品の作成	POST	`/openapi/v1/products`	`product:write`
商品状態の変更	PATCH	`/openapi/v1/products/{productId}/status`	`product:write`
自分の情報の照会	GET	`/openapi/v1/users/me`	`user:read`
メンバー情報の照会	GET	`/openapi/v1/users/{userId}`	`user:read`
チームメンバー一覧	GET	`/openapi/v1/users`	`user:read`
アップロード URL 生成	POST	`/openapi/v1/images/upload-url`	`product:write`
画像ダウンロード	GET	`/openapi/v1/images/download/{productId}`	`product:read`

Common Convention​

Team (チーム)​

自分のチーム情報の照会​

クレジットの照会​

Workspaces (ワークスペース)​

ワークスペース一覧の照会​

ワークスペースの作成​

ワークスペース名の変更​

Templates (テンプレート)​

テンプレート一覧の照会​

Products (商品)​

商品一覧の照会​

商品詳細の照会​

商品の作成​

商品の検収状態変更​

Users (ユーザー)​

自分の情報の照会​

メンバー情報の照会​

チームメンバー一覧の照会​

Images (画像)​

アップロード URL の発行​

商品画像のダウンロード​

全エンドポイントの要約​

Common Convention

Team (チーム)

自分のチーム情報の照会

クレジットの照会

Workspaces (ワークスペース)

ワークスペース一覧の照会

ワークスペースの作成

ワークスペース名の変更

Templates (テンプレート)

テンプレート一覧の照会

Products (商品)

商品一覧の照会

商品詳細の照会

商品の作成

商品の検収状態変更

Users (ユーザー)

自分の情報の照会

メンバー情報の照会

チームメンバー一覧の照会

Images (画像)

アップロード URL の発行

商品画像のダウンロード

全エンドポイントの要約