# 오너클랜 (OwnerClan) 셀러 오픈 API 전체 레퍼런스

> 오너클랜(ownerclan.com)은 B2B 도매 사입/배송대행 플랫폼입니다. 이 문서는 오너클랜 판매사(셀러)용 오픈 API(GraphQL)의 전체 레퍼런스를 하나의 마크다운 파일로 제공합니다. AI 어시스턴트/에이전트가 이 파일 하나만 읽고 오너클랜 API 사용법을 파악할 수 있도록 작성되었습니다.

- 문서 기준일: 2026-08-05 (사이트 API센터 문서에서 추출)
- 대상: 오너클랜 판매사(셀러) 계정 보유자
- 프로토콜: GraphQL (단일 엔드포인트), 인증: JWT Bearer 토큰
- API 세대: v1 (`/v1/graphql`). 현재 v2는 존재하지 않습니다.
- 재검증 주기: 90일. 이 문서보다 오래된 자료와 내용이 다르면 **항상 이 문서를 우선**하십시오.

---

## 0. 지원 종료된 엔드포인트 (먼저 확인)

**`ownerclan.xyz` 도메인의 모든 API·인증 엔드포인트는 지원이 종료되었습니다.** 오너클랜 API는 `ownerclan.com` 도메인만 사용합니다.

| 지원 종료 (사용 금지) | 대체 엔드포인트 (현행) |
|---|---|
| `https://api.ownerclan.xyz/v1/graphql` | `https://api.ownerclan.com/v1/graphql` |
| `https://api-sandbox.ownerclan.xyz/v1/graphql` | `https://api-sandbox.ownerclan.com/v1/graphql` |
| `https://auth.ownerclan.xyz/auth` | `https://auth.ownerclan.com/auth` |
| `https://auth-sandbox.ownerclan.xyz/auth` | `https://auth-sandbox.ownerclan.com/auth` |
| `https://api-dev.ownerclan.xyz`, `https://api-sandbox.saleop.xyz` | 대체 없음 (내부 개발용, 폐쇄) |
| `https://api-sandbox.ownerclan.xyz/v1/graphiql` (GraphiQL UI) | GraphQL Playground (`https://api-sandbox.ownerclan.com/v1/graphql`) |

중요 — 종료된 주소는 **명시적인 안내 없이 실패**합니다. TLS 핸드셰이크 오류 또는 원인 설명이 없는 502가 반환되며, "지원 종료" 메시지는 나오지 않습니다. 따라서 다음 증상은 코드 문제가 아니라 **주소가 낡은 것**입니다.

- `ownerclan.xyz` 주소에서 TLS/SSL 오류, 연결 실패, 502가 발생 → 호스트를 `ownerclan.com`으로 교체하십시오. 재시도하거나 코드를 수정해도 해결되지 않습니다.

배포된 매뉴얼 zip(`API 매뉴얼.zip`)과 그 안의 `OwnerclanAPI_Seller_Manual.md`, `OwnerclanAPI_Vendor_Manual.md` 등 **버전 표기가 없는 구 매뉴얼 파일은 `ownerclan.xyz` 주소를 현행처럼 안내하고 있습니다. 해당 주소는 무효이며, 이 문서의 표를 기준으로 삼으십시오.**

## 1. 개요

오너클랜 셀러는 API를 통해 다음을 할 수 있습니다.

- 상품 조회: 단일/복수 상품 정보, 상품 변경 이력(품절·단종·재입고 등), 상품코드 리스트 기반 대량 조회
- 주문 관리: 주문 조회, 신규 주문 등록(배송대행 발주), 주문 시뮬레이션(금액/배송비 사전 계산), 주문 메모 수정, 주문 취소/취소 요청, 반품·교환 신청
- 카테고리 조회: 오너클랜 카테고리 트리 탐색
- 문의/알림: 1:1 문의 글 조회·작성, 긴급 메시지 조회, 알림 메모 조회

API 사용 신청은 오너클랜 로그인 후 API센터(`/V2/service/api-center-main.php`)에서 할 수 있으며, 비로그인 안내 페이지는 `https://www.ownerclan.com/V2/service/api-center-guest-view.php` 입니다.

## 2. 엔드포인트

GraphQL 단일 엔드포인트를 사용합니다. 모든 쿼리/뮤테이션을 같은 URL로 전송합니다.

| 환경 | GraphQL 엔드포인트 |
|------|--------------------|
| Production | `https://api.ownerclan.com/v1/graphql` |
| Sandbox | `https://api-sandbox.ownerclan.com/v1/graphql` |

- 같은 URL이 GraphQL Playground 역할도 하므로, 브라우저로 접속하면 쿼리를 직접 실행·테스트할 수 있습니다.
- 쿼리는 GET(`?query=<URL인코딩된 쿼리>`) 또는 POST(JSON body `{query, variables, operationName}`) 모두 가능합니다.
- **사이트 API센터 문서의 실행 예제는 모두 Sandbox 호스트로 작성되어 있습니다.** 운영 연동 시에는 호스트를 Production으로 바꿔야 하며, 예제를 그대로 복사하면 운영 주문이 생성되지 않습니다.
- 경로별 호출 횟수 제한(rate limit)이 적용됩니다. 한도를 넘으면 오류가 반환되므로 대량 조회는 간격을 두고 호출하십시오. 구체적인 한도 수치는 문서화되어 있지 않으므로 API 문의로 확인하십시오.

## 3. 인증 (JWT)

오너클랜 API는 JWT 토큰 인증을 사용합니다.

| 환경 | 인증 엔드포인트 |
|------|-----------------|
| Production | `https://auth.ownerclan.com/auth` |
| Sandbox | `https://auth-sandbox.ownerclan.com/auth` |

토큰 발급 — 아래 JSON을 `Content-Type: application/json`으로 POST하면 JWT 토큰이 반환됩니다.

```json
{
  "service": "ownerclan",
  "userType": "seller",
  "username": "판매사ID",
  "password": "판매사PW"
}
```

- 발급된 토큰은 **한 달간** 사용 가능합니다.
- 이후 모든 API 요청에 헤더 `Authorization: Bearer <발급받은 토큰>`을 포함합니다.

## 4. 상품 API

### 4.1 `item` — 단일 상품 정보 조회 (query)

파라미터:

- `key (String)`: 조회할 상품의 key (오너클랜 상품코드)
- `lang (Language)`: 텍스트 필드 언어. 기본값 `ko_KR`
- `currency (Currency)`: 가격 화폐 단위. 기본값 `KRW`

주요 반환 필드: `createdAt (Int, Unix timestamp)`, `updatedAt (Int)`, `key`, `name`, `model`, `production`(제조사), `origin`(제조국가), `price (Float)`, `pricePolicy (PricePolicy)`, `fixedPrice (Float, 소비자 준수 가격)`, `category { key name fullName }`, `shippingFee (Int)`, `shippingType (ShippingType)`, `status`, `options [ItemOption] { optionAttributes { name value } price quantity }`, `taxFree (Boolean)`, `adultOnly (Boolean)`, `returnable (Boolean)`, `images([URL], size 인자 예: large)`. 예제 코드에는 `guaranteedShippingPeriod`, `openmarketSellable`, `boxQuantity`, `attributes`, `returnCriteria`, `metadata` 필드도 등장합니다.

### 4.2 `allItems` — 복수 상품 정보 조회 (query)

한 번에 **최대 1000개** 조회 가능. cursor 기반 pagination.

파라미터: `after (String)`, `first (Int)`, `minPrice (Int)`, `maxPrice (Int)`, `search (String, 검색어)`

반환: `pageInfo { hasNextPage startCursor endCursor }` + `edges { node { ...item 필드... } }`

### 4.3 `itemHistories` — 상품 변경 이력 조회 (query)

상품의 품절, 단종, 재입고 등의 변경 이력을 조회합니다.

파라미터: `after (String)`, `first (Int)`, `dateFrom (Timestamp)`, `kind (ItemHistoryKind, 예: soldout)`, `itemKey (ID)`

반환: `pageInfo` + `edges { node { itemKey kind title valueBefore valueAfter createdAt } }`

### 4.4 `itemsByKeys` — 상품코드 리스트 기반 대량 조회 (query)

한 번의 요청에 **최대 5000개**의 key 요청 가능.

파라미터: `keys ([String])` — 조회할 상품 key 배열

반환: 상품 정보 배열. `item`과 유사하며 상품의 상세정보인 `content (String)` 필드를 추가로 포함합니다.

### 상품 조회 예제 (사이트 문서의 예제 그대로)

```graphql
query {
    item(key: "W000000") {
        name
        model
        options {
            price
            quantity
            optionAttributes {
                name
                value
            }
        }
    }
}
```

예시 응답:

```json
{
    "data": {
        "item": {
            "name": "예시 상품",
            "model": "예시 모델",
            "options": [
                {
                    "price": 35000,
                    "quantity": 23,
                    "optionAttributes": [
                        { "name": "색상", "value": "RED" },
                        { "name": "사이즈", "value": "95" }
                    ]
                }
            ]
        }
    }
}
```

## 5. 주문 API

### 5.1 `order` — 단일 주문 조회 (query)

파라미터: `key (String)` — 오너클랜 주문 코드

주요 반환 필드:

- `key`, `id`
- `products [OrderProduct]`: `quantity (Int)`, `price (Float, 수량 반영 전)`, `shippingType`, `itemKey`, `itemOptionInfo { optionAttributes { name value } price }`, `trackingNumber`(운송장), `shippingCompanyName`/`shippingCompanyCode`(택배사), `shippedDate (Int)`, `additionalAttributes`, `taxFree`, `status (OrderStatus)`
- `shippingInfo`: `sender { name phoneNumber email }`(보내는 사람), `recipient { name phoneNumber destinationAddress { addr1 addr2 postalCode } }`(받는 사람 — 배송지 주소는 recipient 하위), `shippingFee`
  - 참고: 원문 설명은 `destinationAddress`를 shippingInfo 직속으로 나열하지만, 문서의 모든 실행 예제 쿼리는 `recipient` 내부에 중첩합니다. 예제 구조를 따르십시오.
- `createdAt`, `updatedAt`, `note`(원장주문코드 메모), `ordererNote`(구매자 배송 요청), `sellerNote`(주문관리코드), `isBeingMediated`, `adjustments`(조정 내역), `transactions`(오클머니 사용 내역), `refundDetails`(반품 요청 내역)

### 5.2 `allOrders` — 복수 주문 조회 (query)

한 번에 최대 1000개 조회, cursor pagination. 검색 조건 없이 호출하면 기본값: 지난 90일 주문을 주문 시점 내림차순으로 100개.

- Pagination: `after`, `before`, `first`, `last` — 단, `before`/`last`는 정상 동작하지 않을 수 있어 `after`/`first` 사용 권장 (사이트 문서 명시)
- 검색: `dateFrom (Timestamp, 생략 시 90일 전)`, `dateTo (생략 시 현재)`, `note`(원장주문코드 검색), `sellerNote`(주문관리코드 검색), `status (OrderStatus)`, `shippedAfter`, `shippedBefore`(단독 사용 불가)
- **기간을 명시하는 경우 반드시 90일 이내**여야 합니다. `note`/`sellerNote` 검색 시 dateFrom/dateTo로 90일 이내 기간 지정 필수.

### 5.3 `createOrder` — 새 주문 등록 (mutation)

파라미터: `input (OrderInput!)`, `simulationResult ([object])` — simulateCreateOrder 결과를 넘기면 시뮬레이션과 실제 주문 내역이 일치하지 않을 때 주문이 실패(안전장치).

`OrderInput` 필드(굵은 항목 필수):

- `sender (SenderInput)`: 보내는 사람. 생략하면 판매사 계정 기본값 사용
  - 참고: 원문 문서는 sender를 필수로 표기하면서 동시에 "생략 시 기본값 사용"이라고 설명해 상호 모순됨. 본 문서는 생략 가능 쪽으로 정리했으며, 최종 확인은 API팀 필요.
- **`recipient (RecipientInput)`**: 받는 사람 — `name`, `phoneNumber`, `destinationAddress { addr1 addr2 postalCode }`
- **`products ([OrderProductInput])`**: 주문 상품 리스트 — 예제 기준 `quantity`, `itemKey`, `optionAttributes ([String])`
- `note (String)`: 원장주문코드, `sellerNote (String)`: 주문관리코드, `ordererNote (String)`: 배송 요청사항
- `customsClearanceCode { type (CustomsClearanceCodeType, 예: PersonalNumber), value }`: 해외배송 상품 주문 시에만

주문 분할 규칙: 공급사(`Item.metadata.vendorKey`)가 다르거나 배송비 부과 방식(`Item.shippingType`)이 다르면 주문이 여러 개로 나뉘어 생성됩니다.

### 5.4 `simulateCreateOrder` — 테스트 주문 (mutation)

실제 주문을 등록하지 않고 예상 금액을 반환합니다. 입력은 `createOrder`와 동일한 `input (OrderInput)`.

반환(주문 1건당): `itemAmounts { amount(수량 반영 최종 상품 금액) itemKey }`, `shippingAmount (Int, 추가 배송비 포함 최종 배송비)`, `extraShippingFeeExists (Boolean)`

### 5.5 `updateOrderNotes` — 주문 메모 업데이트 (mutation)

파라미터: `key (String)`, `input (OrderUpdateNotesInput)` — `note (String, 원장주문코드)`, `sellerNotes ([SellerNoteInput]) { sellerNote }`

주문 전체에 메모 1개(배열에 object 1개) 또는 주문 상품별(order 쿼리의 상품 순서대로 배열 지정) 설정 가능. 반환은 `order` 쿼리 결과와 동일.

### 5.6 `cancelOrder` — 주문 취소 (mutation)

파라미터: `key (ID!)`. **결제 완료(paid) 상태인 주문만** 취소 가능. 반환은 `order`와 동일.

### 5.7 `requestOrderCancellation` — 주문 취소 요청 (mutation)

파라미터: `key (ID!)`, `input (RequestOrderCancellationInput) { cancelReason (String) }`. **배송 준비중(preparing) 상태 주문만** 취소 요청 가능. 반환은 `order`와 동일.

### 주문 취소 예제 (사이트 문서의 예제 그대로, 반환 필드 축약)

```graphql
mutation CancelOrder($key: ID!) {
    cancelOrder(key: $key) {
        key
        id
        status
        createdAt
        updatedAt
    }
}
```

Query Variables:

```json
{
    "key": "2020000000000000000A"
}
```

## 6. 카테고리 API

### `category` — 단일 카테고리 조회 (query)

- 파라미터: `key (ID)` — 오너클랜 카테고리 코드
- 모든 최상위 카테고리의 상위 카테고리는 이름 `"ROOT"`, 코드 `"00000000"` — 이를 시작점으로 전체 카테고리 트리를 순회할 수 있습니다.
- 반환: `key`, `id`, `name`, `fullName`(상위 포함 전체 이름), `attributes ([String])`, `parent (Category)`, `children ([Category])`, `ancestors ([Category])`, `descendants (CategoriesConnection — after/before/first/last pagination 지원)`

예제:

```graphql
query {
  category(key: "50000108") {
    key
    name
    parent { key name }
    children { key name }
    ancestors { key name }
    descendants(first: 100) {
      pageInfo { hasNextPage endCursor }
      edges { node { key name } }
    }
  }
}
```

## 7. 문의/알림 API

### 7.1 `sellerQnaArticle` — 단일 1:1 문의 글 조회 (query)

파라미터: `key`. 반환: `key`, `id`, `type (SellerQnaType)`, `isSecret`, `title`, `content`, `files ([String], 첨부 URL)`, `relatedItemKey`, `relatedOrderKey`, `createdAt`, `recipientName`(주문자명), `comments ([String])`, `subArticles ([SellerQnaArticle])`

### 7.2 `allSellerQnaArticles` — 복수 1:1 문의 글 조회 (query)

Pagination: `after`/`before`/`first`/`last`. 검색: `search ([SellerQnaSearch])`, `type (SellerQnaType)`, `receiverName`, `dateFrom`, `dateTo`

### 7.3 `emergencyMessage` / `allEmergencyMessages` — 긴급 메시지 조회 (query)

단건 반환: `key`, `id`, `createdAt`, `type (EmergencyMessageType)`, `itemKey`, `content`, `url`, `penalty (Int)`, `status (EmergencyMessageStatus)`, `repliedAt`, `reply`. 복수 조회는 pagination + `status` 필터.

### 7.4 `notice` / `allNotices` — 알림 메모 조회 (query)

단건 반환: `key`, `id`, `createdAt`, `type (NoticeType)`, `content`, `relatedItemKeys ([String])`, `relatedOrderKeys ([String])`, `checkedAt`. 복수 조회는 pagination + `type`, `checked (Boolean)` 필터.

### 7.5 `createSellerQnaArticle` — 1:1 문의 글 작성 (mutation)

`input (SellerQnaArticleInput)`: `type (SellerQnaType, 예: item)`, `title`, `content`, `files ([Upload], 없으면 [null])`, `relatedItemKey`, `relatedOrderKey`

### 7.6 `requestRefundOrExchange` — 반품/교환 신청 (mutation)

파라미터: `key (ID!)`(대상 주문), `input (RefundExchangeOrderInput)`:

- `productStatus (ProductStatusType, 예: Unopened)`
- `reason (RefundOrExchangeReasonType, 예: DamagedItem)`
- `detailedReason { refundType (예: Reship), detail, explanation }`
- `shippingFeePayment (ShippingFeePaymentType, 예: CollectedOnDelivery)`
- `refundAddress { refundAddressType (예: ManuallyProvided), address }`
- `refundTrackingInfo { shippingCompanyCode, trackingNumber }`
- `content (공급사 전달 내용)`, `files ([Upload])`

반환은 `order` 쿼리 결과와 동일하며 `refundDetails` 필드에 신청 내역이 포함됩니다.

## 8. 문서화되지 않은 부분 (한계 고지)

AI/개발자가 오해하지 않도록, 사이트 API센터 문서에 **없는** 내용을 명시합니다. 아래 항목은 값을 추론하지 말고 API 문의로 확인하십시오.

(CDN 배포 zip 매뉴얼에는 더 많은 내용이 있으나, 버전 표기가 없는 구 매뉴얼 파일은 §0의 지원 종료 엔드포인트를 현행처럼 안내하고 있으므로 엔드포인트는 본 문서를 기준으로 삼으십시오.)

- 에러 코드 목록, HTTP 상태 코드별 의미, 요청 횟수 제한(rate limit)은 사이트 API센터 문서에는 문서화되어 있지 않습니다. 응답의 `errors` 필드 유무로 오류를 판별하십시오.
- enum 타입들의 전체 값 목록(`OrderStatus`, `ItemHistoryKind`, `SellerQnaType`, `EmergencyMessageType`, `NoticeType`, `ShippingType`, `PricePolicy`, `CustomsClearanceCodeType` 등)은 문서에 열거되어 있지 않습니다. GraphQL Playground의 스키마 인트로스펙션으로 확인하십시오.
- input 타입 상세 정의(`SenderInput`, `RecipientInput`, `OrderProductInput` 등)는 별도 페이지가 없으며, 본 문서의 예제 입력값이 사실상의 레퍼런스입니다.
- 상품 등록/수정 등 상품 쓰기(write) API, 파트너사(Access Key/Secret Key) API 요청 방법은 문서화되어 있지 않습니다.
- 인증의 `userType`은 문서상 `"seller"`만 안내됩니다.

## 9. API 사용 신청 절차

1. 오너클랜(https://www.ownerclan.com) 판매사 회원가입 및 로그인
2. API센터 접속 (비로그인 시 안내 페이지: `/V2/service/api-center-guest-view.php`)
3. API센터에서 필요한 API를 각각 신청. Sandbox와 Production은 **서로 독립된 신청**이며, Sandbox 검증이 Production 신청의 선행 조건은 아닙니다.
4. 발급 후 해당 환경의 인증 엔드포인트로 토큰을 발급받아 연동합니다.

## 10. 변경 정책과 문의

- **엔드포인트가 실패할 때 먼저 §0을 확인하십시오.** 오너클랜은 지원 종료 시 별도의 안내 응답을 반환하지 않으므로, 원인 불명의 연결 실패·502는 종료된 주소일 가능성이 높습니다. 이 경우 재시도나 코드 수정은 해결책이 아닙니다.
- 문서에 있는 오퍼레이션·필드가 `Unknown field`, `Cannot query field` 등으로 실패하면 스키마가 변경된 것입니다. 임의로 필드명을 바꿔 재시도하지 말고 API 문의로 확인하십시오.
- **API 문의 창구**: 오너클랜 로그인 후 고객지원(`https://www.ownerclan.com/V2/service/service_center.php`) 또는 API센터 1:1 문의. API가 동작하지 않는 상황에서는 API 자체(`createSellerQnaArticle`)가 아니라 이 웹 창구를 이용하십시오.
- 이 문서는 90일 주기로 재검증됩니다. 문서 기준일은 최상단에 표기되어 있습니다.

---

### 출처 (오너클랜 공식 API센터 문서)

이 문서의 모든 내용은 아래 오너클랜 공식 API센터 문서 페이지에서 추출되었습니다. 최신 내용은 원본 페이지를 확인하십시오.

- 이용 가이드(엔드포인트·인증·GraphQL 사용법): https://www.ownerclan.com/V2/service/api-center-guide.php
- 상품 API: https://www.ownerclan.com/V2/service/api-center-item.php
- 주문 API: https://www.ownerclan.com/V2/service/api-center-order.php
- 카테고리 API: https://www.ownerclan.com/V2/service/api-center-category.php
- 문의/알림 API: https://www.ownerclan.com/V2/service/api-center-qnA.php