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		尺寸表（二維陣列，第一列為標頭資訊）
`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

參考： 僅能查詢同一團隊（master）所屬的使用者。

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

下載商品圖片

全部端點摘要