API 규격서

본 문서에서는 Game8 Store와 연동하기 위한 API 사양을 설명합니다.

API 목록

퍼블리셔 측에서 구현해 주시는 API

Game8 Store에서 요청이 전송됩니다.

Game8 Store 측에서 제공하는 API

퍼블리셔 측에서 Game8 Store로 요청을 전송합니다.

1. 공통 사양

1.1. 요청 사양

요청 헤더

1.2. 응답 사양

공통 응답 헤더

공통 응답 바디

1.3. X-Signature 설정

요청이 정상적인 것인지 판별하기 위해, 게임별로 발급된 시크릿 키를 사용하여 서명하고 요청 헤더에 설정합니다.

서명 설정 방법

1. GET의 경우 쿼리 문자열, POST의 경우 요청 바디의 내용으로 다이제스트를 계산합니다. 다이제스트는 시크릿 키의 시크릿을 이용하여 HMAC-SHA256으로 산출합니다.

1. 산출한 다이제스트를 Base64로 인코딩하여 요청 헤더의 X-Signature에 설정합니다.

서명 검증 방법

1. GET의 경우 쿼리 문자열, POST의 경우 요청 바디의 내용으로 다이제스트를 계산합니다. 다이제스트는 시크릿 키의 시크릿을 이용하여 HMAC-SHA256으로 산출합니다.

1. 산출한 다이제스트를 Base64로 인코딩하여 요청 헤더의 X-Signature 내용과 일치하는지 검증합니다.
   1. 일치하는 경우 정상적인 요청으로 처리를 수행합니다.
   2. 불일치하는 경우 부정한 요청으로 간주하여 에러를 반환합니다.

시크릿 키 취득 방법

시크릿 키는 Game8, Inc.에서 생성하여 공유해 드립니다.

2. 퍼블리셔 측에서 구현해 주시는 API 상세

2.1. 아이템 구매 가능 여부 확인（GET /check）필수

개요

게임 내 아이템을 구매할 수 있는지 확인하고, 연령 제한이나 구매 상한을 고려한 결과를 반환.
또한 수량 한정 등의 아이템 구매 시 결제까지의 시간 차로 인한 구매 중단을 피하기 위해, transaction id를 설정하여 대상 아이템을 확보.

요청 사양

요청 헤더

쿼리 파라미터

요청 예

GET /check HTTP/1.1
Host: <퍼블리셔 임의>
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
X-Signature: <SIGNED_DATA>
Query Parameter:
  ?game=game123&user=user456&transaction_id=txn_123456&item=item789&item_category=paid&price=500

응답 사양

응답 바디

account_limit의 구조

stock의 구조

응답 예（구매 가능）

{
  "request_id": "abc123",
  "timestamp": "2025-02-04T12:34:56Z",
  "result_code": "PUB0000",
  "message": "구매 가능",
  "purchasable": "available",
  "age_category": "under_15",
  "account_limit": {
    "total": 10000,
    "remaining": 9000,
    "reset_at": "2025-03-01T00:00:00Z"
  },
  "stock": {
    "total": 10,
    "remaining": 9,
    "restock_interval": "daily",
    "restock_at": "2025-02-05T00:00:00Z"
  },
  "requested_price": 500
}

응답 예（구매 불가 - 연령 인증 미제출）

{
  "request_id": "abc124",
  "timestamp": "2025-02-04T12:35:00Z",
  "result_code": "PUB2006",
  "message": "연령 인증이 완료되지 않아 구매할 수 없습니다.",
  "purchasable": "unavailable",
  "age_category": "unset",
  "account_limit": null,
  "stock": null,
  "requested_price": 500
}

응답 예（구매 불가 - 구매 한도 초과）

{
  "request_id": "abc125",
  "timestamp": "2025-02-04T12:36:00Z",
  "result_code": "PUB2005",
  "message": "구매 한도의 상한에 도달했습니다.",
  "purchasable": "unavailable",
  "age_category": "under_18",
  "account_limit": {
    "total": 10000,
    "remaining": 0,
    "reset_at": "2025-03-01T00:00:00Z"
  },
  "stock": {
    "total": 10,
    "remaining": 9,
    "restock_interval": "daily",
    "restock_at": "2025-02-05T00:00:00Z"
  },
  "requested_price": 500
}

응답 예（구매 불가 - 아이템 미판매）

{
  "request_id": "abc125",
  "timestamp": "2025-02-04T12:36:00Z",
  "result_code": "PUB2007",
  "message": "대상 아이템은 판매 불가 상태입니다.",
  "purchasable": "unavailable",
  "age_category": "under_18",
  "account_limit": {
    "total": 10000,
    "remaining": 9000,
    "reset_at": "2025-03-01T00:00:00Z"
  },
  "stock": {
    "total": 10,
    "remaining": 9,
    "restock_interval": "daily",
    "restock_at": "2025-02-05T00:00:00Z"
  },
  "requested_price": 500
}

응답 예（구매 불가 - 점검 중）

{
  "request_id": "abc125",
  "timestamp": "2025-02-04T12:36:00Z",
  "result_code": "PUB6000",
  "message": "서비스 점검 중입니다.",
  "purchasable": "maintenance",
  "age_category": "under_18",
  "account_limit": {
    "total": 10000,
    "remaining": 9000,
    "reset_at": "2025-03-01T00:00:00Z"
  },
  "stock": {
    "total": 10,
    "remaining": 9,
    "restock_interval": "daily",
    "restock_at": "2025-02-05T00:00:00Z"
  },
  "requested_price": 500
}

2.2. 아이템 구매 실적 등록（POST /register）필수

개요

구매 완료 후 게임 내 아이템을 증가시키기 위한 처리.

요청 사양

요청 헤더

요청 바디

contents 배열의 구조

요청 예

POST /register HTTP/1.1
Host: <퍼블리셔 임의>
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
X-Signature: <SIGNED_DATA>

{
  "game": "game123",
  "user": "user456",
  "transaction_id": "txn789",
  "item": "pack001",
  "item_category": "paid",
  "item_name": "젬 1000개",
  "price": 5000,
  "selling_price": 5000,
  "billing_amount": 5000,
  "purchased_at": "2025-02-04T12:36:00Z",
  "ref": "game8.jp",
  "payment_method": "Card",
  "contents": [
    {
      "content_id": "pack001-1",
      "content_name": "젬",
      "quantity": 1000
    },
    {
      "content_id": "pack001-2",
      "content_name": "보너스 금화",
      "quantity": 100
    }
  ]
}

응답 사양

응답 바디

응답 예（성공）

{
  "request_id": "def456",
  "timestamp": "2025-02-04T12:36:00Z",
  "result_code": "PUB0000",
  "message": "구매 실적을 등록했습니다.",
  "item_granted": true
}

응답 예（실패 - 사용자 불명）

{
  "request_id": "def458",
  "timestamp": "2025-02-04T12:38:00Z",
  "result_code": "PUB3002",
  "message": "지정된 사용자는 존재하지 않습니다.",
  "item_granted": false
}

응답 예시(실패 - 이미 등록됨)

{
  "request_id": "def458",
  "timestamp": "2025-02-04T12:38:00Z",
  "result_code": "PUB3004",
  "message": "지정된 TransactionID는 이미 등록되어 있습니다.",
  "item_granted": false
}

2.3. 플레이어 정보 조회（GET /user_info）필수

개요

사용자가 입력한 게임 내 ID를 바탕으로 플레이어 이름과 레벨 정보를 조회합니다. 조회한 정보를 구매 확인 화면에 표시함으로써 사용자는 입력한 ID의 정확성과 게임과의 연결이 정상인지 확인할 수 있습니다.

요청 사양

요청 헤더

쿼리 파라미터

요청 예

GET /user_info HTTP/1.1
Host: <퍼블리셔 임의>
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
X-Signature: <SIGNED_DATA>
Query Parameter:
  ?game=game123&user=Player5678

응답 사양

응답 바디

user_name 의 마스킹 예시

응답 예（성공）

{
  "request_id": "abc123",
  "timestamp": "2025-03-12T14:30:00Z",
  "result_code": "PUB0000",
  "message": "조회 성공",
  "user_name": "****rX",
  "user_level": 45
}

응답 예시(실패 - 플레이어 ID를 찾을 수 없음)

{
  "request_id": "abc124",
  "timestamp": "2025-03-12T14:31:00Z",
  "result_code": "PUB2004",
  "message": "플레이어 ID를 찾을 수 없습니다."
}

응답 예시(실패 - 계정이 BAN 등으로 인해 비활성 상태)

{
  "request_id": "abc124",
  "timestamp": "2025-03-12T14:31:00Z",
  "result_code": "PUB2008",
  "message": "계정 정지로 인해 구매할 수 없습니다."
}

응답 예시(실패 - 서버 점검 중)

{
  "request_id": "abc125",
  "timestamp": "2025-03-12T14:32:00Z",
  "result_code": "PUB6000",
  "message": "서비스 점검 중입니다."
}

2.4. 재고 확인（GET /stock）권장

개요

지정된 아이템의 재고 상황을 확인하고 구매 가능한 잔여 수량을 반환합니다.
수량 한정 상품이나 캠페인 상품 등 재고 관리가 필요한 아이템에 대해, 사용자에게 재고 상황을 표시하거나 구매 플로우 시작 전 사전 확인에 사용합니다.

요청 사양

요청 헤더

쿼리 파라미터

요청 예

GET /stock HTTP/1.1
Host: <퍼블리셔 임의>
Authorization: Bearer <ACCESS_TOKEN>
Content-Type: application/json
X-Signature: <SIGNED_DATA>
Query Parameter:
	?game=game123&user=user456&transaction_id=txn_123456&items=item789,item012

응답 사양

응답 바디

stock의 구조

응답 예시(재고 있음)

{
	"request_id": "abc123",
	"timestamp": "2025-02-04T12:34:56Z",
	"result_code": "PUB0000",
	"message": "성공",
	"stock": [
	  {
		  "item": "item789",
		  "total": 10,
		  "remaining": 8,
		  "restock_at": null
	  }
	]
}

응답 예시(재고 없음)

{
	"request_id": "abc124",
	"timestamp": "2025-02-04T12:35:00Z",
	"result_code": "PUB2009",
	"message": "아이템 구매 수량 제한의 상한에 도달함",
	"stock": [
	  {
		  "item": "item789",
		  "total": 10,
		  "remaining": 0,
		  "restock_at": null
	  }
	]
}

응답 예시(무제한 재고)

{
	"request_id": "abc124",
	"timestamp": "2025-02-04T12:36:00Z",
	"result_code": "PUB0000",
	"message": "성공",
	"stock": [
	  {
	    "item": "item789",
		  "total": -1,
		  "remaining": -1,
		  "restock_at": null
	  }
	]
}

3. Game8 Store 측에서 제공하는 API 상세

3.1. 주문 조회（GET /orders/verify）사용 선택

개요

/register API로 통지한 주문의 상태를 paid_transaction_id 를 사용하여 조회하기 위한 API입니다.
/register API에서 사용한 transaction_id 와 동일한 값을 paid_transaction_id 로 지정해 주십시오.
다음과 같은 사용 사례를 상정하고 있습니다:

• /register 수신 후 주문 상태 확인
• API 호출 실패 시 재조회

이를 통해 통지(/register) + 조회(/orders/verify)의 이중 확인이 가능해집니다.

본 API는 Game8 Store 측에서 상시 가동되고 있으며, 사전 신청은 필요하지 않습니다. 퍼블리셔 측에서 엔드포인트를 준비할 필요는 없으며, 이용하는 경우 본 API를 호출하는 처리만 구현하시면 됩니다. 결제 플로우에 포함하지 않은 경우에도 요청을 전송하면 주문의 결제 상태를 확인할 수 있습니다(이용은 임의입니다).

요청 사양

요청 헤더

쿼리 파라미터

요청 예

GET /api/public/marketplace/publishers/example-publisher/games/example-game/orders/verify HTTP/1.1
Host: <Game8가 지정>
Authorization: Bearer <ACCESS_TOKEN>
X-Signature: <SIGNED_DATA>
Query Parameter:
  ?paid_transaction_id=txn_123456

응답 사양

응답 본문(성공 시)

status의 값

응답 예시(성공 - 완료된 주문)

{
  "request_id": "abc123",
  "timestamp": "2025-04-01T12:00:00+09:00",
  "result_code": "PUB0000",
  "message": "성공",
  "paid_transaction_id": "txn_123456",
  "status": "completed",
  "item_id": "item789",
  "price": 1000,
  "selling_price": 900,
  "billing_amount": 800,
  "purchased_at": "2025-04-01T12:00:00+09:00"
}

응답 예시(성공 - 결제 처리 중)

{
  "request_id": "abc124",
  "timestamp": "2025-04-01T12:00:01+09:00",
  "result_code": "PUB0000",
  "message": "성공",
  "paid_transaction_id": "txn_123456",
  "status": "pending",
  "item_id": "item789",
  "price": 1000,
  "selling_price": 1000,
  "billing_amount": 1000,
  "purchased_at": null
}

오류 응답

오류 발생 시에는 공통 응답 본문만 반환됩니다:

{
  "request_id": "<요청ID>",
  "timestamp": "<타임스탬프>",
  "result_code": "<오류 코드>",
  "message": "<오류 메시지>"
}

응답 예시(오류 - 인증 실패)

{
  "request_id": "abc125",
  "timestamp": "2025-04-01T12:00:02+09:00",
  "result_code": "PUB1002",
  "message": "인증 또는 서명 검증에 실패했습니다"
}

응답 예시(오류 - 주문을 찾을 수 없음)

{
  "request_id": "abc126",
  "timestamp": "2025-04-01T12:00:03+09:00",
  "result_code": "PUB3001",
  "message": "지정된 주문을 찾을 수 없습니다"
}

4. 에러 핸들링

4.1. 에러 코드 목록

4.2. 에러 핸들링 권장 플로우

1. result_code 를 확인
   • PUB0000(성공)이면 정상 처리합니다.
   • 그 외의 경우 오류의 종류를 판정합니다.
2. 클라이언트 측에서 수정 가능한 오류인지 확인
   • PUB1000 계열, PUB2000 계열은 요청 내용 수정으로 대응할 수 있습니다.
   • PUB3000 계열은 데이터의 정합성을 확인합니다.
3. 재시도 가능한 오류인지 확인
   • PUB4000, PUB4001 는 일시적인 오류일 가능성이 있으므로 몇 초 후 재시도합니다.
4. 오류 메시지 기록·통지
   • 알 수 없는 오류(PUB5000)는 로그를 남기고 개발팀에 보고합니다.

4.3. 재시도 정책

이 오류 처리 목록을 참고하여 적절한 오류 처리를 구현해 주십시오.