ICouponService

앱 사용자가 입력한 쿠폰 코드를 Hive Axyl 서버에서 사용 처리하는 서비스입니다. 쿠폰을 사용하면 쿠폰의 아이템을 담은 우편이 로그인한 사용자의 우편함으로 발송됩니다.

인터페이스: ICouponService
네임스페이스: Hive.Axyl.Coupon
패키지: com.com2usplatform.hiveaxyl.coupon

등록과 획득

Unity

using Hive.Axyl.Core;
using Hive.Axyl.Core.Unity;   // HiveBootstrap
using Hive.Axyl.Coupon;

var config = CoreConfig.CreateBuilder("{appId}").Build();

HiveBootstrap.Initialize(config, builder =>
{
    builder.AddCoupon();
});

ICouponService coupon = HiveCore.Resolve<ICouponService>();

메서드 요약

'인증' 열의 의미는 인증 요구 표기를 참조하세요.

메서드	인증	설명
RedeemCouponAsync	세션 필요	쿠폰 코드를 사용 처리하고 쿠폰의 아이템을 우편함으로 지급합니다.

공통 파라미터

모든 메서드의 마지막 파라미터는 ApiCallContext? context = null입니다. 생략하면 기본값이 적용됩니다. 자세한 내용은 호출 컨텍스트를 참조하세요.

모든 메서드는 요청 본문을 request 파라미터로 받으며, request는 Required입니다. 아래 메서드 설명에서는 요청 타입만 표기하고 파라미터 표는 생략합니다. 각 요청 타입의 필드는 데이터 타입에서 확인하세요.

발생 예외

ArgumentNullException: request가 null인 경우

공통 Failure 코드

아래 코드는 서버가 코드로 응답하지만 기능 관점의 결과가 아니므로 Outcome이 아닌 Failure로 분기합니다. 원인 코드는 Failure.Problem.ExternalCode에 담깁니다. 결과 갈래와 분기 방법은 Core 결과 모델을 참조하세요.

bad_request: 잘못된 요청
invalid_parameter: 요청 파라미터 형식 오류
missing_field: 필수 필드나 X-App-Id 같은 필수 헤더 자체의 누락
missing_app_id: X-App-Id 헤더를 보냈지만 값이 빈 경우
unauthorized: 인증 토큰이 없거나 유효하지 않은 경우
token_expired: 인증 토큰 만료
forbidden: 요청 권한 없음
resource_not_found: 요청한 리소스 없음
method_not_allowed: 허용되지 않은 요청 방식
resource_conflict: 요청과 리소스 상태의 충돌
unprocessable_content: 처리할 수 없는 요청 내용
rate_limit_exceeded: 허용 한도를 넘은 요청 빈도
internal_error: 서버 내부 오류
service_unavailable: 서비스 일시 중단

메서드

RedeemCouponAsync

앱 사용자가 입력한 쿠폰 코드를 사용 처리합니다. 사용에 성공하면 쿠폰의 아이템을 담은 우편이 로그인한 사용자의 우편함으로 발송되고, 발송된 우편의 ID가 Data.MailId로 반환됩니다. 서버 내부 오류로 Failure가 반환되면 쿠폰은 사용하지 않은 상태로 되돌아갑니다. 서버가 우편 발송에 실패한 경우도 마찬가지이며, 이때 Problem.ExternalCode에는 internal_error가 담깁니다.

Unity

Task<CouponRedeemCouponResult> RedeemCouponAsync(CouponRedeemRequest request, ApiCallContext? context = null);

요청: CouponRedeemRequest
응답: CouponRedeemResponseWrapperResponseData
인증: 세션 필요

결과 케이스 — CouponRedeemCouponResult

서버는 쿠폰 코드를 형식, 존재 여부, 사용 조건, 사용 상태, 사용 한도 순서로 검증합니다. 여러 조건에 해당해도 우선순위가 가장 높은 결과 하나만 반환하며, 아래 표는 결과 케이스를 이 검증 순서대로 나열합니다.

결과 케이스	와이어 코드	설명
`Success`	—	쿠폰을 사용했습니다. 아이템을 지급한 우편의 ID는 `Data.MailId`에 담깁니다.
`CouponCodeInvalidFormat`	`coupon_code_invalid_format`	쿠폰 코드의 형식이 올바르지 않습니다.
`CouponCodeNotFound`	`coupon_code_not_found`	쿠폰 코드가 없거나 삭제되었습니다.
`CouponDisabled`	`coupon_disabled`	쿠폰이나 쿠폰 코드가 비활성화되었습니다.
`CouponBeforeStart`	`coupon_before_start`	쿠폰의 사용 기간이 아직 시작되지 않았습니다.
`CouponExpired`	`coupon_expired`	쿠폰의 사용 기간이 끝났습니다.
`CouponAlreadyUsed`	`coupon_already_used`	이미 사용한 쿠폰입니다.
`CouponAccountLimitExceeded`	`coupon_account_limit_exceeded`	계정당 사용 한도를 모두 사용했습니다.
`CouponGroupLimitExceeded`	`coupon_group_limit_exceeded`	그룹당 사용 한도를 모두 사용했습니다.
`CouponTotalLimitExceeded`	`coupon_total_limit_exceeded`	이 쿠폰 코드의 전체 사용 한도를 모두 사용했습니다.
`UnknownOutcome`	`UNKNOWN`	이 SDK 버전이 알지 못하는 새 결과입니다.
`Failure`	`FAILURE`	호출을 마치지 못했습니다. 공통 Failure 코드도 이 케이스로 분기합니다.

지급 우편

서버는 우편함이 지급 우편의 발송 요청을 접수하면 지급에 성공한 것으로 처리합니다. 따라서 앱 사용자가 우편을 받아 아이템을 수령했는지는 앱 서버가 우편함에서 따로 확인해야 합니다. 지급 우편은 아래와 같이 발송됩니다.

언어: 요청 언어. 요청에 언어가 없거나 서버가 지원하지 않는 언어이면 한국어로 발송됩니다.
카테고리: 우편함 기본 카테고리인 DEFAULT
확장 데이터: 사용한 쿠폰의 UUID 형식 식별자를 couponId 키로 담은 JSON 문자열. Mail.MailExtension에 담기며, 우편함은 이 값을 해석하지 않으므로 앱 서버가 우편을 처리할 때 읽어 사용합니다.

요청 언어를 바꾸려면 SetLanguage()를 참조하세요.

호출 예시

Unity

using Hive.Axyl.Core;
using Hive.Axyl.Coupon;

var result = await coupon.RedeemCouponAsync(new CouponRedeemRequest
{
    CouponCode = inputCode,   // 앱 사용자가 입력한 쿠폰 코드
});

switch (result)
{
    case CouponRedeemCouponResult.Success success:
        string mailId = success.Data.MailId;   // 아이템을 지급한 우편의 ID
        break;

    case CouponRedeemCouponResult.CouponAlreadyUsed:
        // 이미 사용한 쿠폰임을 안내합니다.
        break;

    case CouponRedeemCouponResult.Failure failure:
        HiveError error = failure.Problem;
        break;

    default:
        // 그 밖의 결과 케이스와 UnknownOutcome
        break;
}

데이터 타입

CouponRedeemRequest

쿠폰 사용 요청입니다.

필드	타입	필수 여부	설명
`CouponCode`	`string`	Required	앱 사용자가 입력한 쿠폰 코드입니다. 영문과 숫자로 이루어진 8~20자이며, 대소문자를 구분하지 않습니다. 읽기 쉽도록 넣은 하이픈은 서버가 제거한 뒤 검증하므로 입력한 그대로 보내도 됩니다. 단, 하이픈까지 포함한 전체 길이가 20자를 넘으면 안 됩니다. 예: `ABCD1234EFGH`

CouponRedeemResponseWrapperResponseData

쿠폰 사용 결과입니다.

필드	타입	필수 여부	설명
`MailId`	`string`	Required	쿠폰의 아이템을 지급한 우편의 ID입니다. 우편함의 발신 우편 ID이므로, 수신 우편을 다룰 때 사용하는 `MailRecipientId`와는 다릅니다.
`Meta`	`string?`	Optional	서버가 함께 전달한 부가 정보입니다. 가공되지 않은 원본 JSON 문자열로 담깁니다.