> 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/onequest.md).

# ONEquest 인게임 연동 가이드

ONEquest(원퀘스트)는 게임사가 원하는 시점에 목표에 맞는 퀘스트를 설정하여 원스토어 유저의 게임 참여를 유도할 수 있는 마케팅 도구입니다. 인게임 액션 퀘스트를 제공하려면, 게임 내 액션의 완료 여부를 ONEquest에 전달할 수 있도록 게임사 측 개발 연동이 필요합니다.

## 1. 개요

퀘스트 이용자가 게임 내 특정 액션(퀘스트)을 달성하고 보상을 신청할 때, 원퀘스트 서버가 게임사 API 를 호출해 달성 여부를 실시간으로 검증합니다. 게임사는 본 문서의 규격에 맞춰 **2개의 API** 를 구현해 제공해야 합니다.

<table><thead><tr><th width="175.46875">API</th><th width="159.8515625">호출 시점</th><th>역할</th></tr></thead><tbody><tr><td><a href="#id-5.-api">유저 유효성 확인 API</a></td><td>최초 계정 연동 시</td><td>입력된 <code>game_user_id</code> 가 게임 서버에 실제로 존재하는 유저인지 확인합니다.</td></tr><tr><td><a href="#id-v1.0-6.-api">인게임 액션 검증 API</a></td><td>보상 신청 시</td><td>해당 유저가 지정된 퀘스트를 달성했는지 실시간 조회 후 결과 반환 합니다.</td></tr></tbody></table>

{% hint style="info" %}
두 API 모두 **원퀘스트 서버 → 게임사 서버** 방향의 Server-to-Server 통신입니다. 게임 클라이언트(앱)에는 추가 개발이 필요하지 않습니다. 게임사가 원퀘스트를 호출하는 API 는 없습니다.
{% endhint %}

{% hint style="danger" %}
**반드시 확인해 주세요.**

* 유저 식별자 `game_user_id` 는 **UUID** 를 사용해야 합니다. 순차적 숫자(Sequence)·이메일 주소 등 외부에서 추측 가능한 값을 쓰면, 타인의 `game_user_id` 를 유추해 부정 보상을 수령하는 어뷰징이 발생합니다.
* API 응답은 **500ms 이내**에 완료되어야 합니다.
* 검증 API 는 **조회 전용**이어야 합니다. 같은 요청이 반복돼도 상태가 바뀌면 안 됩니다.
  {% endhint %}

## 2. 연동 프로세스

안정적인 보상 지급과 유저 편의를 위해 **① 최초 계정 연동** 과 **② 인게임 액션 검증** 의 2단계로 동작합니다.

**Phase 1. 최초 계정 연동 — 유저당 1회**

<table><thead><tr><th width="86">순서</th><th width="158">주체</th><th>동작</th></tr></thead><tbody><tr><td>1</td><td>User</td><td>게임 ID(<code>game_user_id</code>) 입력 후 '연동하기' 선택</td></tr><tr><td>2</td><td>원퀘스트</td><td>게임사 <strong>유저 유효성 확인 API</strong> 호출</td></tr><tr><td>3</td><td>Game Server</td><td>유저 존재 여부 확인 후 <code>success</code> 반환</td></tr><tr><td>4</td><td>원퀘스트</td><td>유효한 유저이면 <code>game_user_id</code> 를 저장. 이후 같은 퀘스트 그룹의 모든 퀘스트에 재사용</td></tr></tbody></table>

**Phase 2. 인게임 액션 검증 — 보상 신청 시마다**

<table><thead><tr><th width="86">순서</th><th width="158">주체</th><th>동작</th></tr></thead><tbody><tr><td>1</td><td>User</td><td>퀘스트 달성 후 ID 입력 없이 '보상 받기' 선택</td></tr><tr><td>2</td><td>원퀘스트</td><td>저장된 <code>game_user_id</code> 로 게임사 <strong>인게임 액션 검증 API</strong> 자동 호출</td></tr><tr><td>3</td><td>Game Server</td><td>유저의 퀘스트 달성 데이터 조회 및 결과 반환</td></tr><tr><td>4</td><td>원퀘스트</td><td>결과에 따라 유저에게 리워드 지급</td></tr></tbody></table>

{% hint style="info" %}
하나의 `game_user_id` 는 **원스토어 계정 1개에만** 연동됩니다. 이미 다른 원스토어 계정에 연동된 식별자로는 연동할 수 없습니다(중복 참여 방지).
{% endhint %}

## 3. 사전 준비 사항

#### 3.1 개발 필수 요건

<table><thead><tr><th width="171">항목</th><th>요건</th></tr></thead><tbody><tr><td>프로토콜</td><td><strong>HTTPS 권장</strong> (HTTP 허용 시 별도 협의). 엔드포인트 호스트는 IP 주소가 아닌 <strong>DNS 도메인(호스트명)</strong> 으로 제공해 주시기 바랍니다</td></tr><tr><td>응답 속도 (SLA)</td><td>API 응답은 요청 후 <strong>500ms 이내</strong>에 완료되어야 합니다</td></tr><tr><td>데이터 형식</td><td>요청 및 응답 본문은 <strong>JSON</strong> 형식을 사용합니다 (<code>Content-Type: application/json</code>)</td></tr><tr><td>식별자 전달</td><td><code>game_user_id</code> 는 HTTP 메서드 종류와 관계없이 <strong>쿼리 파라미터(Query String)</strong> 로 수신해야 합니다. 표준이 요구하는 필수 파라미터는 <code>game_user_id</code> 하나입니다</td></tr><tr><td>엔드포인트</td><td>경로·호스트는 게임 서비스 환경에 맞게 자율 구성 가능합니다. <br>단 요청·응답 데이터 규격은 반드시 본 표준을 준수해야 합니다</td></tr><tr><td>리다이렉트</td><td>등록한 URL 이 <strong>최종 URL</strong> 이어야 합니다. <br>원퀘스트는 3xx 리다이렉트를 따라가지 않습니다</td></tr></tbody></table>

#### 3.2 방화벽 허용 IP <a href="#id-v1.0-3.2-ip" id="id-v1.0-3.2-ip"></a>

원퀘스트 서버가 게임사 API 를 호출하므로, 게임사 서버(방화벽)는 아래 **원퀘스트 발송 IP(Source IP)에 대해 인바운드 접근을 허용**해야 합니다.

<table><thead><tr><th width="232">환경</th><th>허용해야 할 IP 주소 (Source IP)</th></tr></thead><tbody><tr><td>개발(QA) 서버</td><td><code>211.188.207.190</code></td></tr><tr><td>운영(상용) 서버</td><td><code>211.188.201.250</code></td></tr></tbody></table>

{% hint style="danger" %}
등록되지 않은 IP 에서의 요청은 게임사 서버에서 **401 또는 403** 으로 거부 처리하여 보안을 유지해야 합니다. 개발 환경의 경우 추가로 IP 를 요청할 수 있습니다. IP 가 변경될 경우 사전에 안내해 드립니다.
{% endhint %}

#### 3.3 콘솔 등록 <a href="#id-v1.0-3.2-ip" id="id-v1.0-3.2-ip"></a>

구현한 API 는 개발자센터 **ONEconsole > Quest** 메뉴에서 개발사가 직접 등록합니다. 원퀘스트는 여기 등록된 URL 에 `game_user_id` 쿼리 파라미터만 붙여 호출합니다.

<table><thead><tr><th width="179">등록 단위</th><th width="208">항목</th><th>설명</th></tr></thead><tbody><tr><td>퀘스트 그룹</td><td><a href="#id-5.-api">유저 유효성 확인 API URL</a></td><td>퀘스트 그룹 당 1개.</td></tr><tr><td>퀘스트 (인게임 액션)</td><td><a href="#id-v1.0-6.-api">인게임 액션 검증 API URL</a></td><td>퀘스트마다 1개. 경로에 게임사 자체 퀘스트 식별자를 포함하는 방식을 권장합니다</td></tr></tbody></table>

{% hint style="info" %}
**등록 화면에서 통신 테스트를 제공합니다.** \
입력한 URL 로 실제 호출을 보내 도달 여부와 응답 규격을 확인하며, **통신 테스트를 통과해야 퀘스트를 등록 가능 합니다.**

테스트는 "도달 가능하고 규격에 맞는 JSON 을 반환하는가" 를 확인하는 것이므로, 달성/미달성 어느 결과여도 통과합니다. URL 이나 HTTP Method 를 변경하면 다시 테스트해야 합니다.
{% endhint %}

## 4. game\_user\_id

두 API 모두 유저 식별자로 `game_user_id` 하나만을 필수 파라미터로 사용합니다.

<table><thead><tr><th width="150">항목</th><th>설명</th></tr></thead><tbody><tr><td>타입</td><td>String</td></tr><tr><td>형식</td><td><strong>UUID</strong> — 표준 UUID(36자) 형식 8-4-4-4-12</td></tr><tr><td>최대 길이</td><td>255자 이내</td></tr><tr><td>전달 위치</td><td>HTTP 메서드 종류와 관계없이 <strong>쿼리 파라미터(Query String)</strong> 로 수신</td></tr><tr><td>예시</td><td><code>13f664fc-3d8a-f011-94e3-e0451a3b66b3</code></td></tr></tbody></table>

{% hint style="warning" %}
순차적 숫자(Sequence), **이메일 주소** 등 외부에서 추측 가능한 값은 사용할 수 없습니다. 타인의 `game_user_id` 를 유추해 부정 보상을 수령하는 어뷰징으로 이어집니다.
{% endhint %}

## 5. 유저 유효성 확인 API

원퀘스트 이용자가 게임 계정을 최초 연동할 때, 입력한 `game_user_id` 가 게임 서버에 실제로 존재하는지 확인하는 API 입니다.

#### 5.1 요청 (Request) <a href="#id-v1.0-5.1-request" id="id-v1.0-5.1-request"></a>

<table><thead><tr><th width="150">항목</th><th>값</th></tr></thead><tbody><tr><td>Method</td><td>GET (예시)</td></tr><tr><td>Endpoint (예시)</td><td><code>https://{Game_Server_Host}/onequest/users/validate?game_user_id=13f664fc-3d8a-f011-94e3-e0451a3b66b3</code></td></tr><tr><td>Content-Type</td><td>application/json</td></tr></tbody></table>

엔드포인트 경로는 예시이며, 게임 서비스 환경에 맞게 구성 후 ONEconsole 에 등록해 주세요. **요청·응답 데이터 규격은 변경할 수 없습니다.**

<table><thead><tr><th width="83">구분</th><th width="151">파라미터명</th><th width="99">타입</th><th width="78">필</th><th>설명</th></tr></thead><tbody><tr><td>Query</td><td>game_user_id</td><td>String</td><td>Y</td><td>검증할 게임 내 유저 식별자 (UUID, 최대 255자)</td></tr></tbody></table>

#### Request Example <a href="#id-v1.0-5.2-response" id="id-v1.0-5.2-response"></a>

```
curl -X GET \
```

#### 5.2 응답 (Response) <a href="#id-v1.0-5.2-response" id="id-v1.0-5.2-response"></a>

<table><thead><tr><th width="127">필드명</th><th width="107">타입</th><th width="88">필수</th><th>설명</th></tr></thead><tbody><tr><td>success</td><td>Boolean</td><td>Y</td><td>유효한 유저 여부 (true: 존재함, false: 존재하지 않음)</td></tr><tr><td>joined_at</td><td>String</td><td>N</td><td>게임 가입 일시. ISO 8601 형식(타임존 포함)</td></tr></tbody></table>

#### 성공 - 유효한 유저

```
{
  "success": true,
  "joined_at": "2026-09-01T07:14:08.920+09:00"
}
```

#### 실패 - 존재하지 않는 유저

```
{
  "success": false,
  "joined_at": null
}
```

## 6. 인게임 액션 검증 API <a href="#id-v1.0-6.-api" id="id-v1.0-6.-api"></a>

유저가 게임 내 특정 퀘스트를 완수하고 보상을 신청하는 시점에, 해당 유저의 실제 달성 여부를 실시간으로 조회·검증하는 API 입니다. 퀘스트마다 ONEconsole 에 등록한 URL 로 호출됩니다.

#### 6.1 요청 (Request) <a href="#id-v1.0-6.1-request" id="id-v1.0-6.1-request"></a>

<table><thead><tr><th width="159">항목</th><th>값</th></tr></thead><tbody><tr><td>Method</td><td>GET (예시)</td></tr><tr><td>Endpoint (예시)</td><td><code>https://{Game_Server_Host}/onequest/quests/{quest_id}/verify?game_user_id=13f664fc-3d8a-f011-94e3-e0451a3b66b3</code></td></tr><tr><td>Content-Type</td><td>application/json</td></tr></tbody></table>

<table><thead><tr><th width="90">구분</th><th width="132">파라미터명</th><th width="105">타입</th><th width="83">필수</th><th>설명</th></tr></thead><tbody><tr><td>Path</td><td>quest_id</td><td>String</td><td>N</td><td>게임사 자체 퀘스트 식별자. 원퀘스트는 URL 을 해석하지 않고 등록된 URL 그대로 호출하므로, 퀘스트별 조건(레벨·튜토리얼 완료 등)은 게임사 서버가 URL 로 구분합니다</td></tr><tr><td>Query</td><td>game_user_id</td><td>String</td><td>Y</td><td>게임 내 유저 식별자 (UUID). Phase 1 에서 연동 저장된 값</td></tr></tbody></table>

#### Request Example

```
curl -X GET \
  "https://api.game-company.com/onequest/quests/1/verify?game_user_id=13f664fc-3d8a-f011-94e3-e0451a3b66b3" \
  -H "Content-Type: application/json"
```

#### 6.2 응답 (Response) <a href="#id-v1.0-6.2-response" id="id-v1.0-6.2-response"></a>

검증 결과에 따라 달성(true) 또는 미달성(false)을 명확히 반환해야 합니다.

<table><thead><tr><th width="117">필드명</th><th width="103">타입</th><th width="86">필수</th><th>설명</th></tr></thead><tbody><tr><td>success</td><td>Boolean</td><td>Y</td><td>퀘스트 달성 여부 (true: 달성, false: 미달성)</td></tr><tr><td>message</td><td>String</td><td>Y</td><td>결과 메시지. 실패 시 사유 포함 권장(운영 확인용이며 유저에게 그대로 노출되지 않습니다)</td></tr></tbody></table>

#### 성공 - 퀘스트 달성

```
{
  "success": true,
  "message": "Quest 1 Complete"
}
```

#### 실패 - 퀘스트 미달성

```
{
  "success": false,
  "message": "조건을 만족하지 못했습니다. (현재 레벨: 25)"
}
```

#### 실패 - 존재하지 않는 유저

```
{
  "success": false,
  "message": "존재하지 않는 유저 ID입니다."
}
```

## 7. 예외 처리 및 응답 코드 <a href="#id-v1.0-7" id="id-v1.0-7"></a>

정상적인 검증 로직 수행이 불가능한 경우(서버 점검 등)에는 적절한 HTTP 상태 코드를 반환해야 합니다.

<table><thead><tr><th width="116">HTTP Code</th><th width="181">상태 (Status)</th><th width="227">설명 및 처리 가이드</th><th>원퀘스트 측 유저 안내</th></tr></thead><tbody><tr><td>200</td><td>OK</td><td>정상 처리. Body 의 <code>success</code> 값으로 달성/미달성 판별</td><td>달성: 리워드 지급 / 미달성: 조건 미충족 안내</td></tr><tr><td>401 / 403</td><td>Unauthorized / Forbidden</td><td>허용되지 않은 IP 에서의 요청 (보안 차단)</td><td>일시적으로 확인할 수 없음. <br>원퀘스트 운영 알림 대상(허용 IP 누락 의심)</td></tr><tr><td>500</td><td>Internal Server Error</td><td>게임사 서버 내부 오류</td><td>일시적으로 확인할 수 없음</td></tr><tr><td>503</td><td>Service Unavailable</td><td>서버 점검 또는 일시적 서비스 불가. <strong>점검 시 타임아웃을 기다리지 않고 즉시 503 을 반환</strong>해야 합니다</td><td>"게임 점검 중" 안내</td></tr></tbody></table>

{% hint style="danger" %}
**4xx 를 "미달성" 의 표현으로 쓰지 마세요.**

원퀘스트는 `200 + success=false` 만 미달성으로 판정하고, 그 외 4xx 는 전부 일시 오류로 처리합니다 (401/403 이 허용 IP 누락을 뜻하므로 구분할 수 없습니다). **존재하지 않는 유저, 파라미터 형식 오류도 404/400 이 아니라 `200 + success=false`** 로 응답 부탁드립니다.
{% endhint %}

#### **원퀘스트 서버의 호출 정책**

<table><thead><tr><th width="220">항목</th><th width="218">값</th><th>비고</th></tr></thead><tbody><tr><td>타임아웃</td><td>connect 1초 / read 3초</td><td>초과 시 실패(일시적으로 확인 불가) 처리. SLA 500ms 를 지키면 도달하지 않는 값입니다</td></tr><tr><td>재시도</td><td>없음 (1회 호출)</td><td>유저가 다시 시도하면 새 호출이 발생합니다. 검증 API 가 <strong>조회 전용</strong>이어야 하는 이유입니다</td></tr><tr><td>리다이렉트</td><td>3xx 미추적 — 실패 처리</td><td>등록 URL 이 최종 URL 이어야 합니다</td></tr><tr><td>2xx 이지만 본문이 JSON 이 아니거나 <code>success</code> 가 없음</td><td>실패 처리</td><td>빈 본문 포함</td></tr><tr><td>장애 격리</td><td>게임사별 차단</td><td>특정 게임사 API 실패가 누적되면 일정 시간 호출을 차단하고 유저에게 일시 확인 불가를 안내합니다. 다른 게임사 퀘스트에는 영향이 없습니다</td></tr></tbody></table>

## 8. 구현 예시 <a href="#id-v1.0-8" id="id-v1.0-8"></a>

상황: 유저(`game_user_id` = 13fc-...)가 '레벨 30 달성 (게임사 Quest ID: 1)' 퀘스트를 완료하고 보상을 요청

{% stepper %}
{% step %}

#### 유저 유효성 확인 (최초 연동 시 1회)

* 원퀘스트 요청: `GET /onequest/users/validate?game_user_id=13f664fc-...`
* 게임사 응답: `{"success": true}`
* 결과: 유효한 유저 확인. 원스토어 계정과 연동 저장
  {% endstep %}

{% step %}

#### 인게임 액션 달성 검증

* 원퀘스트 요청: `GET /onequest/quests/1/verify?game_user_id=13f664fc-...` (Source IP: `211.188.201.250`)
* 게임사 서버 로직: (1) Source IP 가 허용 목록에 있는지 확인 → Pass (2) DB 조회: 해당 유저의 레벨 확인 → Lv.32 (조건 충족)
* 게임사 응답: `{"success": true, "message": "Quest Complete"}`
  {% endstep %}

{% step %}

#### 최종 처리

* 원퀘스트: 같은 유저·같은 퀘스트는 1회만 지급됩니다
  {% endstep %}
  {% endstepper %}

## 9. 연동 체크리스트 <a href="#id-v1.0-9" id="id-v1.0-9"></a>

* [ ] &#x20;`game_user_id` 를 UUID(36자) 형식으로 발급·저장하고 있다 (순차 번호·이메일 아님)
* [ ] 두 API 가 DNS 도메인(호스트명)으로 제공된다 (HTTPS 권장 — HTTP 사용 시 별도 협의)
* [ ] 두 API 모두 `game_user_id` 를 쿼리 파라미터로 수신한다 (HTTP 메서드 무관)
* [ ] 응답 본문이 규격(`success` 필수, `message`/`joined_at`)과 일치한다
* [ ] 유저 없음·형식 오류를 404/400 이 아니라 `200 + success=false` 로 응답한다
* [ ] 응답이 500ms 이내에 완료된다 (DB 조회 인덱스·캐시 확인)
* [ ] 점검 시 즉시 503 을 반환한다
* [ ] 검증 API 가 조회 전용이어서 반복 호출에도 상태가 바뀌지 않는다
* [ ] 원퀘스트 발송 IP(개발 `211.188.207.190` / 운영 `211.188.201.250`)를 방화벽 인바운드에 등록했다
* [ ] 미등록 IP 요청을 401/403 으로 차단한다
* [ ] 엔드포인트 URL 이 리다이렉트 없는 최종 URL 이다
* [ ] 엔드포인트 URL(개발/운영)을 ONEconsole 에 등록하고 통신 테스트를 통과했다

{% hint style="info" %}
추가  원퀘스트 개발 연동 관련 문의는 [**quest@onestorecorp.com**](mailto:quest@onestorecorp.com) 으로 부탁 드립니다.
{% endhint %}