API Reference

Gency Open API 엔드포인트 레퍼런스입니다. Base URL과 인증 헤더(OAuth 토큰·API Key), 공통 응답·에러 형식, 팀·워크스페이스·템플릿·상품·사용자·이미지 API 명세를 정리했습니다.

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": {
    "templates": [
      { "templateId": "01ARZ3JAEKFSV4RVVF369G56#A", "displayName": "템플릿2" },
      { "templateId": "01ARZ3NDEKTSV4RRFFQ69G5FAV", "displayName": "템플릿1" }
    ]
  }
}

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}&split={split}&format={format}&width={width}

Required Scope: product:read

Query Parameters:

파라미터	타입	필수	기본값	설명
`templateId`	String	X	(첫 번째 템플릿)	사용할 템플릿 ID. 미지정 시 상품의 기본 템플릿
`split`	Boolean	X	`false`	`true`면 페이지별 분할 이미지를 ZIP으로, `false`면 단일 이미지로 다운로드
`format`	String	X	`png`	출력 이미지 포맷. `png` 또는 `jpeg` (`jpg`도 허용)
`width`	Integer	X	(canvas 기본값)	출력 이미지 너비(px), `360`~`4096` 범위

Response: 이미지 파일 (binary) — split=false면 선택한 포맷(format)의 단일 이미지 파일, split=true면 페이지별 분할 이미지 ZIP 파일

예시:

GET /openapi/v1/images/download/{productId}?split=true&format=jpeg&width=1200

전체 엔드포인트 요약

기능	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 발급

상품 이미지 다운로드

전체 엔드포인트 요약