> For the complete documentation index, see [llms.txt](https://onestore-dev.gitbook.io/dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://onestore-dev.gitbook.io/dev/tools/oneitem.md).

# 원아이템 연동 가이드 (Beta)

원스토어 ONEitem과 연동하는 게임사(개발사)를 위한 서버·SDK 연동 가이드입니다.\
다이어그램의 파란 화살표와 흐름 표의 ● 표시는 게임사가 구현하는 부분입니다.

**작성일** 2026-11-03 · **기준** SDK 2.2.0 · **지원** 국내 회원 · Android

{% hint style="info" %}
**원아이템 입점 시에는** [**원아이템 정책**](https://onestore-dev.gitbook.io/dev/oneitem/guide)**을 준수해야 합니다.** [**해당 가이드**](https://onestore-dev.gitbook.io/dev/oneitem/guide)**를 확인 후 개발 연동을 부탁 드립니다.**\
원아이템은 현재 Closed Beta로 운영되며, 원콘솔 내에서는 정식 오픈할 예정입니다. 대한민국 대상으로 서비스를 제공하며, 대한민국 외 국가는 점차 확대될 예정입니다. \
\
Closed Beta 기간에는 원스토어와 개별 협의한 개발사를 대상으로 입점을 진행합니다. 입점을 희망하시면 [원콘솔의 문의하기](https://dev.onestore.net/dev/help/contact)로 문의해 주시기 바랍니다.
{% endhint %}

## 1. 개요 <a href="#undefined" id="undefined"></a>

게임사는 게임 서버에 아래 8개 API를 구현하면 ONEitem을 통해 계정 연결, 보유 아이템 조회, 판매 등록, 구매 아이템 전달, 판매 취소를 제공할 수 있습니다. 모든 API는 **ONEitem 서버가 게임사 서버를 호출**하는 서버 간(S2S) 통신이며, 게임 클라이언트나 WebView에는 인증 키를 넣지 않습니다.

<table data-search="false"><thead><tr><th>기능</th><th>메서드와 경로</th><th>언제 호출되나</th></tr></thead><tbody><tr><td>점검 확인</td><td><code>GET /v1/status</code></td><td>거래 전 게임 점검 여부 확인</td></tr><tr><td>보유 아이템 조회</td><td><code>GET /v1/inventory</code></td><td>판매자가 판매할 아이템을 고를 때</td></tr><tr><td>수취 계정 확인</td><td><code>POST /v1/recipients/validations</code></td><td>구매자가 아이템 받을 계정을 입력할 때</td></tr><tr><td>판매 수량 잠금</td><td><code>POST /v1/locks</code></td><td>판매 등록 시</td></tr><tr><td>아이템 전달</td><td><code>POST /v1/transfers</code></td><td>구매 결제 완료 후</td></tr><tr><td>잠금 해제</td><td><code>POST /v1/unlocks</code></td><td>판매 취소 또는 거래 실패 확정 시</td></tr><tr><td>처리 결과 조회</td><td><code>GET /v1/operations</code></td><td>응답 유실·타임아웃 후 결과 확인</td></tr><tr><td>계정 연결 토큰 교환</td><td><code>POST /v1/link-tokens/exchanges</code></td><td>회원이 게임 계정을 ONEitem에 연결할 때</td></tr></tbody></table>

결제·판매대금·정산은 이 연동 범위에 포함되지 않습니다.

## 2. 사전 준비 <a href="#undefined" id="undefined"></a>

연동 개발을 시작하기 전에 입점 신청, 게임·아이템 정보 등록, 게임 측 정책 정의를 마쳐야 합니다.

#### 2.1 입점 절차 <a href="#undefined" id="undefined"></a>

1. 원스토어 개발자센터(ONEconsole)에 가입합니다. 수수료 정산을 받기 위해서 정산 정보를 등록합니다.
2. Closed Beta 기간 입점하기 위해서는 [원콘솔의 문의하기](https://dev.onestore.net/dev/help/contact)로 입점 문의 후 연동이 가능합니다.
3. 원아이템 입점 계약 후에 진행이 가능합니다.

#### 2.2 입점 심사 기준 <a href="#undefined" id="undefined"></a>

<table><thead><tr><th width="156">항목</th><th>기준</th></tr></thead><tbody><tr><td>게임 성격</td><td>웹보드(고스톱·포커류), 베팅·배당·카지노 요소가 없을 것</td></tr><tr><td>게임 이용약관</td><td>원스토어를 통한 아이템 2차 거래를 허용하는 조항이 있을 것 (없으면 개정 일정 확정)</td></tr><tr><td>거래 아이템</td><td>등록한 아이템이 실제로 유료 구매로만 얻어지는지 표본 검수</td></tr><tr><td>연동 검증</td><td>테스트 환경에서 API 검증 통과 (타임아웃·중복 호출 처리 포함)</td></tr></tbody></table>

#### 2.3 게임 정보 등록 <a href="#undefined" id="undefined"></a>

<table><thead><tr><th width="164">항목</th><th width="171">필수</th><th>내용</th></tr></thead><tbody><tr><td>게임명</td><td>필수</td><td>다국어 입력 가능</td></tr><tr><td>아이콘</td><td>필수</td><td>512×512, jpg·png</td></tr><tr><td>그래픽 이미지</td><td>필수</td><td>1024×578</td></tr><tr><td>마켓 식별자</td><td>1개 이상</td><td>원스토어 PID, Google Play 패키지명, Apple 앱 ID, Windows·Web URL</td></tr></tbody></table>

원스토어 입점 게임은 기존 상품 정보를 가져와 사용합니다. 미입점 게임은 콘솔에서 직접 입력하며 ONEitem 게임 ID가 발급됩니다. 이 게임 ID는 SDK `setGameId()`에 사용합니다.

#### 2.4 거래 아이템 카탈로그 등록 <a href="#undefined" id="undefined"></a>

카탈로그에 등록된 아이템만 판매할 수 있습니다. 보유 아이템 조회에 나오더라도 카탈로그에 없으면 판매 불가로 표시됩니다.

<table data-search="false"><thead><tr><th width="188">항목</th><th width="182">필수</th><th>내용</th></tr></thead><tbody><tr><td>아이템 ID</td><td>필수</td><td>게임사가 정하는 고유값. 보유 아이템 조회 응답의 <code>developer_item_id</code>와 같은 값</td></tr><tr><td>아이템명·설명</td><td>필수</td><td>한국어</td></tr><tr><td>아이콘</td><td>선택</td><td>화면에는 정사각형으로 표시</td></tr><tr><td>카테고리</td><td>선택</td><td>여러 개 지정 가능</td></tr><tr><td>원본 서버</td><td>필수</td><td>아이템이 속한 서버</td></tr><tr><td>이전 가능 서버</td><td>선택</td><td>미지정 시 원본 서버 안에서만 거래</td></tr><tr><td>아이템 유형</td><td>필수</td><td>획득 경로 분류 (2.5 참고)</td></tr><tr><td>배포 지역</td><td>선택</td><td>대한민국</td></tr></tbody></table>

* 판매가 시작된 아이템은 삭제할 수 없고 판매중지로만 바꿀 수 있습니다.
* 등록 방식(콘솔 입력 또는 서버 연동)과 갱신 주기는 입점 협의 시 안내합니다.

#### 2.5 거래 가능 아이템 기준 <a href="#undefined" id="undefined"></a>

[**원아이템 준수 정책**](https://onestore-dev.gitbook.io/dev/oneitem/guide)**에서 1. 거래 허용 아이템만 선택 가능합니다.**&#x20;

**① 직접 구매형:** 이용자가 대가를 지급하고 특정 아이템 또는 구성품이 확정된 패키지를 직접 구매한 경우 거래할 수 있습니다. 단, 구매 시 옵션이 무작위로 정해지는 아이템은 거래할 수 없습니다.

**② 이용자 간 구매형:** 최초 획득 경로가 ①·**③**·④ 등 허용 유형으로 이력이 시스템에서 확인되는 경우 거래할 수 있습니다. 구매 후 확률형 강화를 한 경우나 최초 획득 경로를 알 수 없는 경우 및 비정상적인 방법으로 획득한 아이템은 거래할 수 없습니다.

**③ 유료 랜덤박스형(미개봉):** 이용자가 직접 유료로 구매한 랜덤박스 중 미개봉 상태가 시스템에서 확인되는 경우 거래할 수 있습니다. 단, 유료 상품 구매 시 보너스·사은품으로 무상 지급된 랜덤박스나 아이템은 유료 구매와 관련되어 있더라도 ⑥ 무료 랜덤박스형으로 보아 거래할 수 없습니다.

**④ 순수 플레이 획득형:** 확률적 요소 없이 게임 이용에 따라 확정 지급된 아이템은 거래할 수 있습니

작업장·해킹·명의도용·결제 취소 등으로 얻은 아이템이 판매 등록되면 게임사가 ONEitem에 알려야 합니다. 통지 방식은 입점 협의 시 안내합니다.

#### 2.6 게임사가 정해야 할 항목 <a href="#undefined" id="undefined"></a>

<table data-search="false"><thead><tr><th width="197">항목</th><th width="355">내용</th><th>관련</th></tr></thead><tbody><tr><td>게임 계정 ID</td><td>외부에서 의미를 알 수 없는 내부 ID. 이메일·닉네임·실명 사용 불가, 128자 이하</td><td><code>game_account_id</code>, <code>setGameUserId()</code></td></tr><tr><td>서버 ID 체계</td><td>게임 서버 식별자. 연결 시 토큰 교환 결과의 <code>server_id</code>로 정해지며, SDK <code>setServerName()</code>은 화면 표시용. 서버 구분이 없는 게임은 빈 문자열</td><td><code>server_id</code></td></tr><tr><td>수취 계정 입력 필드</td><td>구매자가 아이템을 받을 계정을 특정하는 필드 구성 (예: 계정 ID, 캐릭터명)</td><td><code>recipient</code></td></tr><tr><td>연결 토큰 발급 경로</td><td>게임 클라이언트 → 게임 서버의 기존 로그인 세션 경로</td><td>4.1 계정 연결</td></tr><tr><td>개발사 국가</td><td>해외 개발사면 <code>setDeveloperOverseas(true)</code>. 회원에게 개인정보 국외 이전 동의를 추가로 받으며, 동의 화면은 원스토어가 처리</td><td>SDK <code>ONEitemParams</code></td></tr><tr><td>잠금 아이템 처리</td><td>판매 등록으로 잠긴 수량을 게임 안에서 사용·이동·거래할 수 없게 막고 화면에 표시</td><td><code>POST /v1/locks</code></td></tr><tr><td>운영 정보</td><td>기본 주소, 인증 키, 방화벽, 점검 정책, 장애 연락처</td><td>입점 협의 시 확정</td></tr></tbody></table>

#### 2.7 알아 둘 서비스 정책 <a href="#undefined" id="undefined"></a>

* **계정 연결**: 게임별로 원스토어 회원 1명과 게임 계정 1개만 연결됩니다. 판매 중인 아이템이 있으면 연결을 해제할 수 없습니다.
* **회원 자격**: 아이디 회원이면서 만 19세 이상인 회원만 거래합니다. 휴대폰번호 로그인 회원과 미성년자는 계정을 연결할 수 없습니다. 자격 판단은 원스토어가 하며 게임사에 전달하지 않습니다.
* **거래 방식**: 고정가 판매만 제공합니다. 판매 기간은 30일이며, 만료되면 잠금을 풀어 판매자에게 돌려줍니다.
* **수수료**: 플랫폼 수수료 15%, 개발사 수수료 15%입니다. 정산 주기와 방식은 별도로 안내합니다.
* **운영 책임**: 게임사는 비정상 아이템 통지와 거래 분쟁 문의에 응답합니다. 미전달·롤백·서비스 종료 등 개발사 귀책이면 구매자에게 환불됩니다.

## 3. 연동 준비 <a href="#undefined" id="undefined"></a>

#### 3.1 접속 정보 등록 <a href="#undefined" id="undefined"></a>

게임사는 게임별 **기본 주소**(`https://<game-server-host>`)와 **인증 키**를 ONEitem에 전달합니다. ONEitem은 이 두 값으로 호출 대상 게임을 구분합니다.

* 모든 API 경로는 `/v1` 아래에 둡니다.
* 경로·본문·헤더에 게임 ID는 들어가지 않습니다.
* 한 서버에서 여러 게임을 운영하면 기본 주소 또는 인증 키를 게임별로 다르게 발급합니다. 같은 주소·키 조합을 여러 게임에 쓰지 않습니다.
* ONEitem → 게임사 방화벽 허용 IP는 별도로 협의합니다.

#### 3.2 인증과 공통 헤더 <a href="#undefined" id="undefined"></a>

운영 환경은 HTTPS만 사용합니다. 게임사가 발급한 키를 `X-API-Key` 헤더로 받습니다. 키는 **32바이트 이상**이어야 하며 앞뒤 공백·줄바꿈을 포함하지 않습니다.

```
X-API-Key: <게임사가 발급한 키>
Accept: application/json
Content-Type: application/json
```

#### 3.3 공통 규칙 <a href="#undefined" id="undefined"></a>

<table><thead><tr><th width="250">항목</th><th>규칙</th></tr></thead><tbody><tr><td>요청·응답 형식</td><td>JSON. <code>data</code> 같은 래퍼를 추가하지 않음</td></tr><tr><td>정상 응답</td><td>HTTP 200만 성공으로 처리. 201·202·리다이렉트는 성공이 아님</td></tr><tr><td>요청 제한 시간</td><td>5초 (ONEitem 호출 측 현재 설정값)</td></tr><tr><td>응답 본문 크기</td><td>최대 1 MiB</td></tr><tr><td>정의되지 않은 필드</td><td>모든 모델은 명시한 필드 외 속성을 허용하지 않음</td></tr></tbody></table>

#### 3.4 주요 식별자 <a href="#undefined" id="undefined"></a>

<table data-search="false"><thead><tr><th>필드</th><th>의미</th><th>형식·제약</th></tr></thead><tbody><tr><td><code>server_id</code></td><td>게임 서버 식별자</td><td>문자열 1~128자</td></tr><tr><td><code>game_account_id</code></td><td>게임 계정 식별자 (ONEstore 회원 ID와 별개)</td><td>문자열 1~128자</td></tr><tr><td><code>inventory_ref</code></td><td>계정이 보유한 아이템 단위의 식별자 (아이템 정의 ID인 <code>developer_item_id</code>와 별개)</td><td>문자열 1~128자</td></tr><tr><td><code>quantity</code></td><td>수량</td><td>양의 정수 <strong>문자열</strong>, 1~9223372036854775807. <code>"3"</code>은 유효, <code>3</code>·<code>"03"</code>·<code>"0"</code>·<code>"1.5"</code>는 무효</td></tr><tr><td><code>operation_key</code></td><td>ONEitem이 만드는 작업 키. 재시도 시에도 바뀌지 않음</td><td>문자열 1~256자, <code>/</code> 포함 가능</td></tr><tr><td><code>generation</code></td><td>ONEitem이 고정한 잠금 세대 (재시도 횟수 아님)</td><td>정수 1~4294967295</td></tr><tr><td><code>lock_token</code></td><td>잠금 성공 시 게임사가 발급하는 토큰</td><td>문자열 1~200자</td></tr><tr><td><code>recipient</code></td><td>수취 계정을 특정하는 필드 맵</td><td>문자열 값의 객체. 필드 구성은 게임별로 ONEitem과 합의 (예: <code>{"account_id":"..."}</code>)</td></tr></tbody></table>

## 4. 연동 흐름 <a href="#undefined" id="undefined"></a>

#### 4.1 계정 연결 <a href="#undefined" id="undefined"></a>

게임 계정과 ONEstore 회원의 연결은 **게임사 서버가 발급한 1회용 연결 토큰**으로 시작합니다.

<figure><img src="https://1837360763-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fot0z57AnnXZ02C5qyePV%2Fuploads%2F2fs4dHS1FVmtvk5wJUXT%2Fimage.png?alt=media&amp;token=0edb92f8-a900-4d0a-a0f3-2b2929e4d779" alt=""><figcaption></figcaption></figure>

<table data-search="false"><thead><tr><th width="77">단계</th><th width="270">호출 방향</th><th width="291">내용</th><th>게임사 구현</th></tr></thead><tbody><tr><td>①</td><td>게임 클라이언트 → 게임사 서버</td><td>연결 토큰 요청 (로그인 세션 인증)</td><td>●</td></tr><tr><td>②</td><td>게임사 서버 → 게임 클라이언트</td><td><code>token</code>, <code>expires_at</code> 반환 (유효 10분)</td><td>●</td></tr><tr><td>③</td><td>게임 클라이언트 → ONEitem SDK</td><td><code>ONEitemClient.open()</code> — gameId · gameLinkToken · gameUserId</td><td>●</td></tr><tr><td>④</td><td>ONEitem SDK</td><td>원스토어 설치·버전 확인 (미설치·구버전은 안내)</td><td></td></tr><tr><td>⑤</td><td>ONEitem SDK → 원스토어</td><td>연결 토큰 전달</td><td></td></tr><tr><td>⑥</td><td>원스토어</td><td>로그인·회원 확인, 필수 약관 동의</td><td></td></tr><tr><td>⑦</td><td>원스토어 → ONEitem 서버</td><td>연결 토큰 제출</td><td></td></tr><tr><td>⑧</td><td>ONEitem 서버 → 게임사 서버</td><td><code>POST /v1/link-tokens/exchanges</code> (X-API-Key 인증)</td><td>●</td></tr><tr><td>⑨</td><td>게임사 서버 → ONEitem 서버</td><td><code>server_id</code>, <code>game_account_id</code>, <code>expires_at</code> 반환</td><td>●</td></tr><tr><td>⑩</td><td>원스토어 → ONEitem 서버</td><td>연결 확정 (회원이 연결하기 선택)</td><td></td></tr><tr><td>⑪</td><td>원스토어 → ONEitem SDK</td><td>결과 반환 (결과 코드 협의 중)</td><td></td></tr><tr><td>⑫</td><td>ONEitem SDK → 게임 클라이언트</td><td>콜백 <code>ONEitemResult</code> (OK · USER_CANCELED · NOT_ELIGIBLE 등, 협의 중)</td><td>●</td></tr><tr><td>⑬</td><td>게임 클라이언트 → 게임사 서버</td><td>연결 상태 확인 (확인 방법 확정 예정)</td><td>●</td></tr></tbody></table>

* **서버 기준**: 연결된 서버는 ⑨ 토큰 교환 결과의 `server_id`로 정합니다. SDK `setServerName()`은 원스토어 화면에 보여 줄 서버 이름이며 서버 ID로 쓰지 않습니다.

연결 토큰 발급 요건:

<table><thead><tr><th width="203">항목</th><th>요구 사항</th></tr></thead><tbody><tr><td>발급 대상</td><td>현재 로그인 세션의 서버·게임 계정. 클라이언트가 보낸 계정 ID를 그대로 믿지 않음</td></tr><tr><td>형식</td><td>128비트 이상 암호학적 난수의 URL-safe 문자열, 16~512자. 게임·서버·계정을 추측할 수 있는 값 금지</td></tr><tr><td>유효 시간</td><td>발급 후 10분</td></tr><tr><td>1회용·재교환</td><td>첫 교환으로 소비. 단, 응답 유실에 대비해 만료 전 같은 토큰 재교환에는 같은 계정 반환</td></tr><tr><td>저장·로그</td><td>원문 대신 해시 저장. 원문 토큰을 로그·분석 이벤트에 남기지 않음</td></tr><tr><td>클라이언트 처리</td><td>URL query·fragment, 브라우저 저장소, 클립보드에 넣지 않음</td></tr></tbody></table>

같은 계정에 새 토큰을 발급할 때 이전 토큰을 무효화할지는 게임사가 정합니다. 연결 해제는 ONEitem이 처리하므로 별도 API가 없습니다.

#### 4.2 거래 전체 흐름 <a href="#undefined" id="undefined"></a>

<figure><img src="https://1837360763-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fot0z57AnnXZ02C5qyePV%2Fuploads%2FPWktbi9JLffmhffSK2SI%2Funknown.png?alt=media&amp;token=2fe05a1f-5d77-4a70-8cae-c03bd61680ed" alt="잠금 하나는 전달 또는 해제 중 하나로만 끝납니다"><figcaption><p>잠금 하나는 전달 또는 해제 중 하나로만 끝납니다</p></figcaption></figure>

<table><thead><tr><th width="116">단계</th><th>내용</th><th>API</th></tr></thead><tbody><tr><td>1</td><td>보유 아이템 조회</td><td><code>GET /v1/inventory</code></td></tr><tr><td>2</td><td>판매 등록: 수량 잠금</td><td><code>POST /v1/locks</code> → <code>lock_token</code></td></tr><tr><td>3a</td><td>구매: 수취 확인 → 전달</td><td><code>POST /v1/recipients/validations</code>, <code>POST /v1/transfers</code></td></tr><tr><td>3b</td><td>판매 취소: 잠금 해제</td><td><code>POST /v1/unlocks</code></td></tr><tr><td>공통</td><td>응답 유실·타임아웃·503이면 같은 operation_key로 결과 조회</td><td><code>GET /v1/operations</code></td></tr></tbody></table>

잠금 하나는 3a 전달 또는 3b 해제 중 하나로만 끝납니다.

판매 등록 시 잠긴 수량은 구매되면 `transfers`로 구매자에게, 취소되면 `unlocks`로 판매자에게 돌아갑니다. 거래 전 `GET /v1/status`로 점검 여부를 확인합니다.

#### 4.3 판매 등록·취소 <a href="#undefined" id="undefined"></a>

판매 등록은 ⑨ 잠금이 `SUCCEEDED`와 `lock_token`을 돌려줘야 확정됩니다.&#x20;

<figure><img src="https://1837360763-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fot0z57AnnXZ02C5qyePV%2Fuploads%2FHzkBQjLYqLQBBqdWoLrq%2Fimage.png?alt=media&amp;token=3227752f-7564-407f-ab32-31b3dd25ef3c" alt=""><figcaption></figcaption></figure>

<table data-search="false"><thead><tr><th width="53">단계</th><th width="247">호출 방향</th><th width="316">내용</th><th>게임사 구현</th></tr></thead><tbody><tr><td>①</td><td>게임 클라이언트 → ONEitem SDK</td><td><code>ONEitemClient.open()</code> (연결 토큰 포함, 4.1 참고)</td><td>●</td></tr><tr><td>②</td><td>원스토어 → ONEitem 서버</td><td>판매 화면 진입 (연결된 게임 계정 기준)</td><td></td></tr><tr><td>③</td><td>ONEitem 서버 → 게임사 서버</td><td><code>GET /v1/status</code></td><td>●</td></tr><tr><td>④</td><td>게임사 서버 → ONEitem 서버</td><td><code>is_maintenance: false</code></td><td>●</td></tr><tr><td>⑤</td><td>ONEitem 서버 → 게임사 서버</td><td><code>GET /v1/inventory</code> (server_id · game_account_id)</td><td>●</td></tr><tr><td>⑥</td><td>게임사 서버 → ONEitem 서버</td><td><code>items[]</code> (잠긴 수량은 빼고 반환)</td><td>●</td></tr><tr><td>⑦</td><td>ONEitem 서버 → 원스토어</td><td>판매 가능 아이템 표시</td><td></td></tr><tr><td>⑧</td><td>원스토어 → ONEitem 서버</td><td>판매 등록 (수량·가격 입력)</td><td></td></tr><tr><td>⑨</td><td>ONEitem 서버 → 게임사 서버</td><td><code>POST /v1/locks</code> (operation_key · quantity · generation)</td><td>●</td></tr><tr><td>⑩</td><td>게임사 서버</td><td>소유·가용 수량 확인, 선택 수량만 원자적으로 잠금</td><td>●</td></tr><tr><td>⑪</td><td>게임사 서버 → ONEitem 서버</td><td><code>SUCCEEDED</code> + <code>lock_token</code></td><td>●</td></tr><tr><td>⑫</td><td>ONEitem 서버 → 원스토어</td><td>판매 등록 완료</td><td></td></tr><tr><td colspan="4"><strong>판매 취소 시</strong></td></tr><tr><td>⑬</td><td>원스토어 → ONEitem 서버</td><td>판매 취소</td><td></td></tr><tr><td>⑭</td><td>ONEitem 서버 → 게임사 서버</td><td><code>POST /v1/unlocks</code> (operation_key · lock_token · generation)</td><td>●</td></tr><tr><td>⑮</td><td>게임사 서버 → ONEitem 서버</td><td><code>SUCCEEDED</code> (예약 수량을 판매자에게 반환)</td><td>●</td></tr></tbody></table>

* &#x2462;**\~**&#x2465; **조회**: 판매 화면을 열 때 점검 여부와 판매 가능한 보유 아이템을 조회합니다. 이미 잠긴 수량은 목록에서 빠져야 합니다.
* &#x2468;**\~**&#x246A; **잠금**: 소유권·가용 수량 확인과 잠금을 한 번에 처리하고, 성공 시 반드시 `lock_token`을 반환합니다. 같은 `operation_key`로 다시 오면 같은 결과와 같은 토큰을 돌려줍니다.
* **응답 유실**: ONEitem은 새 키로 다시 잠그지 않고 `GET /v1/operations`로 결과를 조회합니다.
* &#x246C;**\~**&#x246E; **판매 취소**: 해당 잠금의 예약 수량만 판매자에게 돌려줍니다. 이미 전달된 잠금이면 `FAILED`로 응답합니다.

요청·응답 상세는 5.1, 5.2, 5.4, 5.6, 5.7을 참고하세요.

#### 4.4 구매 <a href="#undefined" id="undefined"></a>

구매 아이템은 ⑧ 전달 한 번으로 판매자에게서 구매자에게 옮겨집니다.&#x20;

<figure><img src="https://1837360763-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fot0z57AnnXZ02C5qyePV%2Fuploads%2FG4WxuzwKTr4s7DEE6IJj%2Fimage.png?alt=media&amp;token=850e4c19-c455-4665-917e-7349b64a1250" alt=""><figcaption></figcaption></figure>

<table data-search="false"><thead><tr><th width="84">단계</th><th width="217">호출 방향</th><th width="308">내용</th><th>게임사 구현</th></tr></thead><tbody><tr><td>①</td><td>게임 클라이언트 → ONEitem SDK</td><td><code>ONEitemClient.open()</code> (연결 토큰 포함, 4.1 참고)</td><td>●</td></tr><tr><td>②</td><td>원스토어 → ONEitem 서버</td><td>상품 선택 (서버·받을 계정 입력)</td><td></td></tr><tr><td>③</td><td>ONEitem 서버 → 게임사 서버</td><td><code>POST /v1/recipients/validations</code> (server_id · recipient)</td><td>●</td></tr><tr><td>④</td><td>게임사 서버 → ONEitem 서버</td><td><code>masked_account</code> (거부 시 INVALID + reason)</td><td>●</td></tr><tr><td>⑤</td><td>ONEitem 서버 → 원스토어</td><td>받을 계정 확인 표시</td><td></td></tr><tr><td>⑥</td><td>원스토어</td><td>결제 (원스토어에서 결제)</td><td></td></tr><tr><td>⑦</td><td>원스토어 → ONEitem 서버</td><td>결제 결과 전달</td><td></td></tr><tr><td>⑧</td><td>ONEitem 서버 → 게임사 서버</td><td><code>POST /v1/transfers</code> (operation_key · lock_token · recipient)</td><td>●</td></tr><tr><td>⑨</td><td>게임사 서버</td><td>판매자 예약 차감 + 구매자 지급 (원자적으로 1회만)</td><td>●</td></tr><tr><td>⑩</td><td>게임사 서버 → ONEitem 서버</td><td><code>SUCCEEDED</code></td><td>●</td></tr><tr><td>⑪</td><td>ONEitem 서버 → 원스토어</td><td>아이템 전달 완료</td><td></td></tr><tr><td colspan="4"><strong>전달 FAILED 확정 시</strong></td></tr><tr><td>–</td><td>ONEitem 서버 → 게임사 서버</td><td><code>POST /v1/unlocks</code> (operation_key · lock_token · generation)</td><td>●</td></tr><tr><td>–</td><td>게임사 서버 → ONEitem 서버</td><td><code>SUCCEEDED</code> (예약 수량을 판매자에게 반환)</td><td>●</td></tr></tbody></table>

* **③\~④ 수취 확인**: 받을 계정을 확인만 하고 아이템은 이동하지 않습니다. 거부 시 `reason`이 구매 화면 안내에 쓰입니다.
* **⑧\~⑩ 전달**: `lock_token`으로 판매자·아이템·수량을 찾고, 예약 차감과 구매자 지급을 원자적으로 처리합니다. 같은 요청이 반복돼도 한 번만 지급합니다.
* **응답 유실**: 같은 키로 결과를 조회합니다. 타임아웃이나 `UNKNOWN`만으로 환불하거나 잠금을 풀지 않습니다.
* **전달 실패 확정**: ONEitem이 `POST /v1/unlocks`로 잠금을 풀어 판매자에게 수량을 돌려줍니다. 전달과 해제는 동시에 성공할 수 없습니다.

요청·응답 상세는 5.3, 5.5, 5.6, 5.7을 참고하세요.

## 5. API 상세 <a href="#api" id="api"></a>

아래 예시의 계정·아이템·키 값은 설명용입니다.

모든 요청에는 `X-API-Key` 헤더가 포함됩니다(3.2 참고). 표에 없는 필드는 요청·응답에 넣지 않습니다. 문자열 길이는 최소\~최대 글자 수입니다.

#### 5.1 점검 확인 — `GET /v1/status` <a href="#get-v1status" id="get-v1status"></a>

```
{
  "is_maintenance": false
}
```

**요청**: 파라미터 없음

**응답**

| 필드               | 타입      | 필수 | 설명                             |
| ---------------- | ------- | -- | ------------------------------ |
| `is_maintenance` | boolean | 필수 | 점검 중이면 `true`, 거래 가능하면 `false` |

* 점검 중에도 HTTP 200과 `"is_maintenance": true`를 반환합니다.
* 점검 여부는 현재 거래 가능 여부만 뜻하며, 이미 요청된 작업의 결과를 확정하지 않습니다.

#### 5.2 보유 아이템 조회 — `GET /v1/inventory` <a href="#get-v1inventory" id="get-v1inventory"></a>

요청: `GET /v1/inventory?server_id=s1&game_account_id=acct-seller` (두 파라미터 모두 필수)

```
{
  "items": [
    {
      "inventory_ref": "inv-potion-hp-acct-seller",
      "developer_item_id": "potion-hp",
      "name": "회복 물약",
      "server_id": "s1",
      "quantity": "500",
      "attributes": {
        "등급": "희귀"
      }
    }
  ]
}
```

**요청**

<table><thead><tr><th width="89">위치</th><th>필드</th><th>타입</th><th>필수</th><th>설명</th></tr></thead><tbody><tr><td>query</td><td><code>server_id</code></td><td>string (1~128)</td><td>필수</td><td>조회할 게임 서버</td></tr><tr><td>query</td><td><code>game_account_id</code></td><td>string (1~128)</td><td>필수</td><td>조회할 판매자의 게임 계정</td></tr></tbody></table>

**응답**

<table data-search="false"><thead><tr><th>필드</th><th>타입</th><th>필수</th><th>설명</th></tr></thead><tbody><tr><td><code>items</code></td><td>array</td><td>필수</td><td>보유 아이템 목록. 없으면 빈 배열</td></tr><tr><td><code>items[].inventory_ref</code></td><td>string (1~128)</td><td>필수</td><td>계정이 보유한 아이템 단위 식별자. 한 응답 안에서 중복 불가</td></tr><tr><td><code>items[].developer_item_id</code></td><td>string (1~128)</td><td>필수</td><td>아이템 정의 ID (카탈로그의 아이템 ID)</td></tr><tr><td><code>items[].name</code></td><td>string</td><td>필수</td><td>아이템 이름</td></tr><tr><td><code>items[].server_id</code></td><td>string (1~128)</td><td>필수</td><td>요청한 <code>server_id</code>와 같은 값</td></tr><tr><td><code>items[].quantity</code></td><td>string</td><td>필수</td><td>판매 가능 수량. 양의 정수 문자열, 잠긴 수량 제외</td></tr><tr><td><code>items[].attributes</code></td><td>object (값은 string)</td><td>필수</td><td>아이템 속성(등급 등). 없으면 <code>{}</code></td></tr></tbody></table>

* `items`와 각 항목의 6개 필드는 모두 필수입니다. 보유 아이템이 없으면 `{"items": []}`, 속성이 없으면 `"attributes": {}`입니다.
* 한 응답 안에서 `inventory_ref`가 중복되면 안 되며, `server_id`는 요청한 서버와 같아야 합니다.
* 수량 0인 항목은 제외하고, 잠긴(판매 중인) 수량은 빼고 반환합니다.

#### 5.3 수취 계정 확인 — `POST /v1/recipients/validations` <a href="#post-v1recipientsvalidations" id="post-v1recipientsvalidations"></a>

```
{
  "server_id": "s1",
  "recipient": {
    "account_id": "acct-buyer"
  }
}
```

**요청**

| 위치   | 필드          | 타입                 | 필수 | 설명                             |
| ---- | ----------- | ------------------ | -- | ------------------------------ |
| body | `server_id` | string (1\~128)    | 필수 | 아이템을 받을 게임 서버                  |
| body | `recipient` | object (값은 string) | 필수 | 구매자가 입력한 수취 계정 필드. 구성은 게임별로 합의 |

**응답**: 아래 두 형태 중 하나

| 필드               | 타입     | 필수      | 설명                  |
| ---------------- | ------ | ------- | ------------------- |
| `masked_account` | string | 유효 시 필수 | 구매자에게 보여줄 수취 계정 표시값 |
| `status`         | string | 거부 시 필수 | `INVALID` 고정        |
| `reason`         | string | 선택      | 거부 원인. 값은 아래 표 참고   |

아래 두 형태 중 하나만 반환하며, 섞지 않습니다.

<table><thead><tr><th width="229">결과</th><th>응답 예시</th></tr></thead><tbody><tr><td>유효한 계정</td><td><code>{"masked_account": "pla***"}</code> — 구매자에게 보여줄 계정 표시값</td></tr><tr><td>거부</td><td><code>{"status": "INVALID", "reason": "GAME_ACCOUNT_NOT_FOUND"}</code></td></tr></tbody></table>

| `GAME_ACCOUNT_NOT_FOUND` | 입력한 계정이 없음         |
| ------------------------ | ------------------ |
| `SERVER_MISMATCH`        | 해당 서버에서 받을 수 없는 계정 |
| `INVENTORY_FULL`         | 계정의 보관 공간 부족       |

* `reason`은 선택입니다. 생략하거나 목록 밖 값이면 원인 없는 거부로 처리됩니다. 값은 구매 화면의 오류 안내에 사용됩니다.
* 판매자 본인 여부와 점검 여부는 이 API에서 알리지 않습니다.
* 이 단계는 확인만 하며 아이템을 이동하지 않습니다. 실제 전달 시에도 수취 가능 여부를 다시 확인합니다.

#### 5.4 판매 수량 잠금 — `POST /v1/locks` <a href="#post-v1locks" id="post-v1locks"></a>

```
// 요청
{
  "operation_key": "sale/100/lock/1",
  "server_id": "s1",
  "game_account_id": "acct-seller",
  "inventory_ref": "inv-potion-hp-acct-seller",
  "quantity": "3",
  "generation": 1
}

// 응답
{
  "status": "SUCCEEDED",
  "lock_token": "game-lock-token-01"
}
```

**요청**

<table><thead><tr><th width="96">위치</th><th>필드</th><th>타입</th><th width="89">필수</th><th>설명</th></tr></thead><tbody><tr><td>body</td><td><code>operation_key</code></td><td>string (1~256)</td><td>필수</td><td>작업 키. 재시도해도 같은 값</td></tr><tr><td>body</td><td><code>server_id</code></td><td>string (1~128)</td><td>필수</td><td>판매자 게임 서버</td></tr><tr><td>body</td><td><code>game_account_id</code></td><td>string (1~128)</td><td>필수</td><td>판매자 게임 계정</td></tr><tr><td>body</td><td><code>inventory_ref</code></td><td>string (1~128)</td><td>필수</td><td>잠글 보유 아이템 (보유 아이템 조회 값)</td></tr><tr><td>body</td><td><code>quantity</code></td><td>string</td><td>필수</td><td>잠글 수량. 양의 정수 문자열</td></tr><tr><td>body</td><td><code>generation</code></td><td>integer (1~4294967295)</td><td>필수</td><td>잠금 세대. ONEitem이 고정한 값</td></tr></tbody></table>

**응답**

| 필드           | 타입              | 필수      | 설명                                                        |
| ------------ | --------------- | ------- | --------------------------------------------------------- |
| `status`     | string          | 필수      | `SUCCEEDED` · `FAILED` · `UNKNOWN` · `NOT_FOUND` (6.2 참고) |
| `lock_token` | string (1\~200) | 성공 시 필수 | 게임사가 발급하는 잠금 토큰. 전달·해제에 사용                                |

* 소유권과 가용 수량을 확인한 뒤 요청 수량만 **원자적으로** 잠급니다. 잠긴 수량은 게임 내 사용·이동·다른 판매에서 제외합니다.
* 성공 시 `lock_token`은 **반드시** 반환합니다(스키마상 선택 필드이지만 잠금 성공에서는 필수). 같은 작업 키로 결과를 조회해도 같은 토큰을 돌려줍니다.
* 토큰은 게임·소유자·아이템·수량·세대에 결합합니다.

#### 5.5 아이템 전달 — `POST /v1/transfers` <a href="#post-v1transfers" id="post-v1transfers"></a>

```
// 요청
{
  "operation_key": "order/200/transfer/1",
  "lock_token": "game-lock-token-01",
  "generation": 1,
  "recipient_server_id": "s1",
  "recipient": {
    "account_id": "acct-buyer"
  }
}

// 응답
{
  "status": "SUCCEEDED"
}
```

**요청**

| 위치   | 필드                    | 타입                      | 필수 | 설명                         |
| ---- | --------------------- | ----------------------- | -- | -------------------------- |
| body | `operation_key`       | string (1\~256)         | 필수 | 작업 키. 재시도해도 같은 값           |
| body | `lock_token`          | string (1\~200)         | 필수 | 잠금 성공 시 받은 토큰              |
| body | `generation`          | integer (1\~4294967295) | 필수 | 잠금 시와 같은 세대                |
| body | `recipient_server_id` | string (1\~128)         | 필수 | 구매자가 받을 게임 서버              |
| body | `recipient`           | object (값은 string)      | 필수 | 수취 계정 필드 (수취 계정 확인과 같은 구성) |

**응답**

| 필드       | 타입     | 필수 | 설명                                                        |
| -------- | ------ | -- | --------------------------------------------------------- |
| `status` | string | 필수 | `SUCCEEDED` · `FAILED` · `UNKNOWN` · `NOT_FOUND` (6.2 참고) |

* 판매자·아이템·수량은 `lock_token`으로 찾습니다. 요청에 수량은 없습니다.
* 판매자 예약 수량 차감 + 구매자 지급 + 잠금 전달 완료 표시 + 작업 결과 기록을 **하나의 원자적 처리**로 묶습니다.
* 같은 요청이 반복돼도 한 번만 지급합니다. 이미 해제됐거나 세대가 다른 잠금은 전달하지 않습니다.

#### 5.6 잠금 해제 — `POST /v1/unlocks` <a href="#post-v1unlocks" id="post-v1unlocks"></a>

```
// 요청
{
  "operation_key": "sale/100/unlock/1",
  "lock_token": "game-lock-token-01",
  "generation": 1
}

// 응답
{
  "status": "SUCCEEDED"
}
```

**요청**

| 위치   | 필드              | 타입                      | 필수 | 설명               |
| ---- | --------------- | ----------------------- | -- | ---------------- |
| body | `operation_key` | string (1\~256)         | 필수 | 작업 키. 재시도해도 같은 값 |
| body | `lock_token`    | string (1\~200)         | 필수 | 해제할 잠금의 토큰       |
| body | `generation`    | integer (1\~4294967295) | 필수 | 잠금 시와 같은 세대      |

**응답**

| 필드       | 타입     | 필수 | 설명                                                                              |
| -------- | ------ | -- | ------------------------------------------------------------------------------- |
| `status` | string | 필수 | `SUCCEEDED` · `FAILED` · `UNKNOWN` · `NOT_FOUND` (6.2 참고). 이미 전달된 잠금이면 `FAILED` |

* 해당 토큰·세대의 예약 수량만 판매자에게 돌려줍니다.
* **전달과 해제는 동시에 성공할 수 없습니다.** 전달이 끝난 잠금의 해제는 `FAILED`로 응답하며, 구매자에게 지급한 아이템을 회수하지 않습니다.
* 전달 결과가 불명인 동안 게임사 자체 타이머만으로 잠금을 풀지 않습니다.

#### 5.7 처리 결과 조회 — `GET /v1/operations` <a href="#get-v1operations" id="get-v1operations"></a>

요청: `GET /v1/operations?operation_key=sale%2F100%2Flock%2F1`

```
{
  "status": "SUCCEEDED",
  "lock_token": "game-lock-token-01"
}
```

**요청**

| 위치    | 필드              | 타입              | 필수 | 설명                |
| ----- | --------------- | --------------- | -- | ----------------- |
| query | `operation_key` | string (1\~256) | 필수 | 조회할 작업 키. URL 인코딩 |

**응답**

| 필드           | 타입              | 필수  | 설명                                                        |
| ------------ | --------------- | --- | --------------------------------------------------------- |
| `status`     | string          | 필수  | `SUCCEEDED` · `FAILED` · `UNKNOWN` · `NOT_FOUND` (6.2 참고) |
| `lock_token` | string (1\~200) | 조건부 | 잠금 작업이 `SUCCEEDED`이면 필수. 원래 발급한 토큰과 같은 값                  |

* 작업 키는 쿼리 값으로 URL 인코딩합니다. `/`가 포함돼도 경로에 붙이지 않습니다.
* 잠금 작업의 성공 결과에는 원래 `lock_token`을 포함합니다. 전달·해제 결과에는 필요 없습니다.
* 상태값 의미는 6장을 참고하세요.

#### 5.8 계정 연결 토큰 교환 — `POST /v1/link-tokens/exchanges` <a href="#post-v1link-tokensexchanges" id="post-v1link-tokensexchanges"></a>

```
// 요청
{
  "token": "example-link-token-0001"
}

// 응답
{
  "server_id": "s1",
  "game_account_id": "acct-seller",
  "expires_at": "2026-10-27T03:10:00Z"
}
```

**요청**

| 위치   | 필드      | 타입               | 필수 | 설명                                 |
| ---- | ------- | ---------------- | -- | ---------------------------------- |
| body | `token` | string (16\~512) | 필수 | 게임사가 발급한 1회용 연결 토큰. 원문을 로그에 남기지 않음 |

**응답**: 아래 두 형태 중 하나

| 필드                | 타입                     | 필수      | 설명                                                |
| ----------------- | ---------------------- | ------- | ------------------------------------------------- |
| `server_id`       | string (0\~128)        | 유효 시 필수 | 토큰에 묶인 서버. 서버 구분이 없으면 빈 문자열                       |
| `game_account_id` | string (1\~128)        | 유효 시 필수 | 토큰을 발급한 로그인 세션의 게임 계정                             |
| `expires_at`      | string (RFC 3339, UTC) | 유효 시 필수 | 토큰 만료 시각                                          |
| `status`          | string                 | 무효 시 필수 | `INVALID` 고정                                      |
| `reason`          | string                 | 선택      | `TOKEN_NOT_FOUND`(발급 이력 없음) · `TOKEN_EXPIRED`(만료) |

| 상황                        | 응답                                                          |
| ------------------------- | ----------------------------------------------------------- |
| 유효한 토큰 (첫 교환 또는 만료 전 재교환) | 200, `server_id`·`game_account_id`·`expires_at`. 재교환에도 같은 값 |
| 발급 이력 없음                  | 200, `{"status": "INVALID", "reason": "TOKEN_NOT_FOUND"}`   |
| 만료                        | 200, `{"status": "INVALID", "reason": "TOKEN_EXPIRED"}`     |
| 점검 중                      | 503, `{"code": "GAME_MAINTENANCE"}`                         |
| 형식 오류·인증 실패               | 400·401                                                     |

* 서버 구분이 없는 게임은 `server_id`를 빈 문자열로 둡니다. `expires_at`은 UTC, RFC 3339 형식입니다.
* 토큰 발급 요건은 4.1 계정 연결을 참고하세요.

## 6. 응답 처리와 안정성 요건 <a href="#undefined" id="undefined"></a>

업무 결과는 항상 **HTTP 200 + 본문**으로 전달합니다. 200 외의 응답은 통신·요청 문제로 보며, 그것만으로 거래 실패를 확정하지 않습니다.

#### 6.1 HTTP 상태 코드 <a href="#http" id="http"></a>

| 상태                       | 의미                                           | ONEitem 처리                       |
| ------------------------ | -------------------------------------------- | -------------------------------- |
| 200                      | 업무 결과 (본문으로 판단)                              | 본문의 `status`로 처리                 |
| 400                      | 필수값 누락·형식 오류                                 | 요청 확인                            |
| 401                      | 키 없음·무효                                      | 연결 설정 확인                         |
| 409                      | 같은 작업 키를 다른 요청에 재사용 (`OPERATION_KEY_REUSED`) | 자산 변경 없음                         |
| 503 + `GAME_MAINTENANCE` | 명시적 점검                                       | 점검으로 처리하되, 변경 요청은 결과 조회로 대조      |
| 503(그 외)·기타 오류·연결 중단     | 일시 장애                                        | 결과 불명 → `GET /v1/operations`로 대조 |

오류 본문 형식: `{"code": "GAME_MAINTENANCE", "message": "game under maintenance"}`. `code`는 필수, `message`는 선택이며 분기는 `code`로만 합니다.

#### 6.2 작업 결과 상태 (`status`) <a href="#status" id="status"></a>

잠금·전달·해제·결과 조회는 다음 상태 중 하나를 반환합니다.

타임아웃·`UNKNOWN`·`NOT_FOUND`만으로 환불·잠금 해제·새 작업 키 재전달을 결정하지 않습니다. ONEitem이 같은 키로 결과를 다시 조회합니다.

#### 6.3 게임사 구현 필수 요건 <a href="#undefined" id="undefined"></a>

1. **멱등성**: `operation_key`에 고유 제약을 두고 작업 종류와 요청 내용을 비교합니다. 잠금·전달·해제는 같은 키 공간을 공유합니다.
   * 같은 키 + 같은 요청 → 저장해 둔 결과를 그대로 반환
   * 같은 키 + 다른 요청 → 409
   * JSON 공백·필드 순서 차이는 다른 요청으로 보지 않음
2. **원자성**: 자산 변경과 작업 결과 저장을 같은 트랜잭션(또는 동등하게 복구 가능한 절차)으로 처리합니다. 응답 전에 프로세스가 종료돼도 재시도에서 중복 지급이 없어야 합니다.
3. **토큰 결합**: `lock_token`은 한 게임·한 세대에만 유효합니다. 토큰의 소유자·아이템·수량을 요청 값으로 덮어쓰지 않습니다.
4. **경합 처리**: 전달과 해제가 동시에 오면 하나만 성공시킵니다. 오류 응답을 보냈다는 이유만으로 `FAILED`를 기록하지 않습니다.
5. **영속성**: 재시작·재배포 후에도 작업 결과를 조회할 수 있어야 합니다. 메모리 저장은 테스트 용도로만 사용합니다.
