bootpay-backend 2.3.0__tar.gz → 2.7.0__tar.gz

{bootpay_backend-2.3.0 → bootpay_backend-2.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bootpay_backend
-Version: 2.3.0
+Version: 2.7.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>
@@ -444,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.3.0 → bootpay_backend-2.7.0}/README.md

@@ -404,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.3.0 → bootpay_backend-2.7.0}/bootpay_backend/commerce/__init__.py

@@ -15,7 +15,9 @@ from .modules import (
     CouponModule,
     PointModule,
     CartModule,
-    OrderSubscriptionRequestModule
+    OrderSubscriptionRequestModule,
+    MallSettingModule,
+    WebhookModule
 )
 from .types import *
 
@@ -55,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()
 
@@ -76,6 +78,8 @@ class BootpayCommerce(BootpayCommerceResource):
         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):
         """
@@ -206,6 +210,8 @@ __all__ = [
     'PointModule',
     'CartModule',
     'OrderSubscriptionRequestModule',
+    'MallSettingModule',
+    'WebhookModule',
     # Types
     'ListParams',
     'CommerceAddress',
@@ -287,4 +293,20 @@ __all__ = [
     'OrderSubscriptionRequest',
     'OrderSubscriptionRequestListParams',
     'OrderSubscriptionRequestUpdateParams',
+    'InvoiceListResponse',
+    'OrderCancelWithdrawParams',
+    'OrderSubscriptionPurchaseParams',
+    'OrderSubscriptionTransferParams',
+    'SupervisorOrderSubscriptionChargeParams',
+    'SupervisorOrderSubscriptionChargeRevokeParams',
+    'OrderSubscriptionChargeResponse',
+    'OrderSubscriptionChargeRevokeResponse',
+    'MallProductListParams',
+    'MallUserLoginParams',
+    'MallUserJoinParams',
+    'MallUserJoinCheckType',
+    'MallUserSessionResponse',
+    'MallSettingUpdateParams',
+    'CommerceMallSetting',
+    'SendTestWebhookParams',
 ]

{bootpay_backend-2.3.0 → bootpay_backend-2.7.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',
@@ -77,24 +86,26 @@ class BootpayCommerceResource:
         if include_auth:
             basic_auth = self._get_basic_auth_header()
             if basic_auth:
-                headers['Authorization'] = basic_auth
-        return headers
+                merged['Authorization'] = basic_auth
+        if headers:
+            merged.update(headers)
+        return merged
 
-    def get(self, url: str, params: Optional[Dict] = None):
+    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
         )
@@ -112,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,
@@ -129,28 +144,35 @@ class BootpayCommerceResource:
         }
         basic_auth = self._get_basic_auth_header()
         if basic_auth:
-            headers['Authorization'] = 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
@@ -161,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.3.0 → bootpay_backend-2.7.0}/bootpay_backend/commerce/modules/__init__.py

@@ -14,6 +14,8 @@ 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',
@@ -30,5 +32,7 @@ __all__ = [
     'CouponModule',
     'PointModule',
     'CartModule',
-    'OrderSubscriptionRequestModule'
+    'OrderSubscriptionRequestModule',
+    'MallSettingModule',
+    'WebhookModule'
 ]

bootpay_backend-2.7.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.7.0/bootpay_backend/commerce/modules/invoice.py

@@ -0,0 +1,106 @@
+import uuid
+from typing import TYPE_CHECKING, Optional, List, Dict
+from urllib.parse import urlencode
+
+if TYPE_CHECKING:
+    from ..commerce_resource import BootpayCommerceResource
+
+from ..types import (
+    CommerceInvoice,
+    InvoiceListParams,
+    InvoiceListResponse,
+    ListParams
+)
+
+
+class InvoiceModule:
+    """청구서 모듈"""
+
+    def __init__(self, bootpay: 'BootpayCommerceResource'):
+        self._bootpay = bootpay
+
+    def list(self, params: Optional[InvoiceListParams] = None):
+        """
+        청구서 목록 조회
+        GET /v1/invoices
+        응답은 {'list': [...], 'count': N} 구조다 ({'items', 'total'} 아님).
+        limit 미지정시 서버 기본값과 동일한 24 를 보낸다.
+        :param params: 조회 파라미터
+        :return: InvoiceListResponse — {'list': List[CommerceInvoice], 'count': int}
+        """
+        params = dict(params or {})
+        idempotency_key = params.pop('idempotency_key', None)
+
+        query_params = {
+            'page': 1 if params.get('page') is None else params['page'],
+            'limit': 24 if params.get('limit') is None else params['limit'],
+        }
+        if params.get('keyword'):
+            query_params['keyword'] = params['keyword']
+        if params.get('cs_type'):
+            query_params['cs_type'] = params['cs_type']
+        if params.get('user_id'):
+            query_params['user_id'] = params['user_id']
+        if params.get('product_type') is not None:
+            query_params['product_type'] = params['product_type']
+        if params.get('css_at'):
+            query_params['css_at'] = params['css_at']
+        if params.get('cse_at'):
+            query_params['cse_at'] = params['cse_at']
+
+        return self._bootpay.get(
+            f'invoices?{urlencode(query_params)}',
+            headers=self._invoice_headers(idempotency_key)
+        )
+
+    def create(self, invoice: CommerceInvoice):
+        """
+        청구서 생성
+        :param invoice: 청구서 정보
+        :return: CommerceInvoice
+        """
+        return self._bootpay.post('invoices', invoice)
+
+    def notify(self, invoice_id: str, send_types: Optional[List[int]] = None,
+               idempotency_key: Optional[str] = None):
+        """
+        청구서 알림 재발송
+        POST /v1/invoices/{invoice_id}/notify
+        send_types 미전달시 서버가 빈 배열로 처리한다.
+        ⚠️ 실제 고객에게 알림이 발송되므로 테스트 호출 주의.
+        :param invoice_id: 청구서 ID
+        :param send_types: 발송 타입 배열 (예: [1, 2] - SMS, Email 등)
+        :param idempotency_key: 미지정시 자동 생성
+        :return: None
+        """
+        payload = {}
+        if send_types is not None:
+            payload['send_types'] = send_types
+        return self._bootpay.post(
+            f'invoices/{invoice_id}/notify',
+            payload,
+            headers=self._invoice_headers(idempotency_key)
+        )
+
+    def detail(self, invoice_id: str, idempotency_key: Optional[str] = None):
+        """
+        청구서 상세 조회
+        GET /v1/invoices/{invoice_id}
+        :param invoice_id: 청구서 ID
+        :param idempotency_key: 미지정시 자동 생성
+        :return: CommerceInvoice
+        """
+        return self._bootpay.get(
+            f'invoices/{invoice_id}',
+            headers=self._invoice_headers(idempotency_key)
+        )
+
+    def _invoice_headers(self, idempotency_key: Optional[str] = None) -> Dict[str, str]:
+        """
+        청구서 API 요청 헤더
+        Idempotency-Key 는 미지정시 매 호출마다 생성된다.
+        """
+        return {
+            'Idempotency-Key': idempotency_key or str(uuid.uuid4()),
+            'BOOTPAY-ROLE': 'user'
+        }

bootpay_backend-2.7.0/bootpay_backend/commerce/modules/mall_setting.py

@@ -0,0 +1,63 @@
+import uuid
+from typing import TYPE_CHECKING, Optional, Dict, Any
+
+if TYPE_CHECKING:
+    from ..commerce_resource import BootpayCommerceResource
+
+from ..types import (
+    CommerceMallSetting,
+    MallSettingUpdateParams
+)
+
+
+class MallSettingModule:
+    """몰 설정 모듈 (supervisor scope 전용)"""
+
+    def __init__(self, bootpay: 'BootpayCommerceResource'):
+        self._bootpay = bootpay
+
+    def get_mall_setting(self, idempotency_key: Optional[str] = None):
+        """
+        몰 설정 조회
+        GET /v1/mall-setting (supervisor scope 토큰 전용)
+        :param idempotency_key: 미지정시 자동 생성
+        :return: CommerceMallSetting
+        """
+        return self._bootpay.get('mall-setting', headers=self._supervisor_headers(idempotency_key))
+
+    def detail(self, idempotency_key: Optional[str] = None):
+        """get_mall_setting 별칭"""
+        return self.get_mall_setting(idempotency_key)
+
+    def update_mall_setting(self, params: MallSettingUpdateParams, idempotency_key: Optional[str] = None):
+        """
+        몰 설정 수정
+        PUT /v1/mall-setting (supervisor scope 토큰 전용)
+        요청 바디는 flatten 형식이며 전달된 값(non-None)만 서버로 전송된다.
+        :param params: 수정할 설정값
+        :param idempotency_key: 미지정시 자동 생성
+        :return: CommerceMallSetting
+        """
+        return self._bootpay.put(
+            'mall-setting',
+            self._compact(params),
+            headers=self._supervisor_headers(idempotency_key)
+        )
+
+    def update(self, params: MallSettingUpdateParams, idempotency_key: Optional[str] = None):
+        """update_mall_setting 별칭"""
+        return self.update_mall_setting(params, idempotency_key)
+
+    def _compact(self, params: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+        """None 값을 제거한다."""
+        return {k: v for k, v in (params or {}).items() if v is not None}
+
+    def _supervisor_headers(self, idempotency_key: Optional[str] = None) -> Dict[str, str]:
+        """
+        supervisor 전용 요청 헤더
+        Idempotency-Key 는 미지정시 매 호출마다 생성된다.
+        """
+        return {
+            'Idempotency-Key': idempotency_key or str(uuid.uuid4()),
+            'BOOTPAY-ROLE': 'supervisor'
+        }

{bootpay_backend-2.3.0 → bootpay_backend-2.7.0}/bootpay_backend/commerce/modules/order.py

@@ -36,6 +36,11 @@ class OrderModule:
                 query_params['user_group_id'] = params['user_group_id']
             if params.get('cs_type'):
                 query_params['cs_type'] = params['cs_type']
+            if params.get('search_date_from'):
+                query_params['search_date_from'] = params['search_date_from']
+            if params.get('search_date_to'):
+                query_params['search_date_to'] = params['search_date_to']
+            # css_at / cse_at 는 서버 별칭으로 계속 지원 (정식 키는 search_date_from / search_date_to)
             if params.get('css_at'):
                 query_params['css_at'] = params['css_at']
             if params.get('cse_at'):
@@ -47,7 +52,7 @@ class OrderModule:
             if params.get('payment_status') and len(params['payment_status']) > 0:
                 query_params['payment_status'] = ','.join(map(str, params['payment_status']))
             if params.get('order_subscription_ids') and len(params['order_subscription_ids']) > 0:
-                query_params['order_subscription_ids'] = ','.join(params['order_subscription_ids'])
+                query_params['order_subscription_ids'] = ','.join(map(str, params['order_subscription_ids']))
 
         query = urlencode(query_params) if query_params else ''
         return self._bootpay.get(f'orders{"?" + query if query else ""}')