쿠폰 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,
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 | 응답 코드에 따른 결과 메시지 |
- 호출 예제
12345curl -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
- 요청 예제
1234567>> 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
- 응답 예제
12345< 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 값만 ‘–‘ 로 구분해서 노출)
|
| ┕ 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 | 게임서버 추가 전달 값 (게임서버에 지급요청시 추가 전달이 필요한 값) |
- 요청 예제
123456789{"cs_code": "20000013680","server": ["kr","cn","en","jp"]} - 응답 예제
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657// ※ 하단의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 | 응답 코드에 따른 결과 메시지 |
- 요청 예제
1234{"cs_code": "20000013680","coupon_code”: “ABCD"} - 응답 예제
1234567891011121314// 성공{"code":100, "message": "Success"}// 잘못된 파라미터로 에러가 발생한 경우{"code":200, "message": "No parameter, or invalid parameter name."}// 크리에이터로부터 받은 쿠폰이 유효하지 않은 쿠폰일 경우{"code":201, "message": "No data, or invalid creator."} -
(PC 화면)사용할 수 없는 쿠폰일 경우
