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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bootpay_backend
-Version: 2.9.0
+Version: 2.10.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>
@@ -69,6 +69,8 @@ Python 언어로 작성된 어플리케이션, 프레임워크 등에서 사용
    - [9-2. 현금영수증 발행 취소](#9-2-현금영수증-발행-취소)
    - [9-3. 별건 현금영수증 발행](#9-3-별건-현금영수증-발행)
    - [9-4. 별건 현금영수증 발행 취소](#9-4-별건-현금영수증-발행-취소)
+   - [10. 뱅크알람 입금대기](#10-뱅크알람-입금대기-무통장-입금-자동-확인)
+   - [11. 입점사 지급 요청](#11-입점사-지급-요청)
 - [Example 프로젝트](#example-프로젝트)
 - [Documentation](#documentation)
 - [기술문의](#기술문의)
@@ -440,6 +442,89 @@ if 'error_code' not in token:
    print(response)
 ```
 
+## 10. 뱅크알람 입금대기 (무통장 입금 자동 확인)
+
+가맹점 서버가 아직 입금되지 않은 주문을 등록하면, 판매자 폰의 입금 알림 중 **금액 · 입금자명**이 맞는 것을
+뱅크알람이 그 주문에 연결해 입금을 확인하고 입금 웹훅으로 알립니다.
+전부 supervisor 전용이며, 인스턴스 role 과 무관하게 `BOOTPAY-ROLE: supervisor` 로 나갑니다.
+
+```python
+import os
+
+from bootpay_backend.commerce import BootpayCommerce
+
+commerce = BootpayCommerce(
+    client_key=os.getenv('BOOTPAY_COMMERCE_CLIENT_KEY_PROD'),
+    secret_key=os.getenv('BOOTPAY_COMMERCE_SECRET_KEY_PROD')
+)
+commerce.get_access_token()
+
+# 판매자 입금 계좌 목록 — 첫 계좌가 대표 계좌(primary: true)
+accounts = commerce.deposit.accounts()['accounts']
+
+# 웹훅 서명 비밀값 발급 — ⚠️ 원문은 이 응답에서만 받습니다. 다시 부르면 바뀝니다
+secret = commerce.deposit.webhook_secret()['secret']
+
+# 입금대기 등록 — 같은 merchant_order_id 로 같은 금액·입금자명·계좌를 다시 보내면 기존 주문을 돌려줍니다
+# (하나라도 다르면 18110 BANK_DEPOSIT_MERCHANT_ID_CONFLICT)
+commerce.deposit.create({
+    'merchant_order_id': 'ORDER_1234',
+    'price': 15000,
+    'depositor': '홍길동',               # 은행 입금 알림과 맞춰 볼 이름
+    'order_name': '티셔츠 외 1건',       # 미지정시 '무통장 입금'
+    'memo': '관리자 메모',
+    'buyer_name': '홍길동',              # 미지정시 입금자명
+    'buyer_email': 'buyer@example.com',  # 주면 입금 안내 · 확인 메일 (무료)
+    'account_id': accounts[0]['id'],      # 미지정시 대표 계좌
+    'webhook_url': 'https://example.com/hooks/deposit',  # 비밀값을 먼저 발급받아야 합니다(18131)
+    # 구매자 알림톡 (유료) — buyer_phone 필수, link 는 https
+    # 'notify': {'deposit_guide': True, 'deposit_paid': True, 'link': 'https://example.com/orders/ORDER_1234'},
+})
+
+# 조회 · 취소 — 가맹점 주문번호 또는 부트페이 주문번호
+commerce.deposit.detail('ORDER_1234')  # status: awaiting · paid · expired · cancelled
+commerce.deposit.cancel('ORDER_1234')  # 이미 닫힌 주문은 그대로 돌려줍니다
+```
+
+`webhook_secret(idempotency_key=None)` · `cancel(id, idempotency_key=None)` 은 멱등 키 선택 인자를 받고,
+`create(params)` 는 `params['idempotency_key']` 로 받습니다. 미지정시 호출할 때마다 새 UUID 를 사용합니다.
+
+> 입금 웹훅은 `X-Bootpay-Signature: sha256=HMAC_SHA256(secret, "{X-Bootpay-Timestamp}.{raw_body}")` 로 서명됩니다.
+> 이벤트 코드는 `BANK_DEPOSIT_WEBHOOK_EVENT_*` 상수(400~407)를 참고하세요.
+
+## 11. 입점사 지급 요청
+
+가맹점 지정 금액(`manual`) 정산 방식에서 입점사와 지급액을 정해 지급 원장에 등록합니다.
+실제 송금은 별도 배치가 처리하며, 세 API 모두 인스턴스 role과 무관하게 `BOOTPAY-ROLE: supervisor`로 나갑니다.
+
+```python
+from bootpay_backend.commerce import BootpayCommerce
+
+commerce = BootpayCommerce(client_key='CLIENT_KEY', secret_key='SECRET_KEY')
+
+# 등록 — 같은 merchant_payout_id 재호출은 처음 생성한 항목을 돌려줍니다
+commerce.payout.create({
+    'sub_seller_id': 'SUB_SELLER_ID',
+    'amount': 150000,
+    'merchant_payout_id': 'PAYOUT_20261112_001',
+    'order_number': 'ORDER_1234',       # 선택
+    'payout_date': '2026-11-20',        # 선택, YYYY-MM-DD
+})
+
+# merchant_payout_id 또는 지급 항목 id로 조회
+commerce.payout.detail('PAYOUT_20261112_001')
+
+# 목록은 전체 개수 래퍼 없는 지급 항목 배열입니다
+commerce.payout.list({
+    'status': 'ready', 'sub_seller_id': 'SUB_SELLER_ID',
+    'from': '2026-11-01', 'to': '2026-11-30', 'page': 1, 'limit': 20,
+})
+```
+
+`status`는 `ready` · `held` · `sending` · `requested` · `processing` · `succeeded` · `failed` ·
+`cancelled` · `unknown` · `void` 중 하나입니다. 세 메서드 모두 명시적 `idempotency_key`를 받을 수 있고,
+미지정하면 호출마다 새 UUID를 사용합니다.
+
 ## Example 프로젝트
 
 [적용한 샘플 프로젝트](https://github.com/bootpay/backend-python-example)을 참조해주세요

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

@@ -29,6 +29,8 @@ Python 언어로 작성된 어플리케이션, 프레임워크 등에서 사용
    - [9-2. 현금영수증 발행 취소](#9-2-현금영수증-발행-취소)
    - [9-3. 별건 현금영수증 발행](#9-3-별건-현금영수증-발행)
    - [9-4. 별건 현금영수증 발행 취소](#9-4-별건-현금영수증-발행-취소)
+   - [10. 뱅크알람 입금대기](#10-뱅크알람-입금대기-무통장-입금-자동-확인)
+   - [11. 입점사 지급 요청](#11-입점사-지급-요청)
 - [Example 프로젝트](#example-프로젝트)
 - [Documentation](#documentation)
 - [기술문의](#기술문의)
@@ -400,6 +402,89 @@ if 'error_code' not in token:
    print(response)
 ```
 
+## 10. 뱅크알람 입금대기 (무통장 입금 자동 확인)
+
+가맹점 서버가 아직 입금되지 않은 주문을 등록하면, 판매자 폰의 입금 알림 중 **금액 · 입금자명**이 맞는 것을
+뱅크알람이 그 주문에 연결해 입금을 확인하고 입금 웹훅으로 알립니다.
+전부 supervisor 전용이며, 인스턴스 role 과 무관하게 `BOOTPAY-ROLE: supervisor` 로 나갑니다.
+
+```python
+import os
+
+from bootpay_backend.commerce import BootpayCommerce
+
+commerce = BootpayCommerce(
+    client_key=os.getenv('BOOTPAY_COMMERCE_CLIENT_KEY_PROD'),
+    secret_key=os.getenv('BOOTPAY_COMMERCE_SECRET_KEY_PROD')
+)
+commerce.get_access_token()
+
+# 판매자 입금 계좌 목록 — 첫 계좌가 대표 계좌(primary: true)
+accounts = commerce.deposit.accounts()['accounts']
+
+# 웹훅 서명 비밀값 발급 — ⚠️ 원문은 이 응답에서만 받습니다. 다시 부르면 바뀝니다
+secret = commerce.deposit.webhook_secret()['secret']
+
+# 입금대기 등록 — 같은 merchant_order_id 로 같은 금액·입금자명·계좌를 다시 보내면 기존 주문을 돌려줍니다
+# (하나라도 다르면 18110 BANK_DEPOSIT_MERCHANT_ID_CONFLICT)
+commerce.deposit.create({
+    'merchant_order_id': 'ORDER_1234',
+    'price': 15000,
+    'depositor': '홍길동',               # 은행 입금 알림과 맞춰 볼 이름
+    'order_name': '티셔츠 외 1건',       # 미지정시 '무통장 입금'
+    'memo': '관리자 메모',
+    'buyer_name': '홍길동',              # 미지정시 입금자명
+    'buyer_email': 'buyer@example.com',  # 주면 입금 안내 · 확인 메일 (무료)
+    'account_id': accounts[0]['id'],      # 미지정시 대표 계좌
+    'webhook_url': 'https://example.com/hooks/deposit',  # 비밀값을 먼저 발급받아야 합니다(18131)
+    # 구매자 알림톡 (유료) — buyer_phone 필수, link 는 https
+    # 'notify': {'deposit_guide': True, 'deposit_paid': True, 'link': 'https://example.com/orders/ORDER_1234'},
+})
+
+# 조회 · 취소 — 가맹점 주문번호 또는 부트페이 주문번호
+commerce.deposit.detail('ORDER_1234')  # status: awaiting · paid · expired · cancelled
+commerce.deposit.cancel('ORDER_1234')  # 이미 닫힌 주문은 그대로 돌려줍니다
+```
+
+`webhook_secret(idempotency_key=None)` · `cancel(id, idempotency_key=None)` 은 멱등 키 선택 인자를 받고,
+`create(params)` 는 `params['idempotency_key']` 로 받습니다. 미지정시 호출할 때마다 새 UUID 를 사용합니다.
+
+> 입금 웹훅은 `X-Bootpay-Signature: sha256=HMAC_SHA256(secret, "{X-Bootpay-Timestamp}.{raw_body}")` 로 서명됩니다.
+> 이벤트 코드는 `BANK_DEPOSIT_WEBHOOK_EVENT_*` 상수(400~407)를 참고하세요.
+
+## 11. 입점사 지급 요청
+
+가맹점 지정 금액(`manual`) 정산 방식에서 입점사와 지급액을 정해 지급 원장에 등록합니다.
+실제 송금은 별도 배치가 처리하며, 세 API 모두 인스턴스 role과 무관하게 `BOOTPAY-ROLE: supervisor`로 나갑니다.
+
+```python
+from bootpay_backend.commerce import BootpayCommerce
+
+commerce = BootpayCommerce(client_key='CLIENT_KEY', secret_key='SECRET_KEY')
+
+# 등록 — 같은 merchant_payout_id 재호출은 처음 생성한 항목을 돌려줍니다
+commerce.payout.create({
+    'sub_seller_id': 'SUB_SELLER_ID',
+    'amount': 150000,
+    'merchant_payout_id': 'PAYOUT_20261112_001',
+    'order_number': 'ORDER_1234',       # 선택
+    'payout_date': '2026-11-20',        # 선택, YYYY-MM-DD
+})
+
+# merchant_payout_id 또는 지급 항목 id로 조회
+commerce.payout.detail('PAYOUT_20261112_001')
+
+# 목록은 전체 개수 래퍼 없는 지급 항목 배열입니다
+commerce.payout.list({
+    'status': 'ready', 'sub_seller_id': 'SUB_SELLER_ID',
+    'from': '2026-11-01', 'to': '2026-11-30', 'page': 1, 'limit': 20,
+})
+```
+
+`status`는 `ready` · `held` · `sending` · `requested` · `processing` · `succeeded` · `failed` ·
+`cancelled` · `unknown` · `void` 중 하나입니다. 세 메서드 모두 명시적 `idempotency_key`를 받을 수 있고,
+미지정하면 호출마다 새 UUID를 사용합니다.
+
 ## Example 프로젝트
 
 [적용한 샘플 프로젝트](https://github.com/bootpay/backend-python-example)을 참조해주세요

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

@@ -18,6 +18,8 @@ from .modules import (
     OrderSubscriptionRequestModule,
     MallSettingModule,
     WebhookModule,
+    DepositModule,
+    PayoutModule,
     FaqModule,
     NoticeModule,
     InquiryModule,
@@ -92,6 +94,8 @@ class BootpayCommerce(BootpayCommerceResource):
         self.order_subscription_request = OrderSubscriptionRequestModule(self)
         self.mall_setting = MallSettingModule(self)
         self.webhook = WebhookModule(self)
+        self.deposit = DepositModule(self)
+        self.payout = PayoutModule(self)
         # 게시판 계열 (FAQ·공지사항·1:1문의·상품문의·상품평)
         self.faq = FaqModule(self)
         self.notice = NoticeModule(self)
@@ -238,6 +242,8 @@ __all__ = [
     'OrderSubscriptionRequestModule',
     'MallSettingModule',
     'WebhookModule',
+    'DepositModule',
+    'PayoutModule',
     'FaqModule',
     'NoticeModule',
     'InquiryModule',
@@ -347,6 +353,28 @@ __all__ = [
     'MallSettingUpdateParams',
     'CommerceMallSetting',
     'SendTestWebhookParams',
+    # Deposit Types
+    'DepositAccount',
+    'DepositAccountsResponse',
+    'DepositWebhookSecretResponse',
+    'DepositNotifyParams',
+    'DepositCreateParams',
+    'DepositNotice',
+    'DepositNotify',
+    'CommerceDeposit',
+    'BANK_DEPOSIT_WEBHOOK_EVENT_RECEIVED',
+    'BANK_DEPOSIT_WEBHOOK_EVENT_MATCHED',
+    'BANK_DEPOSIT_WEBHOOK_EVENT_AMBIGUOUS',
+    'BANK_DEPOSIT_WEBHOOK_EVENT_UNMATCHED',
+    'BANK_DEPOSIT_WEBHOOK_EVENT_CONFIRMED_MANUALLY',
+    'BANK_DEPOSIT_WEBHOOK_EVENT_EXPIRED',
+    'BANK_DEPOSIT_WEBHOOK_EVENT_CANCELLED',
+    'BANK_DEPOSIT_WEBHOOK_EVENT_REVERTED',
+    # Payout Types
+    'PayoutStatus',
+    'PayoutCreateParams',
+    'PayoutListParams',
+    'CommercePayout',
     # Alimtalk Types
     'ALIMTALK_WEBHOOK_EVENT_SEND_REQUESTED',
     'ALIMTALK_WEBHOOK_EVENT_SEND_SUCCESS',

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

@@ -16,6 +16,8 @@ from .cart import CartModule
 from .order_subscription_request import OrderSubscriptionRequestModule
 from .mall_setting import MallSettingModule
 from .webhook import WebhookModule
+from .deposit import DepositModule
+from .payout import PayoutModule
 from .faq import FaqModule
 from .notice import NoticeModule
 from .inquiry import InquiryModule
@@ -47,6 +49,8 @@ __all__ = [
     'OrderSubscriptionRequestModule',
     'MallSettingModule',
     'WebhookModule',
+    'DepositModule',
+    'PayoutModule',
     'FaqModule',
     'NoticeModule',
     'InquiryModule',

{bootpay_backend-2.9.0 → bootpay_backend-2.10.0}/bootpay_backend/commerce/modules/alimtalk_webhook.py

@@ -45,6 +45,7 @@ class AlimtalkWebhookModule:
           300 발송 접수(기본 미구독) / 301 전달 성공 / 302 전달 실패 / 303 예약 취소 /
           304 문자(LMS) 대체발송 전환 / 310 검수 승인 / 311 검수 반려 / 320 수신거부 등록(기본 미구독)
         events 를 비우면 기본 구독셋(301·302·303·304·310·311)이 적용된다.
+        retry_count: 건별 재시도 횟수 (1~25, 기본 10). 범위 밖이면 11304. 생략하면 기존 값을 유지한다 (26-09-30).
         :param params: 웹훅 설정
         :return: 저장된 웹훅 설정
         """

bootpay_backend-2.10.0/bootpay_backend/commerce/modules/deposit.py

@@ -0,0 +1,107 @@
+import uuid
+from typing import TYPE_CHECKING, Optional, Dict, Any
+from urllib.parse import quote
+
+if TYPE_CHECKING:
+    from ..commerce_resource import BootpayCommerceResource
+
+from ..types import (
+    CommerceDeposit,
+    DepositAccountsResponse,
+    DepositCreateParams,
+    DepositWebhookSecretResponse
+)
+
+
+class DepositModule:
+    """
+    뱅크알람 입금대기 모듈 (/v1/sdk/deposits)
+
+    판매자 폰의 입금 알림 중 금액·입금자명이 맞는 것을 주문에 연결하고 입금 웹훅으로 알린다.
+    인스턴스 role 과 무관하게 모든 요청은 supervisor 전용이다.
+    """
+
+    def __init__(self, bootpay: 'BootpayCommerceResource'):
+        self._bootpay = bootpay
+
+    def accounts(self) -> DepositAccountsResponse:
+        """
+        판매자 입금 계좌 목록
+        GET /v1/sdk/deposits/accounts
+        첫 계좌가 대표 계좌(primary: True)다.
+        :return: {'accounts': List[DepositAccount]}
+        """
+        return self._bootpay.get('sdk/deposits/accounts', headers=self._supervisor_headers())
+
+    def webhook_secret(self, idempotency_key: Optional[str] = None) -> DepositWebhookSecretResponse:
+        """
+        웹훅 서명 비밀값 발급
+        POST /v1/sdk/deposits/webhook_secret
+        ⚠️ 원문은 이 응답에서만 준다. 다시 부르면 바뀐다 (기존 웹훅 작업은 이전 비밀값으로 서명된다).
+        :param idempotency_key: 미지정시 자동 생성
+        :return: {'secret': str}
+        """
+        return self._bootpay.post(
+            'sdk/deposits/webhook_secret', {},
+            headers=self._supervisor_headers(idempotency_key)
+        )
+
+    def create(self, params: DepositCreateParams) -> CommerceDeposit:
+        """
+        입금대기 등록
+        POST /v1/sdk/deposits
+        같은 merchant_order_id 재호출은 기존 주문을 반환한다 (금액·입금자명·계좌가 다르면 18110).
+        webhook_url 을 주려면 webhook_secret() 으로 비밀값을 먼저 발급받아야 한다 (18131).
+        notify 는 유료 알림톡이며, 준비가 안 됐으면 주문을 만들지 않는다 (18133).
+        :param params: merchant_order_id · price · depositor 필수, idempotency_key 선택
+        :return: CommerceDeposit
+        """
+        payload = self._compact({k: v for k, v in params.items() if k != 'idempotency_key'})
+        if payload.get('notify') is not None:
+            payload['notify'] = self._compact(payload['notify'])
+        return self._bootpay.post(
+            'sdk/deposits', payload,
+            headers=self._supervisor_headers(params.get('idempotency_key'))
+        )
+
+    def detail(self, deposit_id: str) -> CommerceDeposit:
+        """
+        입금대기 조회
+        GET /v1/sdk/deposits/{id}
+        기한이 지났으면 조회 시점에 만료(expired)로 닫힌다.
+        :param deposit_id: 가맹점 주문번호 또는 부트페이 주문번호
+        :return: CommerceDeposit
+        """
+        if not deposit_id:
+            raise ValueError('deposit_id is required')
+        return self._bootpay.get(
+            f'sdk/deposits/{quote(deposit_id, safe="")}',
+            headers=self._supervisor_headers()
+        )
+
+    def cancel(self, deposit_id: str, idempotency_key: Optional[str] = None) -> CommerceDeposit:
+        """
+        입금대기 취소
+        DELETE /v1/sdk/deposits/{id}
+        기한이 지났으면 만료로 닫고, 이미 닫힌 주문은 그대로 반환한다. 입금 확인된 주문은 18108.
+        :param deposit_id: 가맹점 주문번호 또는 부트페이 주문번호
+        :param idempotency_key: 미지정시 자동 생성
+        :return: CommerceDeposit
+        """
+        if not deposit_id:
+            raise ValueError('deposit_id is required')
+        return self._bootpay.delete(
+            f'sdk/deposits/{quote(deposit_id, safe="")}',
+            headers=self._supervisor_headers(idempotency_key)
+        )
+
+    def _compact(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        """None 값을 제거한다 (False 는 남긴다)."""
+        return {k: v for k, v in payload.items() if v is not None}
+
+    def _supervisor_headers(self, idempotency_key: Optional[str] = None) -> Dict[str, str]:
+        """요청별 supervisor 헤더와 멱등키 (미지정시 매 호출마다 UUID 생성)."""
+        return {
+            'Idempotency-Key': idempotency_key or str(uuid.uuid4()),
+            'BOOTPAY-ROLE': 'supervisor'
+        }

bootpay_backend-2.10.0/bootpay_backend/commerce/modules/payout.py

@@ -0,0 +1,52 @@
+import uuid
+from typing import TYPE_CHECKING, Optional, Dict, Any, List
+from urllib.parse import quote
+
+if TYPE_CHECKING:
+    from ..commerce_resource import BootpayCommerceResource
+
+from ..types import CommercePayout, PayoutCreateParams, PayoutListParams
+
+
+class PayoutModule:
+    """입점사 지급 요청 모듈 (/v1/sdk/payouts)."""
+
+    def __init__(self, bootpay: 'BootpayCommerceResource'):
+        self._bootpay = bootpay
+
+    def create(self, params: PayoutCreateParams) -> CommercePayout:
+        """입점사와 지급액을 지정해 지급 원장에 등록한다."""
+        payload = self._compact({k: v for k, v in params.items() if k != 'idempotency_key'})
+        return self._bootpay.post(
+            'sdk/payouts', payload,
+            headers=self._supervisor_headers(params.get('idempotency_key'))
+        )
+
+    def detail(self, payout_id: str, idempotency_key: Optional[str] = None) -> CommercePayout:
+        """merchant_payout_id 또는 지급 항목 id로 한 건을 조회한다."""
+        if not payout_id:
+            raise ValueError('payout_id is required')
+        return self._bootpay.get(
+            f'sdk/payouts/{quote(payout_id, safe="")}',
+            headers=self._supervisor_headers(idempotency_key)
+        )
+
+    def list(self, params: Optional[PayoutListParams] = None) -> List[CommercePayout]:
+        """현재 프로젝트의 지급 항목 배열을 최근 생성 순으로 조회한다."""
+        request_params = params or {}
+        query = self._compact({k: v for k, v in request_params.items() if k != 'idempotency_key'})
+        return self._bootpay.get(
+            'sdk/payouts', params=query,
+            headers=self._supervisor_headers(request_params.get('idempotency_key'))
+        )
+
+    def _compact(self, payload: Dict[str, Any]) -> Dict[str, Any]:
+        """None 값을 제거한다 (0과 빈 문자열은 호출자가 보낸 값으로 유지한다)."""
+        return {k: v for k, v in payload.items() if v is not None}
+
+    def _supervisor_headers(self, idempotency_key: Optional[str] = None) -> Dict[str, str]:
+        """요청별 supervisor 헤더와 멱등키 (미지정시 매 호출마다 UUID 생성)."""
+        return {
+            'Idempotency-Key': idempotency_key or str(uuid.uuid4()),
+            'BOOTPAY-ROLE': 'supervisor'
+        }

{bootpay_backend-2.9.0 → bootpay_backend-2.10.0}/bootpay_backend/commerce/modules/product.py

@@ -116,7 +116,7 @@ class ProductModule:
         :return: CommerceProduct
         """
         payload = self._compact(product)
-        headers = self._manager_headers(idempotency_key)
+        headers = self._write_headers(idempotency_key)
 
         if not image_paths:
             return self._bootpay.post('products', payload, headers=headers)
@@ -173,7 +173,7 @@ class ProductModule:
         return self._bootpay.put(
             f'products/{product["product_id"]}',
             self._compact(product),
-            headers=self._manager_headers(idempotency_key)
+            headers=self._write_headers(idempotency_key)
         )
 
     def status(self, params: ProductStatusParams):
@@ -192,7 +192,7 @@ class ProductModule:
         return self._bootpay.put(
             f'products/{product_id}/status',
             self._compact(params),
-            headers=self._manager_headers(idempotency_key)
+            headers=self._write_headers(idempotency_key)
         )
 
     def delete(self, product_id: str, idempotency_key: Optional[str] = None):
@@ -205,21 +205,22 @@ class ProductModule:
         """
         return self._bootpay.delete(
             f'products/{product_id}',
-            headers=self._manager_headers(idempotency_key)
+            headers=self._write_headers(idempotency_key)
         )
 
     def _compact(self, payload: Dict[str, Any]) -> Dict[str, Any]:
         """None 값을 제거한다."""
         return {k: v for k, v in dict(payload or {}).items() if v is not None}
 
-    def _manager_headers(self, idempotency_key: Optional[str] = None) -> Dict[str, str]:
+    def _write_headers(self, idempotency_key: Optional[str] = None) -> Dict[str, str]:
         """
         상품 쓰기(등록/수정/삭제/상태변경) 요청 헤더
-        서버가 manager scope 를 요구한다.
+        서버 스코프는 user:product_create/update/delete/status 뿐이라 BOOTPAY-ROLE 은 user 로 보낸다.
+        manager 로 보내면 manager:product_* 를 찾다 401 API_ROLE_NOT_SUPPORT(-50) 로 막힌다.
         """
         return {
             'Idempotency-Key': idempotency_key or str(uuid.uuid4()),
-            'BOOTPAY-ROLE': 'manager'
+            'BOOTPAY-ROLE': 'user'
         }
 
     def _mall_headers(self, user_jwt: Optional[str] = None, idempotency_key: Optional[str] = None) -> Dict[str, str]:

{bootpay_backend-2.9.0 → bootpay_backend-2.10.0}/bootpay_backend/commerce/types/__init__.py

@@ -1,5 +1,5 @@
 # Commerce API Types
-from typing import TypedDict, Optional, List, Any, Dict
+from typing import TypedDict, Optional, List, Any, Dict, Literal
 
 # Common Types
 class ListParams(TypedDict, total=False):
@@ -1688,6 +1688,8 @@ class AlimtalkWebhookUpdateParams(TypedDict, total=False):
     # 목록에 없는 값은 저장 시 조용히 버려진다. 비우면 기본 구독셋(301·302·303·304·310·311).
     events: List[int]
     enabled: bool
+    # 건별 재시도 횟수(1~25, 기본 10). 범위 밖이면 11304. 생략하면 기존 값을 유지한다(26-09-30)
+    retry_count: int
 
 
 class AlimtalkWebhookDeliveryListParams(TypedDict, total=False):
@@ -1695,3 +1697,136 @@ class AlimtalkWebhookDeliveryListParams(TypedDict, total=False):
     page: int
     # 서버 기본 20, 최대 100
     limit: int
+
+
+# Bank Deposit Types (/v1/sdk/deposits)
+BANK_DEPOSIT_WEBHOOK_EVENT_RECEIVED = 400
+BANK_DEPOSIT_WEBHOOK_EVENT_MATCHED = 401
+BANK_DEPOSIT_WEBHOOK_EVENT_AMBIGUOUS = 402
+BANK_DEPOSIT_WEBHOOK_EVENT_UNMATCHED = 403
+BANK_DEPOSIT_WEBHOOK_EVENT_CONFIRMED_MANUALLY = 404
+BANK_DEPOSIT_WEBHOOK_EVENT_EXPIRED = 405
+BANK_DEPOSIT_WEBHOOK_EVENT_CANCELLED = 406
+BANK_DEPOSIT_WEBHOOK_EVENT_REVERTED = 407
+
+
+class DepositAccount(TypedDict, total=False):
+    id: str
+    bank_name: str
+    account_no: str
+    holder: str
+    # 대표 계좌 여부 — 계좌 목록 응답에만 실린다
+    primary: bool
+
+
+class DepositAccountsResponse(TypedDict, total=False):
+    accounts: List[DepositAccount]
+
+
+class DepositWebhookSecretResponse(TypedDict, total=False):
+    # 원문은 발급 응답에서만 받는다. 다시 발급하면 바뀐다.
+    secret: str
+
+
+class DepositNotify(TypedDict, total=False):
+    deposit_guide: bool
+    deposit_paid: bool
+
+
+class DepositNotifyParams(DepositNotify, total=False):
+    # 하나라도 True 면 buyer_phone 필수(18134), link 는 https · 500자 이하(18135)
+    link: str
+
+
+class _DepositCreateRequired(TypedDict):
+    merchant_order_id: str
+    price: float
+    depositor: str
+
+
+class DepositCreateParams(_DepositCreateRequired, total=False):
+    order_name: str
+    memo: str
+    # 미지정시 입금자명
+    buyer_name: str
+    buyer_phone: str
+    # 입금 안내·확인 메일 (무료). 잘못된 형식은 18136
+    buyer_email: str
+    # accounts() 의 id — 미지정시 대표 계좌
+    account_id: str
+    # 먼저 webhook_secret() 으로 서명 비밀값을 발급받아야 한다 (18131)
+    webhook_url: str
+    notify: DepositNotifyParams
+    idempotency_key: str
+
+
+class DepositNotice(TypedDict, total=False):
+    # 주문에 연결된 입금 알림 — 웹훅 본문에만 실린다
+    key: str
+    bank_name: str
+    account_tail: str
+    depositor: str
+    amount: float
+    received_at: Optional[str]
+
+
+class CommerceDeposit(TypedDict, total=False):
+    merchant_order_id: str
+    order_number: str
+    order_name: str
+    amount: float
+    status: Literal['awaiting', 'paid', 'expired', 'cancelled']
+    buyer_name: str
+    depositor: str
+    account: Optional[DepositAccount]
+    deadline: Optional[str]
+    deadline_label: Optional[str]
+    paid_at: Optional[str]
+    notify: Optional[DepositNotify]
+    deposit: Optional[DepositNotice]
+
+
+# Payout Types (/v1/sdk/payouts)
+PayoutStatus = Literal[
+    'ready', 'held', 'sending', 'requested', 'processing',
+    'succeeded', 'failed', 'cancelled', 'unknown', 'void'
+]
+
+
+class _PayoutCreateRequired(TypedDict):
+    sub_seller_id: str
+    amount: int
+    merchant_payout_id: str
+
+
+class PayoutCreateParams(_PayoutCreateRequired, total=False):
+    order_number: str
+    # 지급 예정일 YYYY-MM-DD (미지정시 서버 기준 오늘)
+    payout_date: str
+    idempotency_key: str
+
+
+PayoutListParams = TypedDict('PayoutListParams', {
+    'status': PayoutStatus,
+    'sub_seller_id': str,
+    # 지급 예정일 범위 YYYY-MM-DD (포함)
+    'from': str,
+    'to': str,
+    'page': int,
+    'limit': int,
+    'idempotency_key': str,
+}, total=False)
+
+
+class CommercePayout(TypedDict, total=False):
+    id: str
+    merchant_payout_id: str
+    sub_seller_id: str
+    amount: int
+    status: PayoutStatus
+    payout_date: str
+    order_number: Optional[str]
+    last_code: Optional[str]
+    last_message: Optional[str]
+    created_at: str
+    updated_at: str

{bootpay_backend-2.9.0 → bootpay_backend-2.10.0}/bootpay_backend/rest_client.py

@@ -11,7 +11,7 @@ class BootpayBackend:
         'production': 'https://api.bootpay.co.kr/v2'
     }
     API_VERSION = '5.1.0'
-    SDK_VERSION = '2.9.0'
+    SDK_VERSION = '2.10.0'
 
     def __init__(self, application_id=None, private_key=None, mode='production', client_key=None, secret_key=None):
         # application_id/private_key는 legacy 사용자를 위해 그대로 지원한다.