콘텐츠로 이동

웹 쿠폰 교환소

쿠폰 API 서버 URL

상용 URL https://coupon.withhive.com
Sandbox URL https://sandbox-coupon.withhive.com

쿠폰 서버 IP

설명 게임 서버에서 아래 IP의 방화벽 인바운드 규칙을 해제해야 합니다.
상용 IP 13.124.83.83, 52.78.11.220, 3.34.204.168,
e 3.35.59.227, 43.202.201.239, 43.200.188.52
Sandbox IP 43.155.155.10

쿠폰 사용 API

기본사항

설명 발급된 쿠폰 사용 및 아이템 발송 처리
참고문서 Hive 식별자 정책
URL /tp/coupon/api
Method POST Response Format JSON
HTTP Header Content-type application/json 호출비율
Authorization Bearer Token (앱센터 토큰)

Request parameters

명칭 타입 필수 여부 (필수: M, 옵션: O) 설명
game_index Integer M 앱센터 게임 Index
coupon String M 쿠폰번호
cs_code String M 게임 내 사용자 CS CODE
server_id String M 아이템 지급 게임 서버 ID (예: KR)
language String O 응답 메세지 노출 언어코드
(기본값 영어 - 참고문서의 Hive 언어코드 참조) 메시지를 화면에 그대로 노출할 경우 사용
additionalinfo String O 게임 서버로 보내기 위한 추가적인 정보
(JSON String 형식으로 전달)

Response elements

명칭 타입 필수 여부 (필수: M, 옵션: O) 설명
code Integer M 응답 코드 (100: 성공)
message String M 응답 코드에 따른 결과 메시지
  • 호출 예제
curl -L -v
 -d '{"game_index":539,"coupon":"HIVESDKTEST","cs_code":"123456789","server_id":"KR","additionalinfo":"{"user_level":50,"chanel":1,"sub_sever":"1"}"}'
 -H "Content-Type: text/html"
 -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAzNzc4OTU2LCJqdGkiOiIxODczMTExMzIwIn0.OxWo4R6UdI0BLP1ckt8RlMFrPAb5H7TNedmLFV1Cawc"
 https://sandbox-coupon.withhive.com/tp/coupon/api
  • 요청 예제
>> POST /tp/coupon/api HTTP/2
> Host: sandbox-coupon.withhive.com 
> user-agent: curl/7.68.0 
> Content-Type: application/json
> Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNjAzNzc4OTU2LCJqdGkiOiIxODczMTExMzIwIn0.OxWo4R6UdI0BLP1ckt8RlMFrPAb5H7TNedmLFV1Cawc
> Accept: */*
> Content-Length: 163
  • 응답 예제
< HTTP/2 200
 < server: nginx
 < date: Wed, 23 Mar 2022 09:49:29 GMT
 < content-type: application/json; charset=utf-8
 {"code":100,"message":"The Coupon Code has been redeemed."}

Response codes (API 서버)

코드 설명 메시지
100 성공 쿠폰 사용이 완료 되었습니다.
200 요청 파라미터 오류 파라미터가 일부 없거나, 파라미터 명이 잘못 되었습니다.
202 해당 계정의 사용한도 초과 사용 가능한 쿠폰 횟수를 초과 하였습니다.
203 그룹 쿠폰의 사용제한 초과 사용 가능한 쿠폰 횟수를 초과 하였습니다!
204 발급된 쿠폰과 게임정보 미일치 해당 게임의 이벤트 쿠폰 교환소에서만 이용하실수 있습니다.
302 존재하지 않는 쿠폰 존재하지 않는 쿠폰번호 입니다. 다시 확인해 주세요.
303 사용 진행 중인 쿠폰 이미 사용된 쿠폰입니다.
304 사용 완료된 쿠폰 이미 사용된 쿠폰입니다.
305 쿠폰 사용한도 초과 (모두 사용된 고유 쿠폰) 발급된 쿠폰이 모두 사용됐습니다.
306 사용기간이 만료된 쿠폰 사용 기간이 만료된 쿠폰 입니다.
311 사용 중지된 쿠폰 사용이 중지된 쿠폰입니다.
312 사용 기간 이전 쿠폰 아직 쿠폰 사용 기간 전입니다. (테스트 쿠폰은 검증 제외)
400 아이템 전송 오류 (전체 실패) 쿠폰 사용이 실패하였습니다.
계속 실패 시 고객센터로 문의해 주세요.
401 아이템 전송 오류 (부분 실패) 쿠폰 사용이 일부 실패하였습니다.
고객센터로 문의해 주세요.
500 DB 통신 오류 쿠폰 사용이 실패하였습니다.
계속 실패 시 고객센터로 문의해 주세요.
501 서버 통신 실패 쿠폰 사용이 실패하였습니다.
계속 실패 시 고객센터로 문의해 주세요.

사용자 유효성 검사 및 게임 서버 목록 조회 API 규약

사용자 유효성을 검사하고 게임 서버 목록을 조회하기 위한 규약을 정의합니다. 이를 위해, 먼저 게임 서버에서는 쿠폰 서버 IP에 설정한 방화벽 인바운드 규칙을 해제하여 게임 서버와 쿠폰 서버 간 API 통신이 가능하게 해야 합니다.

기본 사항

설명 게임 서버에서 유효 사용자 검증 및 쿠폰 사용이 가능한 게임 서버 목록 조회를 위한 API 규약 정의
URL 콘솔 > 빌링 > Hive 쿠폰 > 웹 쿠폰 교환소 설정 > 게임 서버 API 등록
Method POST Response Format JSON
HTTP Header Content-type application/json 호출비율

Request parameters (쿠폰 서버 → 게임 서버)

명칭 타입 필수 여부 (필수: M, 옵션: O) 설명
cs_code String M 게임 내 사용자 CS CODE
server Array O Hive 콘솔에서 빌링 > Hive 쿠폰 > 웹 쿠폰교환소 설정 > 앱 선택 후 설정 > 서버 정보에서 API URL과 서버 노출 옵션이 활성화된 게임 서버 목록

Response elements (게임 서버 → 쿠폰 서버)

명칭 타입 필수 여부 (필수: M, 옵션: O) 설명
code Integer M 응답 코드 (100: 성공)
message String M 응답 코드에 따른 결과 메시지
data Object M 응답 데이터
(단, 응답이 성공일 경우에만 반환, 에러 시 미반환)
┕ default_lang String M 기본 언어 값
(해당되는 언어가 없을 경우 노출될 기본값)
┕ extra_display Integer O 쿠폰교환소 서버목록에 노출되는 서버명 뒤에 additionalinfo 값의 추가 노출 처리
(※ extra_display 값 미제공시 기본은 비노출)
(JSON 값 중 value 값만 ‘–‘ 로 구분해서 노출)
  • 0 : additionalinfo 값 전체 노출 ( 예: ASIA – 50 – PLATINUM – USER – 0 – 0 )
  • 1 이상 : additionalinfo 값 중 노출 항목 수 (예: 1 반환 시 첫번째 값인 ASIA만 노출 )
┕ server_list Array M 서버 목록
┕ server_id String M 아이템 지급 게임 서버 ID (예: KR)
┕ server_display_names Object M 쿠폰교환소 서버목록에 노출되는 서버명 다국어 정보
(※ 기본 언어 및 노출될 언어는 필수 제공)
┕ ko ~ ar String O
  •  ko : 한국어
  •  en : 영어
  •  ja : 일본어
  • zh-hans : 중국어 간체
  •  zh-hant : 중국어 번체
  •  de : 독일어
  •  fr : 프랑스어
  •  ru : 러시아어
  •  es : 스페인어
  •  pt : 포르투칼어
  •  id : 인도네시아어
  •  th : 태국어
  •  vi : 베트남어
  •  it : 이탈이아어
  •  tr : 터키어
  •  ar : 아랍어
┕ additionalinfo Object O 게임서버 추가 전달 값
(게임서버에 지급요청시 추가 전달이 필요한 값)
  • 요청 예제
{
    "cs_code": "20000013680",
    "server": [
      "kr",
      "cn",
      "en",
      "jp"
    ]
  }
  • 응답 예제
// ※ 하단의additionalinfo 값은 참고용 예시이며. 게임서버에 추가 전달이 필요한 값이 있다면 전송해주시면 됩니다.
// ※ server_display_names 값은 사용자에게 노출되는 서버 명이며, 게임서버로 요청시에는 server_id 값을 활용합니다.
{
  "code": 100,
  "message": "Success",
  "data": {
      "default_lang": "en",
      "extra_display": 0,
      "server_list": [
      {
        "server_id": "KR",
        "server_display_names": {
          "ko": "한국서버",
          "en": "Korea Server",
          "ja": "韓国サーバー",
          "zh-hans": "韓國服務器",
          "zh-hant": "韩国服务器",
          "de": "Koreanischer Server",
          "fr": "Serveur coréen",
          "ru": "Корейский сервер",
          "es": "servidor coreano",
          "pt": "servidor coreano",
          "id": "server korea",
          "th": "เซิฟเวอร์เกาหลี",
          "vi": "Máy chủ hàn quốc",
          "it": "Server coreano",
          "tr": "Kore sunucusu",
          "ar": "الخادم الكوري"
        },
        "additionalinfo": {
          "region": "ASIA",
          "user_detail": {
            "level": 50,
            "tier": "PLATINUM",
            "nickname": "USER",
            "gold": "0",
            "gem": "0"
          }
        }
      },
      ......
    ]
  }
}
// 파라미터가 잘못되어 에러가 발생한 경우
{
  "code": 200,
"message": "No parameter, or invalid parameter name."
}
// 유효하지 않는 사용자 정보 (CS_CODE) 일 경우
{
  "code": 201,
"message": "No data, or invalid cs_code."
}
  • 게임 적용 예시 화면
    • 게임 서버에서 전송한 문자열을 그대로 서버 선택 UI에 노출

크리에이터 쿠폰 유효성 검사 API 규약

기본사항

설명 크리에이터 서버 또는 게임 서버에서 크리에이터 유효 쿠폰 검증 API 규약 정의
URL 콘솔 > 빌링 > Hive 쿠폰 > 웹 쿠폰교환소 설정 > 웹 쿠폰 교환소 크리에이터 API 등록
Method POST Response Format JSON
HTTP Header Content-type application/json

Request parameters (쿠폰 서버 → 크리에이터(게임) 서버)

명칭 타입 필수 여부 (필수: M, 옵션: O) 설명
cs_code String M 게임 내 사용자 CS CODE
coupon_code String M 쿠폰 번호
additionalinfo Object O 크리에이터 서버 또는 게임 서버에 추가로 전달하는 값

Response elements (크리에이터(게임) 서버 → 쿠폰 서버)

명칭 타입 필수 여부 (필수: M, 옵션: O) 설명
code Integer M 응답 코드 (100: 성공)
message String M 응답 코드에 따른 결과 메시지
  • 요청 예제
{
  "cs_code": "20000013680",
  "coupon_code”: “ABCD"
}
  • 응답 예제
// 성공
{
    "code":100, "message": "Success"
}
// 잘못된 파라미터로 에러가 발생한 경우
{
    "code":200, "message": "No parameter, or invalid parameter name."
}
// 크리에이터로부터 받은 쿠폰이 유효하지 않은 쿠폰일 경우
{
    "code":201, "message": "No data, or invalid creator."
}
  • (PC 화면)사용할 수 없는 쿠폰일 경우