쿠폰 API

쿠폰 기능에서 앱 서버 또는 웹 쿠폰 교환소가 직접 호출하는 Hive Axyl Server API를 설명합니다. 이 API는 플레이어가 입력한 쿠폰 코드를 검증하고, 쿠폰에 설정된 아이템을 플레이어 우편함으로 지급합니다.

쿠폰 사용

POST /coupon/v1/redeem

플레이어가 입력한 쿠폰 코드를 사용 처리합니다.

쿠폰에 설정된 아이템을 플레이어 우편함으로 지급하고 우편 접수번호(mailId)를 반환합니다.

API 호출 전 준비

항목	값
호출 주체	`앱 서버` 또는 `웹 쿠폰 교환소`
기본 URL	운영: `https://commerce-api.hiveaxyl.com` 테스트: `https://test-api.hiveaxyl.com`
인증	`Authorization: Bearer {access-token}`

Warning

인증 헤더에는 토큰 발급 또는 로그인 절차로 받은 Bearer 액세스 토큰을 넣습니다. 액세스 토큰은 요청 권한과 대상 앱을 검증하는 데 사용하므로, 로그나 오류 메시지에 남기지 마세요.

지급 우편

지급 완료 기준 — 우편함이 지급 요청을 접수한 시점에 성공으로 처리됩니다. 아이템의 실제 수령 여부는 앱 서버가 우편함에서 별도로 확인해야 합니다.
언어 — 요청의 Accept-Language 헤더를 따릅니다. 지원하지 않는 언어이거나 헤더가 없으면 한국어(ko)로 발송합니다.
카테고리(mailCategory) — 지정하지 않으므로 우편함 기본값(DEFAULT)으로 발송됩니다.
확장 정보(mailExtension) — 다음 필드를 담은 JSON 문자열이 실립니다. 우편함은 이 값을 해석하지 않고 그대로 보관하므로, 앱 서버가 우편 수령 처리 시 읽어서 사용할 수 있습니다.
- couponId — 사용된 쿠폰의 식별자(UUID)

호출 Parameters

이름	위치	타입	필수	설명
`X-App-Id`	`header`	`string`	`true`	프로젝트 식별 헤더입니다.
`X-SDK-Version`	`header`	`string`	`false`	클라이언트 SDK 버전 정보입니다.
`X-Platform`	`header`	`string`	`false`	플랫폼 정보입니다. 예: `Android`, `iOS`, `STEAM`
`X-OS-Version`	`header`	`string`	`false`	운영 체제 버전 정보입니다.
`Accept-Language`	`header`	`string`	`false`	클라이언트 언어 설정입니다. 예: `en-US`, `ko-KR`
`traceparent`	`header`	`string`	`false`	분산 추적을 위한 W3C Trace Context 헤더입니다.
`User-Agent`	`header`	`string`	`false`	클라이언트 애플리케이션의 User-Agent 정보입니다.
body	body	`CouponRedeemRequest`	`true`	쿠폰 사용 요청 정보입니다.

요청 본문 CouponRedeemRequest

필드	타입	필수	설명
`couponCode`	`string`	`true`	쿠폰 코드입니다. 영문과 숫자를 사용하며, 하이픈을 포함한 전체 길이는 8~20자여야 합니다. 입력 편의를 위한 하이픈(예: `1234-ABCD`)은 서버에서 제거한 뒤 검증하므로 포함해 보내도 됩니다. 대소문자는 구분하지 않습니다.

호출 예시

curl

curl -X POST 'https://test-api.hiveaxyl.com/coupon/v1/redeem' \
  -H 'Authorization: Bearer {access-token}' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'X-App-Id: app.example.game' \
  -H 'X-SDK-Version: 4.23.1' \
  -H 'X-Platform: app.example.game' \
  -H 'X-OS-Version: Android 12' \
  -H 'Accept-Language: en-US' \
  -H 'traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01' \
  -H 'User-Agent: HiveAxylClient/1.0 (Android 12; Mobile)' \
  -d '{
    "couponCode": "ABCD1234EFGH"
  }'

응답

공통 data, meta, 오류 본문, 제품 공통 오류 코드는 응답 및 오류를 참조하세요. 이 섹션에서는 이 API가 실제로 반환하는 객체와 API별 처리 방법을 설명합니다.

성공 응답 data 객체

필드	타입	설명
`data.mailId`	`string`	우편 접수번호입니다.

응답 예시

200 OKAccountLimitExceededAlreadyUsedBeforeStartCodeInvalidFormatCodeNotFoundCouponDisabledExpiredGroupLimitExceededTotalLimitExceededInternalError

{
  "data": {
    "mailId": "0196f7c3-8b2e-7f4d-a123-9c8d7e6f5a4b"
  },
  "meta": null
}

{
  "code": "coupon_account_limit_exceeded",
  "detail": "The per-account usage limit has been exceeded.",
  "instance": "/coupon/v1/redeem",
  "outcome": {
    "code": 3001,
    "message": "The per-account usage limit has been exceeded."
  },
  "status": 400,
  "title": "Account Limit Exceeded",
  "type": "/errors/coupon/coupon-account-limit-exceeded"
}

{
  "code": "coupon_already_used",
  "detail": "This coupon has already been used.",
  "instance": "/coupon/v1/redeem",
  "outcome": {
    "code": 2005,
    "message": "This coupon has already been used."
  },
  "status": 400,
  "title": "Already Used",
  "type": "/errors/coupon/coupon-already-used"
}

{
  "code": "coupon_before_start",
  "detail": "The coupon is not yet available for use.",
  "instance": "/coupon/v1/redeem",
  "outcome": {
    "code": 2001,
    "message": "The coupon is not yet available for use."
  },
  "status": 400,
  "title": "Before Start",
  "type": "/errors/coupon/coupon-before-start"
}

{
  "code": "coupon_code_invalid_format",
  "detail": "The coupon code format is invalid.",
  "instance": "/coupon/v1/redeem",
  "outcome": {
    "code": 1002,
    "message": "The coupon code format is invalid."
  },
  "status": 400,
  "title": "Code Invalid Format",
  "type": "/errors/coupon/coupon-code-invalid-format"
}

{
  "code": "coupon_code_not_found",
  "detail": "The coupon code does not exist or has been deleted.",
  "instance": "/coupon/v1/redeem",
  "outcome": {
    "code": 1001,
    "message": "The coupon code does not exist or has been deleted."
  },
  "status": 400,
  "title": "Code Not Found",
  "type": "/errors/coupon/coupon-code-not-found"
}

{
  "code": "coupon_disabled",
  "detail": "The coupon or coupon code is disabled.",
  "instance": "/coupon/v1/redeem",
  "outcome": {
    "code": 1003,
    "message": "The coupon or coupon code is disabled."
  },
  "status": 400,
  "title": "Coupon Disabled",
  "type": "/errors/coupon/coupon-disabled"
}

{
  "code": "coupon_expired",
  "detail": "The coupon usage period has expired.",
  "instance": "/coupon/v1/redeem",
  "outcome": {
    "code": 2002,
    "message": "The coupon usage period has expired."
  },
  "status": 400,
  "title": "Expired",
  "type": "/errors/coupon/coupon-expired"
}

{
  "code": "coupon_group_limit_exceeded",
  "detail": "The per-group usage limit has been exceeded.",
  "instance": "/coupon/v1/redeem",
  "outcome": {
    "code": 3002,
    "message": "The per-group usage limit has been exceeded."
  },
  "status": 400,
  "title": "Group Limit Exceeded",
  "type": "/errors/coupon/coupon-group-limit-exceeded"
}

{
  "code": "coupon_total_limit_exceeded",
  "detail": "The total usage limit for this code has been exceeded.",
  "instance": "/coupon/v1/redeem",
  "outcome": {
    "code": 3003,
    "message": "The total usage limit for this code has been exceeded."
  },
  "status": 400,
  "title": "Total Limit Exceeded",
  "type": "/errors/coupon/coupon-total-limit-exceeded"
}

{
  "code": "internal_error",
  "detail": "An unexpected error occurred.",
  "instance": "/coupon/v1/redeem",
  "status": 500,
  "title": "Internal Server Error",
  "type": "/errors/common/internal-error"
}

API별 처리 시 유의 사항

쿠폰 사용에 실패할 경우 HTTP 400 응답과 함께 상세 에러 코드(outcome.code)를 반환합니다. 검증은 형식 → 존재 → 사용 조건 → 사용 여부·한도 순으로 수행하며, 여러 오류 조건에 동시에 해당하면 우선순위가 가장 높은 에러 하나만 반환합니다.

응답 상태

상태	콘텐츠 유형	의미	응답 헤더	응답 본문 또는 처리
`200`	`application/json`	쿠폰 사용 성공	-	`data.mailId`에 우편 접수번호가 담깁니다.
`400`	`application/problem+json`	쿠폰 코드·사용 조건·사용 한도 검증 실패	-	`code`와 `outcome.code`로 실패 원인을 확인합니다.
`500`	`application/problem+json`	서버 에러	-	DB 처리 실패, 우편함 지급 실패 등입니다. 쿠폰은 사용되지 않은 상태로 복구됩니다.

API별 오류 코드

코드	`outcome.code`	발생 조건	처리 방법
`coupon_code_not_found`	`1001`	존재하지 않거나 삭제된 쿠폰 코드입니다.	쿠폰 코드를 다시 확인하도록 안내하세요.
`coupon_code_invalid_format`	`1002`	쿠폰 코드 형식이 올바르지 않습니다.	영숫자 8~20자 형식인지 확인하세요.
`coupon_disabled`	`1003`	비활성화된 쿠폰 또는 코드입니다.	쿠폰 운영 상태를 확인하세요.
`coupon_before_start`	`2001`	아직 사용 시작 전인 쿠폰입니다.	쿠폰 사용 시작 시간을 확인하세요.
`coupon_expired`	`2002`	사용 기간이 만료된 쿠폰입니다.	사용 가능한 쿠폰인지 확인하세요.
`coupon_already_used`	`2005`	이미 사용된 쿠폰입니다.	사용 이력을 확인하세요.
`coupon_account_limit_exceeded`	`3001`	계정당 사용 한도를 초과했습니다.	같은 계정에서 이미 사용했는지 확인하세요.
`coupon_group_limit_exceeded`	`3002`	그룹 사용 한도를 초과했습니다.	쿠폰 그룹의 사용 한도를 확인하세요.
`coupon_total_limit_exceeded`	`3003`	이 코드의 총 사용 한도를 초과했습니다.	쿠폰 코드의 전체 사용 한도를 확인하세요.