브랜드 쿠폰

1. 관리자 발급한 일반 쿠폰 목록 조회 API (GET)

엔드포인트:

• GET /api/user/coupon/general

Description: 활성화된 일반 쿠폰 목록을 조회합니다. 사용자가 다운로드 받지 않은 쿠폰목록만 조회됩니다.

필드:

필드 이름	타입	설명
couponId	Long	쿠폰 ID
couponName	String	쿠폰 이름
discountPrice	Long	할인 금액
discountType	Enum (FIXED, PERCENT)	할인 방식 (정액 할인: FIXED, 정률 할인: PERCENT)
minOrderPrice	Long	최소 주문 금액
maximumDiscount	Long	최대 할인 금액 (정률 방식일 경우에만 유효)
expiredDate	LocalDateTime	쿠폰 만료일
couponDescription	String	쿠폰 상세 설명

Request:

• Body: 없음

• Params: 없음

Response:

• Status Code: 200 (OK)

• Body:

[
{
"couponId": 2, //쿠폰 아이디
"couponName": "Welcome Discount", //쿠폰명
"discountPrice": 10000, //할인금액
"discountType": "FIXED", //할인 유형
"minOrderPrice": 50000, //최소 주문 금액
"maximumDiscount": null,  //최대할인 금액
"expiredDate": "2025-01-01T23:59:59" //쿠폰 만료일
},
{
"couponId": 3,
"couponName": "Welcome Discount",
"discountPrice": 10,
"discountType": "PERCENT",
"minOrderPrice": 20000,
"maximumDiscount": 10000,
"expiredDate": "2025-01-01T23:59:59"
},
{
"couponId": 5,
"couponName": "Morning Discount",
"discountPrice": 1000,
"discountType": "FIXED",
"minOrderPrice": 15000,
"maximumDiscount": null,
"expiredDate": "2025-01-01T23:59:59"
}
]

모든 일반 쿠폰을 다운로드 받았을 때:

• Status Code: 200 (OK)

• Body:

[]

설명

• discountType에는 FIXED(정액),와 PERCENT(정률)가 있습니다.

  • ex) discountPrice=10000, discountType= FIXED라면 →10000원

  • ex) discountPrice=10, discountType= PERCENT라면 →10%

• discountType가 PERCENT(정률)일 때만 maximumDiscount (최대 할인 금액)이 올 수도 있습니다.

  • FIXED 일 때는 null값으로 반환됩니다.

---

2. 관리자 발급한 선착순 쿠폰 조회 API (GET)

Endpoint:

• GET /api/user/coupon/first-come

Description: 활성화된 선착순 쿠폰이 있는 경우 쿠폰 정보를 제공합니다.

활성화된 쿠폰이란 couponStatus가 ACTIVE이고,이는 사용자 화면에 보여주는 상태를 말합니다.

필드

필드 이름	타입	설명
couponId	Long	쿠폰 ID
couponName	String	쿠폰 이름
discountPrice	Long	할인 금액
discountType	Enum (FIXED, PERCENT)	할인 방식 (정액 할인: FIXED, 정률 할인: PERCENT)
maximumDiscount	Long	최대 할인 금액 (정률 방식일 경우에만 유효)
downloadStartDate	LocalDateTime	쿠폰 다운로드 시작일

Request:

• Body: 없음

• Params: 없음

Response:

활성화된 쿠폰이 있을 때:

• Status Code: 200 (OK)

• Body:

//할인 타입이 정액(원)일때
{
  "couponId": 5, //쿠폰아이디
  "couponName": "선착순 쿠폰 이벤트", //쿠폰명
  "discountPrice": 3000, //할인금액 (Long)
  "discountType": "FIXED", //할인 우형
  "maximumDiscount": null, //최대할인 금액 (FIXED일때 null)
  "downloadStartDate": "2024-11-30T00:00:00"
}

------------------------
//할인타입이 정률(%)일때
{
  "couponId": 5,
  "couponName": "선착순 쿠폰 이벤트",
  "discountPrice": 30,//할인 퍼센트
  "discountType": "PERCENT", 
  "maximumDiscount": 20000, //최대할인 금액 (PERCENT일때 값)
  "downloadStartDate": "2024-11-30T00:00:00"
}

이미 선착순 쿠폰을 다운로드했을 때:

• Status Code: 200 (OK)

• Body:

{
"message": "이미 선착순 쿠폰 이벤트에 참여하셨습니다."
}

선착순 쿠폰이 다 소진되었을 때:

• Status Code: 200 (OK)

• Body:

{
"message": "선착순 쿠폰이 모두 소진되었습니다."
}

활성화된 쿠폰이 없을 때:

{} //아무것도 반환되지 않습니다.

---

3. 가게 쿠폰 목록 조회 API (GET)

Endpoint:

• POST /api/user/coupon/owner/{storeId}

Description: 가게 전용 쿠폰을 다운로드합니다.

• Path Params:

  • storeId: 쿠폰을 발급한 가게 ID

필드

필드 이름	타입	설명
couponId	Long	쿠폰 ID
couponName	String	쿠폰 이름
discountPrice	Long	할인 금액
discountType	Enum (FIXED, PERCENT)	할인 방식 (정액 할인: FIXED, 정률 할인: PERCENT)
minOrderPrice	Long	최소 주문 금액

Request:

• Path Params:

  • storeId: 쿠폰을 발급한 가게 ID

• Body: 없음

Response:

• Status Code: 200 (OK)

• Body:

[
{
"couponId": 1,
"couponName": "Hello 할인",
"discountPrice": 2000,
"discountType": "FIXED",
"minOrderPrice": 20000
},
{
"couponId": 2,
"couponName": "12월 진짜 할인",
"discountPrice": 20,
"discountType": "PERCENT",
"minOrderPrice": 20000
},
{
"couponId": 4,
"couponName": "정말 좋은 할인",
"discountPrice": 2000,
"discountType": "FIXED",
"minOrderPrice": 20000
}
]

---

4. 일반 쿠폰 다운로드 API (POST)

Endpoint:

• POST /api/user/coupon/download/general/{couponId}

Description: 일반 쿠폰을 다운로드합니다.

Request:

• Path Params:

  • couponId: 다운로드할 쿠폰의 ID.

• Body: 없음

Response:

• Status Code: 200 (OK)

• Body:

{
"message": "쿠폰이 발급되었습니다!"
}

중복 다운로드 시:

• Status Code: 400 (*BAD_REQUEST*)

{
"error": "중복 다운로드가 불가능한 쿠폰입니다."
}

---

5. 선착순 쿠폰 다운로드 API (POST)

Endpoint:

• POST /api/user/coupon/download/first-come/{couponId}

Description: 선착순 쿠폰을 다운로드합니다.

Request:

• Path Params:

  • couponId: 다운로드할 쿠폰의 ID.

• Body: 없음

Response:

처음 다운로드 시:

• Status Code: 200 (OK)

• Body:

{
"message": "선착순 쿠폰 다운로드에 성공했습니다!"
}

중복 다운로드 시:

• Status Code: 400 (*BAD_REQUEST*)

{
"error": "중복 다운로드가 불가능한 쿠폰입니다."
}

선착순 발급 한도를 초과하였을 시:

• Status Code: 400 (*BAD_REQUEST*)

{
"error": "선착순 쿠폰이 모두 소진되었습니다. 다음 이벤트를 기대해주세요!"
}

---

6. 가게 쿠폰 다운로드 API (POST)

Endpoint:

• POST /api/user/coupon/download/owner/{couponId}

Description: 사장님이 발급한 쿠폰을 다운로드합니다.

Request:

• Path Params:

  • couponId: 다운로드할 쿠폰의 ID.

• Body: 없음

Response:

• Status Code: 200 (OK)

• Body:

{
"message": "쿠폰이 발급되었습니다!"
}

중복 다운로드 시:

• Status Code: 400 (*BAD_REQUEST*)

{
"error": "중복 다운로드가 불가능한 쿠폰입니다."
}

---

7. 사용자 쿠폰함 목록 조회 API (GET)

Endpoint:

• GET /api/user/coupon/box

Description: 사용자가 보유하고 있는 미사용 쿠폰 목록을 할인 금액이 큰 순서대로 조회합니다.

필드 설명

필드 이름	타입	설명
userCouponId	String	사용자 쿠폰 고유 ID
couponName	String	쿠폰 이름
discountPrice	Long	할인 금액
discountType	Enum (FIXED, PERCENT)	할인 방식 (정액 할인: FIXED, 정률 할인: PERCENT)
minOrderPrice	Long	최소 주문 금액
maximumDiscount	Long	최대 할인 금액 (정률 방식일 경우에만 유효)
expiredDate	LocalDateTime	쿠폰 만료일
couponDescription	String	쿠폰 상세 설명
storeName	String	쿠폰 발급한 가게 이름

Request:

• Body: 없음

• Params: 없음

Response:

• Status Code: 200 (OK)

• Body:

[
  {
    "userCouponId": "a1b2c3d4e5", //사용자 쿠폰 아이디
    "couponName": "일반 할인 쿠폰", //쿠폰명
    "discountPrice": 1000, //할인 금액
    "discountType": "FIXED", //할인 유형
    "minOrderPrice": 5000, //최소 주문 금액
    "maximumDiscount": null, //최대 할인 금액
    "expiredDate": "2024-12-31T23:59:59", //쿠폰 만료일
    "couponDescription": "전 가게에서 사용 가능한 쿠폰", //쿠폰소개
    "storeName": null //관리자가 발급한 쿠폰일 경우 null
   },
  {
    "userCouponId": "f6g7h8i9j0",
    "couponName": "가게 전용 쿠폰",
    "discountPrice": 2000,
    "discountType": "FIXED",
    "minOrderPrice": 8000,
    "maximumDiscount": null, //할인 타입이 정액(원)일 경우 null
    "expiredDate": "2024-11-30T23:59:59", 
    "couponDescription": "가게에서만 사용 가능한 쿠폰",
    "storeName": "겁나 맛있는 족발집"
  },
  {
		"userCouponId": "a09e239a-a177-4200-bbdb-fb4a6b898c9f",
		"couponName": "12월 진짜 할인",
		"discountPrice": 20,
		"discountType": "PERCENT",
		"minOrderPrice": 20000,
		"maximumDiscount": 10000,
		"expiredDate": "2024-12-06T22:44:33.676798",
		"couponDescription": "12월 할인",
		"storeName": "맛있는 음식점"
		},
]

설명

• discountType에는 FIXED(정액),와 PERCENT(정률)가 있습니다.

  • ex) discountPrice=10000, discountType= FIXED라면 →10000원

  • ex) discountPrice=10, discountType= PERCENT라면 →10%

• discountType가 PERCENT(정률)일 때만 maximumDiscount (최대 할인 금액)이 올 수도 있습니다.

  • FIXED 일 때는 null값으로 반환됩니다.

• 가게 전용 쿠폰일때만 storeName이 반환됩니다.

  • 관리자 쿠폰(일반쿠폰/선착순쿠폰)일 경우 storeName은 null입니다.

---