bootpay-backend 2.2.0__tar.gz → 2.5.0__tar.gz

{bootpay_backend-2.2.0 → bootpay_backend-2.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: bootpay_backend
-Version: 2.2.0
+Version: 2.5.0
 Summary: bootpay server side plugin for python
 Home-page: https://github.com/bootpay/backend-python/tree/2-x-development
 Author: bootpay <bootpay.co.kr@gmail.com>
@@ -27,6 +27,16 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: requests>=2.20; python_version >= "3.0"
 Requires-Dist: requests[security]>=2.20; python_version < "3.0"
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
 
 
 ## Bootpay Python Server Side Library
@@ -70,13 +80,42 @@ Python 언어로 작성된 어플리케이션, 프레임워크 등에서 사용
 pip install bootpay-backend
 ```
 
+
+## 환경변수 설정
+
+예제와 테스트는 각 SDK 루트의 `.env` 파일을 우선 읽습니다. 먼저 `.env.example`을 복사한 뒤 필요한 키만 변경하세요. `.env`는 gitignore 처리되어 커밋되지 않습니다.
+
+```bash
+cp .env.example .env
+# BOOTPAY_ENV=production 또는 development
+```
+
+주요 변수:
+
+```env
+BOOTPAY_ENV=production
+BOOTPAY_PG_CLIENT_KEY_PROD=...
+BOOTPAY_PG_SECRET_KEY_PROD=...
+BOOTPAY_PG_CLIENT_KEY_DEV=...
+BOOTPAY_PG_SECRET_KEY_DEV=...
+BOOTPAY_COMMERCE_CLIENT_KEY_PROD=...
+BOOTPAY_COMMERCE_SECRET_KEY_PROD=...
+BOOTPAY_COMMERCE_CLIENT_KEY_DEV=...
+BOOTPAY_COMMERCE_SECRET_KEY_DEV=...
+```
+
+변수가 없으면 SDK 테스트용 기본값(NodeJS 기준 ck/sk)으로 fallback 합니다.
+
 # 사용하기
 
+> 권장 인증 방식은 `client_key/secret_key`입니다. 기존 positional `application_id/private_key` 방식도 계속 지원됩니다.
+
 ```python
 
+import os
 from bootpay_backend import BootpayBackend
 
-bootpay = BootpayBackend('5b8f6a4d396fa665fdc2b5ea', 'rm6EYECr6aroQVG2ntW0A6LpWnkTgP4uQ3H18sDDUYw=')
+bootpay = BootpayBackend(client_key=os.getenv('BOOTPAY_PG_CLIENT_KEY_PROD'), secret_key=os.getenv('BOOTPAY_PG_SECRET_KEY_PROD'))
 
 token = bootpay.get_access_token() 
 if 'error_code' not in token:
@@ -91,7 +130,7 @@ if 'error_code' not in token:
 발급된 토큰은 30분간 유효하며, 최초 발급일로부터 30분이 지날 경우 토큰 발급 함수를 재호출 해주셔야 합니다.
 
 ```python
-bootpay = BootpayBackend('5b8f6a4d396fa665fdc2b5ea', 'rm6EYECr6aroQVG2ntW0A6LpWnkTgP4uQ3H18sDDUYw=')
+bootpay = BootpayBackend(client_key=os.getenv('BOOTPAY_PG_CLIENT_KEY_PROD'), secret_key=os.getenv('BOOTPAY_PG_SECRET_KEY_PROD'))
 
 token = bootpay.get_access_token() 
 if 'error_code' not in token:
@@ -405,11 +444,12 @@ if 'error_code' not in token:
 
 ## Documentation
 
-[부트페이 개발매뉴얼](https://developer.bootpay.co.kr/)을 참조해주세요
+- [부트페이 결제 개발문서](https://developers.bootpay.ai)
+- [부트페이 커머스 개발문서](https://commerce.bootpay.ai)
 
 ## 기술문의
 
-[부트페이 홈페이지](https://www.bootpay.co.kr) 우측 하단 채팅을 통해 기술문의 주세요!
+[부트페이 홈페이지](https://www.bootpay.ai)에서 문의해주세요!
 
 ## License
 

{bootpay_backend-2.2.0 → bootpay_backend-2.5.0}/README.md

@@ -40,13 +40,42 @@ Python 언어로 작성된 어플리케이션, 프레임워크 등에서 사용
 pip install bootpay-backend
 ```
 
+
+## 환경변수 설정
+
+예제와 테스트는 각 SDK 루트의 `.env` 파일을 우선 읽습니다. 먼저 `.env.example`을 복사한 뒤 필요한 키만 변경하세요. `.env`는 gitignore 처리되어 커밋되지 않습니다.
+
+```bash
+cp .env.example .env
+# BOOTPAY_ENV=production 또는 development
+```
+
+주요 변수:
+
+```env
+BOOTPAY_ENV=production
+BOOTPAY_PG_CLIENT_KEY_PROD=...
+BOOTPAY_PG_SECRET_KEY_PROD=...
+BOOTPAY_PG_CLIENT_KEY_DEV=...
+BOOTPAY_PG_SECRET_KEY_DEV=...
+BOOTPAY_COMMERCE_CLIENT_KEY_PROD=...
+BOOTPAY_COMMERCE_SECRET_KEY_PROD=...
+BOOTPAY_COMMERCE_CLIENT_KEY_DEV=...
+BOOTPAY_COMMERCE_SECRET_KEY_DEV=...
+```
+
+변수가 없으면 SDK 테스트용 기본값(NodeJS 기준 ck/sk)으로 fallback 합니다.
+
 # 사용하기
 
+> 권장 인증 방식은 `client_key/secret_key`입니다. 기존 positional `application_id/private_key` 방식도 계속 지원됩니다.
+
 ```python
 
+import os
 from bootpay_backend import BootpayBackend
 
-bootpay = BootpayBackend('5b8f6a4d396fa665fdc2b5ea', 'rm6EYECr6aroQVG2ntW0A6LpWnkTgP4uQ3H18sDDUYw=')
+bootpay = BootpayBackend(client_key=os.getenv('BOOTPAY_PG_CLIENT_KEY_PROD'), secret_key=os.getenv('BOOTPAY_PG_SECRET_KEY_PROD'))
 
 token = bootpay.get_access_token() 
 if 'error_code' not in token:
@@ -61,7 +90,7 @@ if 'error_code' not in token:
 발급된 토큰은 30분간 유효하며, 최초 발급일로부터 30분이 지날 경우 토큰 발급 함수를 재호출 해주셔야 합니다.
 
 ```python
-bootpay = BootpayBackend('5b8f6a4d396fa665fdc2b5ea', 'rm6EYECr6aroQVG2ntW0A6LpWnkTgP4uQ3H18sDDUYw=')
+bootpay = BootpayBackend(client_key=os.getenv('BOOTPAY_PG_CLIENT_KEY_PROD'), secret_key=os.getenv('BOOTPAY_PG_SECRET_KEY_PROD'))
 
 token = bootpay.get_access_token() 
 if 'error_code' not in token:
@@ -375,11 +404,12 @@ if 'error_code' not in token:
 
 ## Documentation
 
-[부트페이 개발매뉴얼](https://developer.bootpay.co.kr/)을 참조해주세요
+- [부트페이 결제 개발문서](https://developers.bootpay.ai)
+- [부트페이 커머스 개발문서](https://commerce.bootpay.ai)
 
 ## 기술문의
 
-[부트페이 홈페이지](https://www.bootpay.co.kr) 우측 하단 채팅을 통해 기술문의 주세요!
+[부트페이 홈페이지](https://www.bootpay.ai)에서 문의해주세요!
 
 ## License
 

{bootpay_backend-2.2.0 → bootpay_backend-2.5.0}/bootpay_backend/commerce/__init__.py

@@ -9,7 +9,15 @@ from .modules import (
     OrderCancelModule,
     OrderSubscriptionModule,
     OrderSubscriptionBillModule,
-    OrderSubscriptionAdjustmentModule
+    OrderSubscriptionAdjustmentModule,
+    StoreModule,
+    CategoryModule,
+    CouponModule,
+    PointModule,
+    CartModule,
+    OrderSubscriptionRequestModule,
+    MallSettingModule,
+    WebhookModule
 )
 from .types import *
 
@@ -49,7 +57,7 @@ class BootpayCommerce(BootpayCommerceResource):
         :param mode: 환경 ('development', 'stage', 'production')
         """
         super().__init__()
-        if client_key and secret_key:
+        if client_key is not None or secret_key is not None:
             self.set_configuration(client_key, secret_key, mode)
         self._init_modules()
 
@@ -64,6 +72,14 @@ class BootpayCommerce(BootpayCommerceResource):
         self.order_subscription = OrderSubscriptionModule(self)
         self.order_subscription_bill = OrderSubscriptionBillModule(self)
         self.order_subscription_adjustment = OrderSubscriptionAdjustmentModule(self)
+        self.store = StoreModule(self)
+        self.category = CategoryModule(self)
+        self.coupon = CouponModule(self)
+        self.point = PointModule(self)
+        self.cart = CartModule(self)
+        self.order_subscription_request = OrderSubscriptionRequestModule(self)
+        self.mall_setting = MallSettingModule(self)
+        self.webhook = WebhookModule(self)
 
     def get_access_token(self):
         """
@@ -188,6 +204,14 @@ __all__ = [
     'OrderSubscriptionModule',
     'OrderSubscriptionBillModule',
     'OrderSubscriptionAdjustmentModule',
+    'StoreModule',
+    'CategoryModule',
+    'CouponModule',
+    'PointModule',
+    'CartModule',
+    'OrderSubscriptionRequestModule',
+    'MallSettingModule',
+    'WebhookModule',
     # Types
     'ListParams',
     'CommerceAddress',
@@ -242,4 +266,47 @@ __all__ = [
     'SUBSCRIPTION_ADJUSTMENT_TYPE_PERIOD_DISCOUNT',
     'CommerceOrderSubscriptionAdjustment',
     'OrderSubscriptionAdjustmentUpdateParams',
+    'SupervisorOrderSubscriptionApproveParams',
+    'SupervisorOrderSubscriptionRejectParams',
+    'SupervisorOrderSubscriptionTerminateParams',
+    'SupervisorOrderSubscriptionPauseParams',
+    'SupervisorOrderSubscriptionResumeParams',
+    'CommerceCategory',
+    'CategoryCreateParams',
+    'CategoryUpdateParams',
+    'CommerceCoupon',
+    'CouponListParams',
+    'CouponDownloadParams',
+    'PointBalance',
+    'PointTransaction',
+    'PointTransactionsResponse',
+    'PointTransactionsParams',
+    'CartItemPayload',
+    'ShippingAddressPayload',
+    'OrderPreviewParams',
+    'DeliveryGroupItem',
+    'DeliveryGroup',
+    'AppliedCouponSnapshot',
+    'OrderPreviewSummary',
+    'OrderPreviewUnavailableItem',
+    'OrderPreviewResponse',
+    'OrderSubscriptionRequest',
+    'OrderSubscriptionRequestListParams',
+    'OrderSubscriptionRequestUpdateParams',
+    'InvoiceListResponse',
+    'OrderCancelWithdrawParams',
+    'OrderSubscriptionPurchaseParams',
+    'OrderSubscriptionTransferParams',
+    'SupervisorOrderSubscriptionChargeParams',
+    'SupervisorOrderSubscriptionChargeRevokeParams',
+    'OrderSubscriptionChargeResponse',
+    'OrderSubscriptionChargeRevokeResponse',
+    'MallProductListParams',
+    'MallUserLoginParams',
+    'MallUserJoinParams',
+    'MallUserJoinCheckType',
+    'MallUserSessionResponse',
+    'MallSettingUpdateParams',
+    'CommerceMallSetting',
+    'SendTestWebhookParams',
 ]

{bootpay_backend-2.2.0 → bootpay_backend-2.5.0}/bootpay_backend/commerce/commerce_resource.py

@@ -53,19 +53,28 @@ class BootpayCommerceResource:
 
     def _get_basic_auth_header(self) -> str:
         """Basic Auth 헤더 생성"""
-        if self.client_key and self.secret_key:
-            credentials = f'{self.client_key}:{self.secret_key}'
-            encoded = base64.b64encode(credentials.encode()).decode()
-            return f'Basic {encoded}'
-        return ''
+        has_client_key = bool(self.client_key)
+        has_secret_key = bool(self.secret_key)
+        if not has_client_key and not has_secret_key:
+            raise ValueError('Commerce API에는 client_key와 secret_key가 필요합니다.')
+        if has_client_key != has_secret_key:
+            missing = 'secret_key' if has_client_key else 'client_key'
+            raise ValueError(f'{missing} 값이 비어있습니다. client_key와 secret_key는 함께 지정해야 합니다.')
+        credentials = f'{self.client_key}:{self.secret_key}'
+        encoded = base64.b64encode(credentials.encode()).decode()
+        return f'Basic {encoded}'
 
     def _entrypoints(self, url: str) -> str:
         """엔트리포인트 URL 생성"""
         return '/'.join([self.API_ENTRYPOINTS[self.mode], url])
 
-    def _get_headers(self, include_auth: bool = True) -> Dict[str, str]:
-        """공통 헤더 생성"""
-        headers = {
+    def _get_headers(self, include_auth: bool = True, headers: Optional[Dict[str, str]] = None) -> Dict[str, str]:
+        """
+        공통 헤더 생성
+        요청별로 지정된 헤더(headers)가 공통값을 덮어쓴다 —
+        supervisor 전용 endpoint 의 BOOTPAY-ROLE 을 공통 계층이 덮어쓰지 않기 위함.
+        """
+        merged = {
             'Content-Type': 'application/json',
             'Accept': 'application/json',
             'Accept-Charset': 'utf-8',
@@ -74,25 +83,29 @@ class BootpayCommerceResource:
             'BOOTPAY-SDK-TYPE': '302',
             'BOOTPAY-ROLE': self._role or 'user'
         }
-        if include_auth and self._token:
-            headers['Authorization'] = f'Bearer {self._token}'
-        return headers
-
-    def get(self, url: str, params: Optional[Dict] = None):
+        if include_auth:
+            basic_auth = self._get_basic_auth_header()
+            if basic_auth:
+                merged['Authorization'] = basic_auth
+        if headers:
+            merged.update(headers)
+        return merged
+
+    def get(self, url: str, params: Optional[Dict] = None, headers: Optional[Dict[str, str]] = None):
         """GET 요청"""
         response = requests.get(
             self._entrypoints(url),
-            headers=self._get_headers(),
+            headers=self._get_headers(headers=headers),
             params=params,
             timeout=self.timeout
         )
         return response.json()
 
-    def post(self, url: str, data: Optional[Dict] = None):
+    def post(self, url: str, data: Optional[Dict] = None, headers: Optional[Dict[str, str]] = None):
         """POST 요청"""
         response = requests.post(
             self._entrypoints(url),
-            headers=self._get_headers(),
+            headers=self._get_headers(headers=headers),
             json=data,
             timeout=self.timeout
         )
@@ -110,14 +123,18 @@ class BootpayCommerceResource:
         )
         return response.json()
 
-    def post_multipart(self, url: str, data: Dict, image_paths: Optional[List[str]] = None):
+    def post_multipart(self, url: str, data: Dict, image_paths: Optional[List[str]] = None,
+                       headers: Optional[Dict[str, str]] = None):
         """
         Multipart/form-data POST 요청 (이미지 업로드 포함)
+        ⚠️ Content-Type 은 requests 가 생성한 값(boundary 포함)을 그대로 사용한다.
+           직접 지정하면 boundary 가 사라져 본문이 서버에서 null 로 파싱된다.
         :param url: 요청 URL
         :param data: 폼 데이터
         :param image_paths: 이미지 파일 경로 배열
+        :param headers: 요청별 추가 헤더 (공통값을 덮어쓴다)
         """
-        headers = {
+        request_headers = {
             'Accept': 'application/json',
             'Accept-Charset': 'utf-8',
             'BOOTPAY-SDK-VERSION': self.SDK_VERSION,
@@ -125,29 +142,37 @@ class BootpayCommerceResource:
             'BOOTPAY-SDK-TYPE': '302',
             'BOOTPAY-ROLE': self._role or 'user'
         }
-        if self._token:
-            headers['Authorization'] = f'Bearer {self._token}'
+        basic_auth = self._get_basic_auth_header()
+        if basic_auth:
+            request_headers['Authorization'] = basic_auth
+        if headers:
+            request_headers.update(headers)
 
         # 폼 데이터 준비
+        # ⚠️ bool 은 소문자 'true'/'false' 로 보낸다 — str(True) 의 'True'/'False' 는
+        #    Rails 캐스팅 대상이 아니라서 "False" 가 true 로 해석되는 실위험이 있다.
         form_data = {}
         for key, value in data.items():
             if value is not None:
-                if isinstance(value, (dict, list)):
+                if isinstance(value, bool):
+                    form_data[key] = 'true' if value else 'false'
+                elif isinstance(value, (dict, list)):
                     form_data[key] = json.dumps(value)
                 else:
                     form_data[key] = str(value)
 
         # 파일 준비
+        # ⚠️ Rails 는 반복된 `images` 를 배열로 받지 않는다. images[0], images[1] ... 로 인덱싱해야 한다.
         files = []
         if image_paths:
-            for image_path in image_paths:
+            for index, image_path in enumerate(image_paths):
                 filename = os.path.basename(image_path)
-                files.append(('images', (filename, open(image_path, 'rb'))))
+                files.append((f'images[{index}]', (filename, open(image_path, 'rb'))))
 
         try:
             response = requests.post(
                 self._entrypoints(url),
-                headers=headers,
+                headers=request_headers,
                 data=form_data,
                 files=files if files else None,
                 timeout=self.timeout
@@ -158,22 +183,27 @@ class BootpayCommerceResource:
             for _, file_tuple in files:
                 file_tuple[1].close()
 
-    def put(self, url: str, data: Optional[Dict] = None):
+    def put(self, url: str, data: Optional[Dict] = None, headers: Optional[Dict[str, str]] = None):
         """PUT 요청"""
         response = requests.put(
             self._entrypoints(url),
-            headers=self._get_headers(),
+            headers=self._get_headers(headers=headers),
             json=data,
             timeout=self.timeout
         )
         return response.json()
 
-    def delete(self, url: str, params: Optional[Dict] = None):
-        """DELETE 요청"""
+    def delete(self, url: str, params: Optional[Dict] = None, headers: Optional[Dict[str, str]] = None,
+               data: Optional[Dict] = None):
+        """
+        DELETE 요청
+        :param data: 요청 body (JSON) — 대상 ID 를 query 가 아닌 body 로 보내는 endpoint 용
+        """
         response = requests.delete(
             self._entrypoints(url),
-            headers=self._get_headers(),
+            headers=self._get_headers(headers=headers),
             params=params,
+            json=data,
             timeout=self.timeout
         )
         return response.json()

{bootpay_backend-2.2.0 → bootpay_backend-2.5.0}/bootpay_backend/commerce/modules/__init__.py

@@ -8,6 +8,14 @@ from .order_cancel import OrderCancelModule
 from .order_subscription import OrderSubscriptionModule
 from .order_subscription_bill import OrderSubscriptionBillModule
 from .order_subscription_adjustment import OrderSubscriptionAdjustmentModule
+from .store import StoreModule
+from .category import CategoryModule
+from .coupon import CouponModule
+from .point import PointModule
+from .cart import CartModule
+from .order_subscription_request import OrderSubscriptionRequestModule
+from .mall_setting import MallSettingModule
+from .webhook import WebhookModule
 
 __all__ = [
     'UserModule',
@@ -18,5 +26,13 @@ __all__ = [
     'OrderCancelModule',
     'OrderSubscriptionModule',
     'OrderSubscriptionBillModule',
-    'OrderSubscriptionAdjustmentModule'
+    'OrderSubscriptionAdjustmentModule',
+    'StoreModule',
+    'CategoryModule',
+    'CouponModule',
+    'PointModule',
+    'CartModule',
+    'OrderSubscriptionRequestModule',
+    'MallSettingModule',
+    'WebhookModule'
 ]

bootpay_backend-2.5.0/bootpay_backend/commerce/modules/cart.py

@@ -0,0 +1,29 @@
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from ..commerce_resource import BootpayCommerceResource
+
+from ..types import (
+    OrderPreviewParams,
+    OrderPreviewResponse
+)
+
+
+class CartModule:
+    """장바구니 모듈"""
+
+    def __init__(self, bootpay: 'BootpayCommerceResource'):
+        self._bootpay = bootpay
+
+    def order_preview(self, params: Optional[OrderPreviewParams] = None):
+        """
+        주문 미리보기 (배송비/할인 권위적 계산)
+        POST /v1/cart/order-preview
+
+        member_mode='guest' (기본): cart_items 필수
+        member_mode='member': 서버 장바구니 사용 (user 토큰 필요)
+
+        :param params: 주문 미리보기 파라미터
+        :return: OrderPreviewResponse
+        """
+        return self._bootpay.post('cart/order-preview', params if params is not None else {})

bootpay_backend-2.5.0/bootpay_backend/commerce/modules/category.py

@@ -0,0 +1,92 @@
+import uuid
+from typing import TYPE_CHECKING, Dict, Optional
+
+if TYPE_CHECKING:
+    from ..commerce_resource import BootpayCommerceResource
+
+from ..types import (
+    CommerceCategory,
+    CategoryCreateParams,
+    CategoryUpdateParams
+)
+
+
+class CategoryModule:
+    """카테고리 모듈"""
+
+    def __init__(self, bootpay: 'BootpayCommerceResource'):
+        self._bootpay = bootpay
+
+    def list(self):
+        """
+        카테고리 트리 조회
+        :return: List[CommerceCategory]
+        """
+        return self._bootpay.get('categories')
+
+    def detail(self, category_id: str):
+        """
+        카테고리 단건 조회
+        :param category_id: 카테고리 ID
+        :return: CommerceCategory
+        """
+        return self._bootpay.get(f'categories/{category_id}')
+
+    def create(self, params: CategoryCreateParams):
+        """
+        카테고리 생성
+        POST /v1/categories
+        ⚠️ 서버가 supervisor scope 를 요구한다 (scope_invalid!).
+        :param params: 카테고리 생성 파라미터
+        :return: CommerceCategory
+        """
+        params = dict(params or {})
+        idempotency_key = params.pop('idempotency_key', None)
+        return self._bootpay.post(
+            'categories',
+            params,
+            headers=self._supervisor_headers(idempotency_key)
+        )
+
+    def update(self, params: CategoryUpdateParams):
+        """
+        카테고리 수정
+        PUT /v1/categories/{category_id}
+        ⚠️ 서버가 supervisor scope 를 요구한다 (scope_invalid!).
+        :param params: 카테고리 수정 파라미터 (category_id 필수)
+        :return: CommerceCategory
+        """
+        if not params.get('category_id'):
+            raise ValueError('category_id is required')
+        params = dict(params)
+        category_id = params.pop('category_id')
+        idempotency_key = params.pop('idempotency_key', None)
+        return self._bootpay.put(
+            f'categories/{category_id}',
+            params,
+            headers=self._supervisor_headers(idempotency_key)
+        )
+
+    def destroy(self, category_id: str, idempotency_key: Optional[str] = None):
+        """
+        카테고리 삭제
+        DELETE /v1/categories/{category_id}
+        ⚠️ 서버가 supervisor scope 를 요구한다 (scope_invalid!).
+        :param category_id: 카테고리 ID
+        :param idempotency_key: 미지정시 자동 생성
+        :return: None
+        """
+        return self._bootpay.delete(
+            f'categories/{category_id}',
+            headers=self._supervisor_headers(idempotency_key)
+        )
+
+    def _supervisor_headers(self, idempotency_key: Optional[str] = None) -> Dict[str, str]:
+        """
+        카테고리 쓰기(등록/수정/삭제) 요청 헤더 — 서버가 supervisor scope 를 요구한다.
+        Idempotency-Key 는 미지정시 매 호출마다 생성된다.
+        """
+        return {
+            'Idempotency-Key': idempotency_key or str(uuid.uuid4()),
+            'BOOTPAY-ROLE': 'supervisor'
+        }

bootpay_backend-2.5.0/bootpay_backend/commerce/modules/coupon.py

@@ -0,0 +1,51 @@
+from typing import TYPE_CHECKING, Optional
+from urllib.parse import urlencode
+
+if TYPE_CHECKING:
+    from ..commerce_resource import BootpayCommerceResource
+
+from ..types import (
+    CommerceCoupon,
+    CouponListParams,
+    CouponDownloadParams
+)
+
+
+class CouponModule:
+    """쿠폰 모듈"""
+
+    def __init__(self, bootpay: 'BootpayCommerceResource'):
+        self._bootpay = bootpay
+
+    def list(self, params: Optional[CouponListParams] = None):
+        """
+        사용자 보유 쿠폰 목록 조회
+        :param params: 조회 파라미터
+        :return: List[CommerceCoupon]
+        """
+        query_params = {}
+        if params:
+            if params.get('status'):
+                query_params['status'] = params['status']
+            if params.get('page') is not None:
+                query_params['page'] = params['page']
+            if params.get('limit') is not None:
+                query_params['limit'] = params['limit']
+
+        query = urlencode(query_params) if query_params else ''
+        return self._bootpay.get(f'coupon{"?" + query if query else ""}')
+
+    def available(self):
+        """
+        다운로드 가능한 쿠폰 목록
+        :return: List[CommerceCoupon]
+        """
+        return self._bootpay.get('coupon/available')
+
+    def download(self, params: CouponDownloadParams):
+        """
+        쿠폰 다운로드 (issue_from_template)
+        :param params: {'coupon_template_id': str}
+        :return: CommerceCoupon
+        """
+        return self._bootpay.post('coupon/download', params)