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

# 유효성 검증

사용자가 입력한 게임 ID와 서버 정보의 유효성을 확인하고, 해당 아이템의 구매 가능 여부를 검증합니다.

* 게임 ID는 아이템을 지급받을 최종 대상(유저/캐릭터)을 식별하는 값이며, ONEshop에서는 `serviceUserId`로 전달됩니다.\
  *<mark style="color:$info;">(게임 구조에 따라 UID 또는 캐릭터 ID 등으로 사용될 수 있습니다.)</mark>*
* ONEshop은 사용자의 게임 계정 정보를 보유하지 않으며, 게임 서버의 응답 결과에 따라 구매 진행 여부를 결정합니다. 게임 서버는 전달받은 게임 ID·서버가 실제로 존재하는지, 아이템을 구매할 수 있는지 반드시 확인한 뒤 응답해 주세요.

{% hint style="info" %}
유효성 검증 URL이 등록되지 않은 타이틀은 결제를 진행할 수 없습니다. URL은 `ONEconsole > Webshop > 개발자 > 서버 연동` 메뉴에서 등록할 수 있습니다.
{% endhint %}

**호출 시점**

유효성 검증은 사용자가 게임 ID를 입력하는 시점과 아이템을 구매하는 시점에 각각 호출됩니다. 두 요청은 `param.prodId` 포함 여부로 구분할 수 있습니다.

<table><thead><tr><th width="160">시점</th><th width="200">param.prodId</th><th>게임 서버 처리</th></tr></thead><tbody><tr><td>UID 로그인</td><td>포함되지 않음</td><td><p>사용자가 웹샵에서 게임 ID(UID)를 입력하고 로그인할 때 호출됩니다. 게임 ID·서버의 유효성만 확인해 응답해 주세요.</p><ul><li>이 시점에는 아이템 정보가 없으므로 <code>0000</code> 또는 <code>1000</code>으로 응답해 주세요.</li><li>이 시점에 <code>1001</code>을 응답하면 웹샵 진행이 멈춥니다. 구매 가능 여부(<code>1001</code>)는 아이템 구매 시점에 판단해 주세요.</li></ul></td></tr><tr><td>아이템 구매</td><td>포함</td><td>사용자가 아이템 구매를 요청할 때 호출됩니다. 게임 ID·서버의 유효성과 해당 아이템의 구매 가능 여부를 함께 확인해 응답해 주세요.</td></tr></tbody></table>

**Request URI**

{% hint style="warning" %}
**유의사항**

* ONEshop 보안 정책에 따라 **HTTPS 프로토콜 및 443 Port**만 지원하며, 그 외 규격 사용 시 정상 동작하지 않을 수 있습니다.
* 게임 서버는 **5초 이내**에 HTTP 200과 `Content-Type: application/json` 헤더로 응답해야 합니다. 5초를 넘기거나 HTTP 200이 아닌 상태 코드, JSON 형식이 아닌 본문으로 응답하면 연동 오류로 처리되며, ONEshop은 요청을 재시도하지 않습니다.
  {% endhint %}

<table data-header-hidden><thead><tr><th width="185"></th><th></th></tr></thead><tbody><tr><td><strong>HTTP Type</strong></td><td>HTTPS</td></tr><tr><td><strong>HTTP Method</strong></td><td><mark style="color:$primary;"><code>POST</code></mark></td></tr><tr><td><strong>URL</strong></td><td>수신 받을 서버 URL은 <code>ONEconsole > Webshop > 개발자 > 서버 연동</code> 메뉴에서 등록할 수 있습니다. 설정 방법은 서버 연동 문서를 참고해 주세요.</td></tr><tr><td><strong>Header</strong></td><td><p>Content-Type: application/json; charset=UTF-8</p><p>Accept: application/json</p></td></tr></tbody></table>

**Request**

<table><thead><tr><th width="203">Name</th><th width="134">Type</th><th width="127">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>param.clientId</code></td><td>String</td><td>M</td><td>ONEshop 타이틀 ID (예: <code>WS00000001</code>)</td></tr><tr><td><code>param.prodId</code></td><td>String</td><td>Optional</td><td><p>ONEshop 아이템 ID</p><ul><li>아이템 구매 시점에만 포함됩니다.</li><li>UID 로그인 시점의 요청에는 이 필드가 없습니다.</li></ul></td></tr><tr><td><code>param.serviceUserId</code></td><td>String</td><td>M</td><td>사용자의 게임 ID (최대 100byte)</td></tr><tr><td><code>param.serviceServerId</code></td><td>String</td><td>Optional</td><td><p>사용자의 서버 ID (최대 100byte)</p><ul><li>플레이어 식별 필드에 <code>서버 리스트</code> 타입을 설정한 경우 전달됩니다.</li></ul></td></tr><tr><td><code>param.serviceCustomFields</code></td><td>String (JSON String)</td><td>Optional</td><td><p>사용자 커스텀 필드</p><ul><li><code>ONEconsole > Webshop > 개발자 > 플레이어 식별 필드</code>에서 커스텀 필드를 추가한 경우 전달됩니다.</li><li><code>{"필드 키": "입력값"}</code> 형식의 JSON 문자열입니다.</li><li>자세한 내용은 플레이어 식별 필드를 참고해 주세요.</li></ul></td></tr><tr><td><code>signature</code></td><td>String</td><td>M</td><td><p>위변조 방지를 위한 서명</p><ul><li>서명키는 <code>ONEconsole > Webshop > 개발자 > 서버 연동</code> 메뉴의 라이선스 탭에서 확인할 수 있습니다.</li><li>서명 대상과 검증 방법은 아래 서명 검증을 참고해 주세요.</li></ul></td></tr></tbody></table>

**Example**

{% tabs %}
{% tab title="UID 로그인" %}

```bash
curl -X POST \
  'https://example.com/gameuser/check' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "param": {
      "clientId": "WS00000001",
      "serviceUserId": "USR1234567890",
      "serviceServerId": "asia01",
      "serviceCustomFields": "{\"characterId\":\"char_1001\"}"
    },
    "signature": "ajkfl;askfjkladfjksl"
  }'
```

{% endtab %}

{% tab title="아이템 구매" %}

```bash
curl -X POST \
  'https://example.com/gameuser/check' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "param": {
      "clientId": "WS00000001",
      "prodId": "item1000",
      "serviceUserId": "USR1234567890",
      "serviceServerId": "asia01",
      "serviceCustomFields": "{\"characterId\":\"char_1001\"}"
    },
    "signature": "ajkfl;askfjkladfjksl"
  }'
```

{% endtab %}
{% endtabs %}

**서명 검증**

| 항목    | 내용                                                                  |
| ----- | ------------------------------------------------------------------- |
| 알고리즘  | `SHA512withRSA`                                                     |
| 검증 키  | `ONEconsole > Webshop > 개발자 > 서버 연동` 메뉴 라이선스 탭의 라이선스 키 (Base64 공개키) |
| 서명 대상 | 요청 본문에서 `signature`를 제외한 `{"param":{...}}` 문자열 (UTF-8)              |
| 서명값   | Base64                                                              |

* 서명 검증에는 수신한 요청 본문 원문(바이트)을 그대로 사용해 주세요. JSON을 파싱한 뒤 다시 직렬화하면 필드 순서·공백·유니코드 이스케이프가 달라져 검증에 실패할 수 있으므로 권장하지 않습니다. 부득이하게 다시 직렬화하는 경우 필드 순서를 유지하고, 공백 없이, 한글 등 유니코드를 이스케이프하지 않아야 합니다.
* 값이 없는 필드(`prodId`, `serviceServerId` 등)는 요청과 서명 대상 모두에 포함되지 않습니다.
* 서명 검증에 실패하면 HTTP 200과 함께 `result.code`를 `2000`으로 응답해 주세요. `0000`·`1000`·`1001` 외의 코드는 모두 검증 실패로 처리됩니다.

**Response**

<table><thead><tr><th width="203">Name</th><th width="134">Type</th><th width="127">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><code>result.code</code></td><td>String</td><td>M</td><td><p><code>0000</code>: 성공</p><p><code>1000</code>: 비회원 (게임 서버에 등록되지 않은 게임 ID)</p><p><code>1001</code>: 구매불가</p><ul><li>위 3개 외의 값을 응답하거나 응답하지 않으면 검증 실패로 처리되어 구매가 진행되지 않습니다.</li></ul></td></tr><tr><td><code>result.message</code></td><td>String</td><td>M</td><td><ul><li><code>result.code</code>가 <code>1001</code>인 경우 사용자 화면에 표시되는 안내 메시지입니다.</li><li>대상 사용자에게 적합한 언어로 전달하는 것을 권장합니다.</li><li><p><strong>예시 문구</strong></p><ul><li>"구매 가능한 횟수를 초과하였습니다."</li><li>"이미 구매한 상품입니다."</li><li>"이벤트 기간이 종료된 상품입니다."</li></ul></li></ul></td></tr><tr><td><code>developerPayload</code></td><td>String</td><td>Optional</td><td><p>유효성 검증 응답 시 개발사가 전달하는 구매 건 식별자입니다.</p><ul><li>결제 요청에 그대로 전달되며, 결제 완료 후 PNS에도 포함되어 구매 검증에 사용됩니다.</li><li>전달하지 않으면 판매 내역에서 구매 건을 개발사 주문과 대조하기 어려우므로 전달을 권장합니다.</li></ul></td></tr></tbody></table>

**Example**

```json
// 성공
{
  "result": {
    "code": "0000",
    "message": "User found"
  },
  "developerPayload": "OS_000211234"
}

// 비회원
{
  "result": {
    "code": "1000",
    "message": "User not found"
  }
}

// 구매불가
{
  "result": {
    "code": "1001",
    "message": "구매 가능한 횟수를 초과하였습니다."
  }
}
```