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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bootpay_backend
-Version: 2.7.0
+Version: 2.9.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>
@@ -404,9 +404,11 @@ if 'error_code' not in token:
 
 ## 9-3. (별건) 현금영수증 발행
 부트페이 결제와 상관없이 금액, 상품명, 현금영수증 발행정보 등을 보내 현금영수증을 발행하는 API 입니다 
+
+`pg` 는 선택 파라미터입니다. 생략하면 프로젝트에 설정된 기본 PG 로 발행됩니다.
 ```python 
  response = bootpay.request_cash_receipt(
-        pg='토스',
+        pg='토스',  # 생략 가능 (미지정 시 기본 PG 사용)
         price=1000,
         order_name='테스트',
         cash_receipt_type='소득공제',

{bootpay_backend-2.7.0 → bootpay_backend-2.9.0}/README.md

@@ -364,9 +364,11 @@ if 'error_code' not in token:
 
 ## 9-3. (별건) 현금영수증 발행
 부트페이 결제와 상관없이 금액, 상품명, 현금영수증 발행정보 등을 보내 현금영수증을 발행하는 API 입니다 
+
+`pg` 는 선택 파라미터입니다. 생략하면 프로젝트에 설정된 기본 PG 로 발행됩니다.
 ```python 
  response = bootpay.request_cash_receipt(
-        pg='토스',
+        pg='토스',  # 생략 가능 (미지정 시 기본 PG 사용)
         price=1000,
         order_name='테스트',
         cash_receipt_type='소득공제',

{bootpay_backend-2.7.0 → bootpay_backend-2.9.0}/bootpay_backend/commerce/__init__.py

@@ -17,7 +17,19 @@ from .modules import (
     CartModule,
     OrderSubscriptionRequestModule,
     MallSettingModule,
-    WebhookModule
+    WebhookModule,
+    FaqModule,
+    NoticeModule,
+    InquiryModule,
+    ProductQnaModule,
+    ProductReviewModule,
+    AlimtalkMessageModule,
+    AlimtalkOfficialModule,
+    AlimtalkOptoutModule,
+    AlimtalkSendModule,
+    AlimtalkSenderModule,
+    AlimtalkTemplateModule,
+    AlimtalkWebhookModule
 )
 from .types import *
 
@@ -80,6 +92,20 @@ class BootpayCommerce(BootpayCommerceResource):
         self.order_subscription_request = OrderSubscriptionRequestModule(self)
         self.mall_setting = MallSettingModule(self)
         self.webhook = WebhookModule(self)
+        # 게시판 계열 (FAQ·공지사항·1:1문의·상품문의·상품평)
+        self.faq = FaqModule(self)
+        self.notice = NoticeModule(self)
+        self.inquiry = InquiryModule(self)
+        self.product_qna = ProductQnaModule(self)
+        self.product_review = ProductReviewModule(self)
+        # 알림톡 (/alimtalk 계열 — 메시지 API 호스트) — 주문·구독 웹훅과 별개다
+        self.alimtalk_message = AlimtalkMessageModule(self)
+        self.alimtalk_official = AlimtalkOfficialModule(self)
+        self.alimtalk_optout = AlimtalkOptoutModule(self)
+        self.alimtalk_send = AlimtalkSendModule(self)
+        self.alimtalk_sender = AlimtalkSenderModule(self)
+        self.alimtalk_template = AlimtalkTemplateModule(self)
+        self.alimtalk_webhook = AlimtalkWebhookModule(self)
 
     def get_access_token(self):
         """
@@ -212,6 +238,18 @@ __all__ = [
     'OrderSubscriptionRequestModule',
     'MallSettingModule',
     'WebhookModule',
+    'FaqModule',
+    'NoticeModule',
+    'InquiryModule',
+    'ProductQnaModule',
+    'ProductReviewModule',
+    'AlimtalkMessageModule',
+    'AlimtalkOfficialModule',
+    'AlimtalkOptoutModule',
+    'AlimtalkSendModule',
+    'AlimtalkSenderModule',
+    'AlimtalkTemplateModule',
+    'AlimtalkWebhookModule',
     # Types
     'ListParams',
     'CommerceAddress',
@@ -309,4 +347,31 @@ __all__ = [
     'MallSettingUpdateParams',
     'CommerceMallSetting',
     'SendTestWebhookParams',
+    # Alimtalk Types
+    'ALIMTALK_WEBHOOK_EVENT_SEND_REQUESTED',
+    'ALIMTALK_WEBHOOK_EVENT_SEND_SUCCESS',
+    'ALIMTALK_WEBHOOK_EVENT_SEND_FAILED',
+    'ALIMTALK_WEBHOOK_EVENT_SEND_CANCELED',
+    'ALIMTALK_WEBHOOK_EVENT_FALLBACK_SENT',
+    'ALIMTALK_WEBHOOK_EVENT_TEMPLATE_APPROVED',
+    'ALIMTALK_WEBHOOK_EVENT_TEMPLATE_REJECTED',
+    'ALIMTALK_WEBHOOK_EVENT_OPTOUT_CREATED',
+    'AlimtalkMessageListParams',
+    'AlimtalkMessageStatsParams',
+    'AlimtalkOfficialListParams',
+    'AlimtalkOfficialRecommendParams',
+    'AlimtalkOptoutListParams',
+    'AlimtalkOptoutCreateParams',
+    'AlimtalkOptoutCheckParams',
+    'AlimtalkSendParams',
+    'AlimtalkSendRecipient',
+    'AlimtalkSendBulkParams',
+    'AlimtalkSenderOtpParams',
+    'AlimtalkSenderCreateParams',
+    'AlimtalkTemplateListParams',
+    'AlimtalkTemplateCreateParams',
+    'AlimtalkTemplateUpdateParams',
+    'AlimtalkTemplateExportParams',
+    'AlimtalkWebhookUpdateParams',
+    'AlimtalkWebhookDeliveryListParams',
 ]

{bootpay_backend-2.7.0 → bootpay_backend-2.9.0}/bootpay_backend/commerce/commerce_resource.py

@@ -13,6 +13,13 @@ class BootpayCommerceResource:
         'stage': 'https://stage-api.bootapi.com/v1',
         'production': 'https://api.bootapi.com/v1'
     }
+    # 알림톡 API 전용 — 메시지 API 가 직접 받는다(경로에 /v1 없음). _api_base_url 이 고른다.
+    # @date: 26-09-18
+    MESSAGE_API_ENTRYPOINTS = {
+        'development': 'https://dev-m.bootapi.com',
+        'stage': 'https://stage-m.bootapi.com',
+        'production': 'https://message.bootapi.com'
+    }
     API_VERSION = '1.0.0'
     SDK_VERSION = '1.0.0'
 
@@ -23,6 +30,7 @@ class BootpayCommerceResource:
         self.client_key: Optional[str] = None
         self.secret_key: Optional[str] = None
         self.timeout = 60
+        self._message_api_url: Optional[str] = None
 
     def set_configuration(self, client_key: str, secret_key: str, mode: str = 'production'):
         """
@@ -64,9 +72,27 @@ class BootpayCommerceResource:
         encoded = base64.b64encode(credentials.encode()).decode()
         return f'Basic {encoded}'
 
+    def set_message_api_url(self, url: str):
+        """
+        알림톡(메시지 API) URL 을 변경한다.
+        @date: 26-09-18
+        """
+        self._message_api_url = url
+
+    def _api_base_url(self, url: str) -> str:
+        """
+        요청 경로에 맞는 API 기본 주소.
+        알림톡 API 는 26-09-18 부터 커머스 API(api.bootapi.com/v1)가 아니라 메시지 API(message.bootapi.com, /v1 없음)가 받는다.
+        경로·파라미터·응답은 그대로이고 호스트만 다르다 — 그래서 알림톡 모듈은 고치지 않고 여기서 주소만 가른다.
+        옛 주소(/v1/alimtalk/*)는 410 으로 응답한다.
+        """
+        if url.lstrip('/').startswith('alimtalk'):
+            return self._message_api_url or self.MESSAGE_API_ENTRYPOINTS[self.mode]
+        return self.API_ENTRYPOINTS[self.mode]
+
     def _entrypoints(self, url: str) -> str:
         """엔트리포인트 URL 생성"""
-        return '/'.join([self.API_ENTRYPOINTS[self.mode], url])
+        return '/'.join([self._api_base_url(url), url])
 
     def _get_headers(self, include_auth: bool = True, headers: Optional[Dict[str, str]] = None) -> Dict[str, str]:
         """
@@ -134,6 +160,93 @@ class BootpayCommerceResource:
         :param image_paths: 이미지 파일 경로 배열
         :param headers: 요청별 추가 헤더 (공통값을 덮어쓴다)
         """
+        request_headers = self._multipart_headers(headers)
+        form_data = self._serialize_form_data(data)
+
+        # 파일 준비
+        # ⚠️ Rails 는 반복된 `images` 를 배열로 받지 않는다. images[0], images[1] ... 로 인덱싱해야 한다.
+        files = []
+        if image_paths:
+            for index, image_path in enumerate(image_paths):
+                filename = os.path.basename(image_path)
+                files.append((f'images[{index}]', (filename, open(image_path, 'rb'))))
+
+        try:
+            response = requests.post(
+                self._entrypoints(url),
+                headers=request_headers,
+                data=form_data,
+                files=files if files else None,
+                timeout=self.timeout
+            )
+            return response.json()
+        finally:
+            # 파일 핸들 닫기
+            for _, file_tuple in files:
+                file_tuple[1].close()
+
+    def post_multipart_file(self, url: str, field: str, file: Any, data: Optional[Dict] = None,
+                            headers: Optional[Dict[str, str]] = None):
+        """
+        단일 파일 필드 multipart/form-data POST 요청
+        ⚠️ post_multipart 는 Rails 배열 규약(images[0], images[1] ...) 전용이다.
+           알림톡 템플릿 이미지처럼 서버가 필드명을 정해 둔 단일 파일 업로드는 이 메서드를 쓴다.
+           images[0] 으로 올리면 서버가 파일을 찾지 못한다.
+        :param url: 요청 URL
+        :param field: 파일 폼 필드명 (예: 'image')
+        :param file: 파일 경로(str) 또는 이미 열린 파일 객체
+        :param data: 함께 보낼 폼 데이터
+        :param headers: 요청별 추가 헤더 (공통값을 덮어쓴다)
+        """
+        request_headers = self._multipart_headers(headers)
+        form_data = self._serialize_form_data(data or {})
+
+        # 경로를 받으면 여기서 열고 반드시 닫는다. 파일 객체를 받으면 호출자 소유이므로 닫지 않는다.
+        opened = open(file, 'rb') if isinstance(file, str) else None
+        handle = opened if opened is not None else file
+        filename = os.path.basename(file if isinstance(file, str) else getattr(file, 'name', field))
+
+        try:
+            response = requests.post(
+                self._entrypoints(url),
+                headers=request_headers,
+                data=form_data,
+                files={field: (filename, handle)},
+                timeout=self.timeout
+            )
+            return response.json()
+        finally:
+            if opened is not None:
+                opened.close()
+
+    def get_raw(self, url: str, params: Optional[Dict] = None, headers: Optional[Dict[str, str]] = None):
+        """
+        JSON 이 아닌 본문(CSV 등)을 파싱하지 않고 그대로 받는다.
+        ⚠️ 공용 get 은 응답을 무조건 response.json() 으로 파싱하므로, CSV 를 돌려주는 endpoint
+           (알림톡 템플릿 내보내기 format=csv)에서는 성공한 요청이 파싱 예외로 터진다.
+           실제로는 200 이라 원인을 찾기 어려워서 원문 경로를 따로 둔다.
+        :return: {'body': str, 'content_type': str, 'status': int}
+        """
+        # 원문 경로라 Accept 를 */* 로 낮춘다 (요청별로 지정했다면 그 값을 존중한다).
+        request_headers = self._get_headers(headers={'Accept': '*/*', **(headers or {})})
+        response = requests.get(
+            self._entrypoints(url),
+            headers=request_headers,
+            params=params,
+            timeout=self.timeout
+        )
+        return {
+            'body': response.text,
+            'content_type': response.headers.get('Content-Type', ''),
+            'status': response.status_code
+        }
+
+    def _multipart_headers(self, headers: Optional[Dict[str, str]] = None) -> Dict[str, str]:
+        """
+        multipart 요청 공통 헤더
+        ⚠️ Content-Type 은 넣지 않는다 — requests 가 생성한 값(boundary 포함)을 그대로 써야 한다.
+           직접 지정하면 boundary 가 사라져 본문이 서버에서 null 로 파싱된다.
+        """
         request_headers = {
             'Accept': 'application/json',
             'Accept-Charset': 'utf-8',
@@ -147,10 +260,14 @@ class BootpayCommerceResource:
             request_headers['Authorization'] = basic_auth
         if headers:
             request_headers.update(headers)
+        return request_headers
 
-        # 폼 데이터 준비
-        # ⚠️ bool 은 소문자 'true'/'false' 로 보낸다 — str(True) 의 'True'/'False' 는
-        #    Rails 캐스팅 대상이 아니라서 "False" 가 true 로 해석되는 실위험이 있다.
+    def _serialize_form_data(self, data: Dict) -> Dict[str, str]:
+        """
+        폼 데이터 직렬화
+        ⚠️ bool 은 소문자 'true'/'false' 로 보낸다 — str(True) 의 'True'/'False' 는
+           Rails 캐스팅 대상이 아니라서 "False" 가 true 로 해석되는 실위험이 있다.
+        """
         form_data = {}
         for key, value in data.items():
             if value is not None:
@@ -160,28 +277,7 @@ class BootpayCommerceResource:
                     form_data[key] = json.dumps(value)
                 else:
                     form_data[key] = str(value)
-
-        # 파일 준비
-        # ⚠️ Rails 는 반복된 `images` 를 배열로 받지 않는다. images[0], images[1] ... 로 인덱싱해야 한다.
-        files = []
-        if image_paths:
-            for index, image_path in enumerate(image_paths):
-                filename = os.path.basename(image_path)
-                files.append((f'images[{index}]', (filename, open(image_path, 'rb'))))
-
-        try:
-            response = requests.post(
-                self._entrypoints(url),
-                headers=request_headers,
-                data=form_data,
-                files=files if files else None,
-                timeout=self.timeout
-            )
-            return response.json()
-        finally:
-            # 파일 핸들 닫기
-            for _, file_tuple in files:
-                file_tuple[1].close()
+        return form_data
 
     def put(self, url: str, data: Optional[Dict] = None, headers: Optional[Dict[str, str]] = None):
         """PUT 요청"""

{bootpay_backend-2.7.0 → bootpay_backend-2.9.0}/bootpay_backend/commerce/modules/__init__.py

@@ -16,6 +16,18 @@ from .cart import CartModule
 from .order_subscription_request import OrderSubscriptionRequestModule
 from .mall_setting import MallSettingModule
 from .webhook import WebhookModule
+from .faq import FaqModule
+from .notice import NoticeModule
+from .inquiry import InquiryModule
+from .product_qna import ProductQnaModule
+from .product_review import ProductReviewModule
+from .alimtalk_message import AlimtalkMessageModule
+from .alimtalk_official import AlimtalkOfficialModule
+from .alimtalk_optout import AlimtalkOptoutModule
+from .alimtalk_send import AlimtalkSendModule
+from .alimtalk_sender import AlimtalkSenderModule
+from .alimtalk_template import AlimtalkTemplateModule
+from .alimtalk_webhook import AlimtalkWebhookModule
 
 __all__ = [
     'UserModule',
@@ -34,5 +46,17 @@ __all__ = [
     'CartModule',
     'OrderSubscriptionRequestModule',
     'MallSettingModule',
-    'WebhookModule'
+    'WebhookModule',
+    'FaqModule',
+    'NoticeModule',
+    'InquiryModule',
+    'ProductQnaModule',
+    'ProductReviewModule',
+    'AlimtalkMessageModule',
+    'AlimtalkOfficialModule',
+    'AlimtalkOptoutModule',
+    'AlimtalkSendModule',
+    'AlimtalkSenderModule',
+    'AlimtalkTemplateModule',
+    'AlimtalkWebhookModule'
 ]

bootpay_backend-2.9.0/bootpay_backend/commerce/modules/alimtalk_message.py

@@ -0,0 +1,90 @@
+from typing import TYPE_CHECKING, Optional, Dict, Any
+from urllib.parse import urlencode
+
+if TYPE_CHECKING:
+    from ..commerce_resource import BootpayCommerceResource
+
+from ..types import (
+    AlimtalkMessageListParams,
+    AlimtalkMessageStatsParams
+)
+
+
+class AlimtalkMessageModule:
+    """
+    알림톡 발송내역·집계 모듈 (GET /alimtalk/messages 계열)
+
+    **유료** 알림톡만 조회된다 (무료 커머스 알림톡은 포함되지 않는다).
+    상태는 벤더 결과 동기화로 확정되므로 접수 직후에는 requested 로 보인다.
+    """
+
+    def __init__(self, bootpay: 'BootpayCommerceResource'):
+        self._bootpay = bootpay
+
+    def list(self, params: Optional[AlimtalkMessageListParams] = None):
+        """
+        발송내역 목록 조회
+        GET /alimtalk/messages
+        ⚠️ 기간 기본값은 최근 30일이고 최대 조회 폭은 92일이다 — 초과분은 거부하지 않고 시작일을 당겨 잘라낸다.
+           실제 적용된 구간은 응답의 period 로 확인한다.
+        :param params: 조회 파라미터 (status: requested·success·failed·canceled)
+        :return: {'list': [...], 'count': int, 'page': int, 'per': int, 'period': {'from':, 'to':}}
+        """
+        query = urlencode(self._query(params))
+        return self._bootpay.get(
+            f'alimtalk/messages{"?" + query if query else ""}',
+            headers=self._alimtalk_headers()
+        )
+
+    def stats(self, params: Optional[AlimtalkMessageStatsParams] = None):
+        """
+        기간 집계 조회
+        GET /alimtalk/messages/stats
+        일자별 집계 원장에서 읽으므로 응답이 빠르다.
+        ⚠️ billing.unit_price_source 가 'default' 면 **잠정 단가**다 (확정 청구액이 아니다).
+        ⚠️ billable_count 는 성공 − 폴백이다 — 폴백분은 LMS 단가로 따로 계산된다.
+        :param params: 조회 기간
+        :return: {'period':, 'totals': {...}, 'daily': [...], 'billing': {...}}
+        """
+        query = urlencode(self._query(params))
+        return self._bootpay.get(
+            f'alimtalk/messages/stats{"?" + query if query else ""}',
+            headers=self._alimtalk_headers()
+        )
+
+    def detail(self, receipt_id: str):
+        """
+        단건 발송 결과 조회
+        GET /alimtalk/messages/{receipt_id}
+        실패 사유는 error_code·error_message 에 담긴다.
+        fallback_type 은 폴백이 꺼진 건이면 None, 켜진 건이면 LMS 다.
+        다른 프로젝트의 건이거나 없으면 404(3025).
+        :param receipt_id: 발송 접수 ID
+        :return: 발송 상세
+        """
+        return self._bootpay.get(
+            f'alimtalk/messages/{receipt_id}',
+            headers=self._alimtalk_headers()
+        )
+
+    def _query(self, params: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+        """
+        None 을 제거하고 bool 을 소문자 'true'/'false' 로 직렬화한다.
+        ⚠️ urlencode 는 True 를 'True' 로 쓴다 — Rails 의 boolean 캐스팅은 'False' 를 참으로 읽으므로
+           그대로 보내면 false 가 true 로 뒤집힌다.
+        """
+        query = {}
+        for key, value in (params or {}).items():
+            if value is None:
+                continue
+            query[key] = ('true' if value else 'false') if isinstance(value, bool) else value
+        return query
+
+    def _alimtalk_headers(self) -> Dict[str, str]:
+        """
+        알림톡 API 요청 헤더
+        ★Idempotency-Key 를 싣지 않는다★ 알림톡 API 는 이 헤더를 읽지 않는다
+          (멱등은 발송의 ref_id 로만 성립한다).
+        ★BOOTPAY-ROLE 은 항상 user★ 알림톡 스코프 키가 전부 user:alimtalk_* 다.
+        """
+        return {'BOOTPAY-ROLE': 'user'}

bootpay_backend-2.9.0/bootpay_backend/commerce/modules/alimtalk_official.py

@@ -0,0 +1,90 @@
+from typing import TYPE_CHECKING, Optional, Dict, Any
+from urllib.parse import urlencode
+
+if TYPE_CHECKING:
+    from ..commerce_resource import BootpayCommerceResource
+
+from ..types import (
+    AlimtalkOfficialListParams,
+    AlimtalkOfficialRecommendParams
+)
+
+
+class AlimtalkOfficialModule:
+    """
+    부트페이 공식 알림톡 템플릿 카탈로그 모듈 (/alimtalk/official 계열)
+
+    부트페이가 미리 카카오 승인을 받아 둔 템플릿이라, 그룹키가 등록된 채널이면 **검수 없이 즉시 발송**된다.
+    `alimtalk_sender.create` 로 채널을 등록하면 그룹 등록이 함께 끝나므로 따로 채택할 것이 없다.
+    (채택 endpoint 는 서버에서도 비활성화되어 SDK 에 두지 않는다)
+
+    전부 조회 계열이라 부작용이 없다 (자체 DB 만 본다).
+    """
+
+    def __init__(self, bootpay: 'BootpayCommerceResource'):
+        self._bootpay = bootpay
+
+    def list(self, params: Optional[AlimtalkOfficialListParams] = None):
+        """
+        공식 템플릿 검색
+        GET /alimtalk/official
+        keyword 는 본문·이름·분류를 부분일치(대소문자 무시)로 훑는다.
+        ⚠️ 서버는 q 를 먼저 보고 없으면 keyword 를 본다 — 정본 키인 q 로 보낸다.
+        :param params: 조회 파라미터 (msg_type 은 BA·EX 만 존재한다)
+        :return: {'list': [...], 'count': int, 'page': int, 'per': int, 'categories': [...]}
+        """
+        params = dict(params or {})
+        query_params = {
+            'q': params.pop('q', None) or params.pop('keyword', None),
+            'category': params.get('category'),
+            'msg_type': params.get('msg_type'),
+            'page': params.get('page'),
+            'per': params.get('per'),
+            'ksp_id': params.get('ksp_id')
+        }
+
+        query = urlencode(self._compact(query_params))
+        return self._bootpay.get(
+            f'alimtalk/official{"?" + query if query else ""}',
+            headers=self._alimtalk_headers()
+        )
+
+    def recommend(self, params: AlimtalkOfficialRecommendParams):
+        """
+        보내려는 문구로 공식 템플릿을 추천받는다
+        POST /alimtalk/official/recommend
+        유사도 score(0~1) 내림차순으로 돌려준다.
+        :param params: 추천 파라미터 (text 필수)
+        :return: 추천 템플릿 목록
+        """
+        return self._bootpay.post(
+            'alimtalk/official/recommend',
+            self._compact(params),
+            headers=self._alimtalk_headers()
+        )
+
+    def detail(self, code: str, ksp_id: Optional[str] = None):
+        """
+        공식 템플릿 상세 조회
+        GET /alimtalk/official/{code}
+        :param code: 서버 채번 코드 (슬래시를 포함하지 않는다). 없거나 미노출이면 404(3015).
+        :param ksp_id: 주면 그 채널의 변수 예문 사전으로 variable_examples 를 채워 준다 (표시용)
+        :return: 공식 템플릿 상세
+        """
+        query = urlencode(self._compact({'ksp_id': ksp_id}))
+        return self._bootpay.get(
+            f'alimtalk/official/{code}{"?" + query if query else ""}',
+            headers=self._alimtalk_headers()
+        )
+
+    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 _alimtalk_headers(self) -> Dict[str, str]:
+        """
+        알림톡 API 요청 헤더
+        ★Idempotency-Key 를 싣지 않는다★ 알림톡 API 는 이 헤더를 읽지 않는다.
+        ★BOOTPAY-ROLE 은 항상 user★ 알림톡 스코프 키가 전부 user:alimtalk_* 다.
+        """
+        return {'BOOTPAY-ROLE': 'user'}

bootpay_backend-2.9.0/bootpay_backend/commerce/modules/alimtalk_optout.py

@@ -0,0 +1,97 @@
+from typing import TYPE_CHECKING, Optional, Dict, Any
+from urllib.parse import urlencode
+
+if TYPE_CHECKING:
+    from ..commerce_resource import BootpayCommerceResource
+
+from ..types import (
+    AlimtalkOptoutListParams,
+    AlimtalkOptoutCreateParams,
+    AlimtalkOptoutCheckParams
+)
+
+
+class AlimtalkOptoutModule:
+    """
+    알림톡 수신거부 모듈 (/alimtalk/optouts 계열, 가맹점 CRM 수신거부 동기화용)
+
+    발송 판정과 **같은 기준**으로 다룬다 — 부트페이 전역(global) + 내 프로젝트.
+    ⚠️ 전역 건은 **조회는 되지만 해제할 수 없다** (releasable: False).
+       이걸 노출하지 않으면 "화면엔 수신거부가 아닌데 발송은 3021 로 막히는" 상태가 된다.
+    """
+
+    def __init__(self, bootpay: 'BootpayCommerceResource'):
+        self._bootpay = bootpay
+
+    def list(self, params: Optional[AlimtalkOptoutListParams] = None):
+        """
+        수신거부 목록 조회
+        GET /alimtalk/optouts
+        phone 은 숫자만 남겨 **부분일치**로 찾는다 (정확 매칭이 아니다). 50건 단위로 페이징된다.
+        :param params: 조회 파라미터
+        :return: {'list': [{'id':, 'phone':, 'scope':, 'global':, 'releasable':, 'source':,
+                            'reason':, 'opted_out_at':, 'created_at':}], 'count': int, 'page': int}
+        """
+        query = urlencode(self._compact(params))
+        return self._bootpay.get(
+            f'alimtalk/optouts{"?" + query if query else ""}',
+            headers=self._alimtalk_headers()
+        )
+
+    def create(self, params: AlimtalkOptoutCreateParams):
+        """
+        수신거부 등록
+        POST /alimtalk/optouts
+        내 프로젝트 스코프로 등록된다 (source: api). 같은 번호를 다시 등록해도 멱등이다.
+        :param params: 등록 파라미터 (phone 필수)
+        :return: 등록된 수신거부
+        """
+        return self._bootpay.post(
+            'alimtalk/optouts',
+            self._compact(params),
+            headers=self._alimtalk_headers()
+        )
+
+    def check(self, params: AlimtalkOptoutCheckParams):
+        """
+        발송 전 수신거부 사전 확인
+        POST /alimtalk/optouts/check
+        발송 판정과 **같은 축**으로 대조하므로, 벌크에서 skipped 로 낭비될 건을 미리 뺄 수 있다.
+        단건(phone)·다건(phones) 모두 받는다.
+        ⚠️ 1회 최대 1,000건이고 넘으면 -48 이다 (중복은 서버가 제거).
+        :param params: 확인 파라미터
+        :return: {'list': [{'phone':, 'opted_out':, 'global':, 'releasable':, 'opted_out_at':}],
+                  'count': int, 'opted_out_count': int}
+        """
+        return self._bootpay.post(
+            'alimtalk/optouts/check',
+            self._compact(params),
+            headers=self._alimtalk_headers()
+        )
+
+    def release(self, phone: str):
+        """
+        수신거부 해제
+        DELETE /alimtalk/optouts/{phone}
+        내 프로젝트 스코프 건만 해제되며 멱등이다 (없어도 성공).
+        ⚠️ 전역 차단은 해제되지 않고 global_blocked: True 로 알려 준다 —
+           "지웠는데 여전히 막히는" 상태를 응답으로 드러내기 위함이다.
+        :param phone: 해제할 수신번호
+        :return: {'phone':, 'released':, 'global_blocked':}
+        """
+        return self._bootpay.delete(
+            f'alimtalk/optouts/{phone}',
+            headers=self._alimtalk_headers()
+        )
+
+    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 _alimtalk_headers(self) -> Dict[str, str]:
+        """
+        알림톡 API 요청 헤더
+        ★Idempotency-Key 를 싣지 않는다★ 알림톡 API 는 이 헤더를 읽지 않는다.
+        ★BOOTPAY-ROLE 은 항상 user★ 알림톡 스코프 키가 전부 user:alimtalk_* 다.
+        """
+        return {'BOOTPAY-ROLE': 'user'}