bootpay 3.1.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c451a531a23a1a127987e92afb1980687ebd31a484326da574520dc41e78da87
-  data.tar.gz: 0d0e6b71cd59143809355360bedd0f9f43da13a6a02cf9c9d8952edbecb6c7d0
+  metadata.gz: d7343a0e300b71e005a0493321465245bf11217ff32318c16e21be314e242135
+  data.tar.gz: 174b93f4bbccfc80cafd7a080194aec18b57db7ca29462999c1e29e5e36d4b09
 SHA512:
-  metadata.gz: 0ff9f2a74b66f0644633b605edff8e440ea29546cffba5cf7432597ea5b6ebbf8172cdc1598989b64d48c3bfd5091cbe9cec4f048965ccd032e93328faf5a4f6
-  data.tar.gz: 9ef546f66306f41e58e8fcaffc5ac1595eab60140056a1552d8a0f7b78ecd27c6c7843803fb1015149d4b86ac98a22d3350be6e1146eccd42514cedf4a146c41
+  metadata.gz: aac4dd10f479d96ab72b9acb4f3ad05941ea26258a1f63e89f603a996d2b849183908b2ad9a55fb992db948ba9247effa0be2172c5881aa1a155cbefcc6e5536
+  data.tar.gz: dd71f98130bb7548394532df02f42a61f18466664242bdeec701e67f61232fb547abac8634dd1f48a88387d8ffa77a8b33c14d8690809af89bf71c8a809490bb

data/CHANGELOG.md

@@ -1,3 +1,23 @@
+### 3.2.0
+
+- 뱅크알람 입금대기 API 5종 추가 — `deposit_accounts` · `deposit_webhook_secret` · `deposit_create` ·
+  `deposit_detail` · `deposit_cancel` (`/v1/sdk/deposits`). 가맹점 서버가 입금 전 주문을 등록하면 판매자 폰의
+  입금 알림 중 금액·입금자명이 맞는 것을 뱅크알람이 연결해 입금 웹훅으로 알린다.
+  같은 `merchant_order_id` 로 금액·입금자명·계좌가 같은 재호출은 기존 주문을 돌려주고, 하나라도 다르면 `18110`.
+  `deposit_webhook_secret` 은 부를 때마다 비밀값이 바뀌고 원문은 그 응답에서만 온다.
+  `deposit_id` 는 가맹점 주문번호 또는 부트페이 주문번호이며 경로 인코딩한다. 웹훅 이벤트 상수
+  `BootpayStore::Concern::Deposit::BANK_DEPOSIT_WEBHOOK_EVENT_*`(400~407).
+- 입점사 지급 요청 API 3종 추가 — `payout_create` · `payout_detail` · `payouts` (`/v1/sdk/payouts`).
+  가맹점 지정 금액(`manual`) 정산 쇼핑몰이 입점사·지급액을 정해 지급 원장에 등록하고, 송금은 부트페이 배치가 한다.
+  같은 `merchant_payout_id` 재호출은 처음 항목을 돌려준다. `payouts` 의 응답 `data` 는 항목 배열이다(전체 개수 없음).
+- 위 8개는 전부 supervisor scope 라 `Bootpay-Role: supervisor` 로 보내며, `idempotency_key` 를 안 주면 UUID 를 생성한다.
+  nil 인자는 본문·쿼리에서 뺀다(`deposit_create` 의 `notify` 안쪽 포함, `false` 는 유지).
+- `product_create` · `product_update` · `product_delete` · `product_status` 의 `Bootpay-Role` 을 `manager` → `user` 로.
+  서버 스코프가 `user:product_*` 뿐이라 manager 로 보내면 401 `API_ROLE_NOT_SUPPORT(-50)` 였다.
+- `alimtalk_webhook_update` 에 `retry_count` 인자 추가(선택). 웹훅 전달 실패 시 건별 재시도 횟수를
+  `1`~`25` 사이로 정한다(기본 `10`). 범위 밖 값을 주면 `11304` 로 거부된다. 생략하면 기존에 저장된
+  값을 그대로 유지하므로 기존 호출은 변화 없이 동작한다.
+
 ### 3.1.0
 
 - 커머스 게시판 API 28종 SDK 메서드 추가 — FAQ · 공지사항 · 1:1 문의 · 상품문의(Q&A) · 상품평.

data/lib/bootpay_store/concern/alimtalk_webhook.rb

@@ -31,15 +31,18 @@ module BootpayStore::Concern::AlimtalkWebhook
     #   300 발송 접수(기본 미구독) / 301 전달 성공 / 302 전달 실패 / 303 예약 취소 /
     #   304 문자(LMS) 대체발송 전환 / 310 검수 승인 / 311 검수 반려 / 320 수신거부 등록(기본 미구독)
     # events 를 비우면 기본 구독셋(301·302·303·304·310·311)이 적용된다.
-    def alimtalk_webhook_update(url: nil, events: nil, enabled: nil)
+    # retry_count: 건별 재시도 횟수(1~25, 기본 10). 범위 밖이면 11304. 생략하면 기존 값을 유지한다.
+    #   @date: 26-09-30
+    def alimtalk_webhook_update(url: nil, events: nil, enabled: nil, retry_count: nil)
       request(
         uri:     'alimtalk/webhook',
         method:  :put,
         headers: { 'Bootpay-Role' => 'user' },
         payload: {
-          url:     url,
-          events:  events,
-          enabled: enabled
+          url:         url,
+          events:      events,
+          enabled:     enabled,
+          retry_count: retry_count
         }.compact
       )
     end

data/lib/bootpay_store/concern/deposit.rb

@@ -0,0 +1,115 @@
+module BootpayStore::Concern::Deposit
+  extend ActiveSupport::Concern
+
+  # 뱅크알람 입금대기 웹훅 이벤트 (입금 웹훅 본문의 event)
+  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 # 입금 확인을 되돌려 다시 입금대기로 바꿨다
+
+  included do
+    # 판매자 입금 계좌 목록 (GET /v1/sdk/deposits/accounts) — supervisor 전용
+    # @comment_by Claude
+    # @date: 26-11-12
+    # 첫 계좌가 대표 계좌(primary: true)다.
+    def deposit_accounts(idempotency_key: nil)
+      request(
+        uri:     'sdk/deposits/accounts',
+        method:  :get,
+        headers: {
+          'Idempotency-Key' => idempotency_key.presence || SecureRandom.uuid,
+          'Bootpay-Role'    => 'supervisor'
+        }
+      )
+    end
+
+    # 입금 웹훅 서명 비밀값 발급 (POST /v1/sdk/deposits/webhook_secret) — supervisor 전용
+    # @comment_by Claude
+    # @date: 26-11-12
+    # ⚠️ 원문은 이 응답에서만 오고, 부를 때마다 바뀐다.
+    # 웹훅은 X-Bootpay-Signature: sha256=HMAC_SHA256(secret, "{X-Bootpay-Timestamp}.{raw_body}") 로 서명된다.
+    def deposit_webhook_secret(idempotency_key: nil)
+      request(
+        uri:     'sdk/deposits/webhook_secret',
+        method:  :post,
+        headers: {
+          'Idempotency-Key' => idempotency_key.presence || SecureRandom.uuid,
+          'Bootpay-Role'    => 'supervisor'
+        }
+      )
+    end
+
+    # 입금대기 등록 (POST /v1/sdk/deposits) — supervisor 전용
+    # @comment_by Claude
+    # @date: 26-11-12
+    # 같은 merchant_order_id 로 금액·입금자명·계좌가 같은 재호출은 기존 주문을 돌려주고, 하나라도 다르면 18110.
+    # webhook_url 을 주려면 deposit_webhook_secret 으로 비밀값을 먼저 발급받아야 한다(18131).
+    # notify(구매자 알림톡, 유료): { deposit_guide:, deposit_paid:, link: } — buyer_phone 필수(18134), link 는 https(18135).
+    def deposit_create(merchant_order_id:, price:, depositor:, order_name: nil, memo: nil, buyer_name: nil,
+                       buyer_phone: nil, buyer_email: nil, account_id: nil, webhook_url: nil, notify: nil,
+                       idempotency_key: nil)
+      request(
+        uri:     'sdk/deposits',
+        method:  :post,
+        headers: {
+          'Idempotency-Key' => idempotency_key.presence || SecureRandom.uuid,
+          'Bootpay-Role'    => 'supervisor'
+        },
+        payload: {
+                   merchant_order_id: merchant_order_id,
+                   price:             price,
+                   depositor:         depositor,
+                   order_name:        order_name,
+                   memo:              memo,
+                   buyer_name:        buyer_name,
+                   buyer_phone:       buyer_phone,
+                   buyer_email:       buyer_email,
+                   account_id:        account_id,
+                   webhook_url:       webhook_url,
+                   notify:            notify.is_a?(Hash) ? notify.compact : notify
+                 }.compact
+      )
+    end
+
+    # 입금대기 조회 (GET /v1/sdk/deposits/:id) — supervisor 전용
+    # @comment_by Claude
+    # @date: 26-11-12
+    # deposit_id 는 가맹점 주문번호(merchant_order_id) 또는 부트페이 주문번호. 자유 문자열이라 경로 인코딩한다.
+    def deposit_detail(deposit_id:, idempotency_key: nil)
+      request(
+        uri:     "sdk/deposits/#{deposit_path_segment(deposit_id)}",
+        method:  :get,
+        headers: {
+          'Idempotency-Key' => idempotency_key.presence || SecureRandom.uuid,
+          'Bootpay-Role'    => 'supervisor'
+        }
+      )
+    end
+
+    # 입금대기 취소 (DELETE /v1/sdk/deposits/:id) — supervisor 전용
+    # @comment_by Claude
+    # @date: 26-11-12
+    # 이미 닫힌 주문은 그대로 돌려준다. 입금 확인된 주문은 18108.
+    def deposit_cancel(deposit_id:, idempotency_key: nil)
+      request(
+        uri:     "sdk/deposits/#{deposit_path_segment(deposit_id)}",
+        method:  :delete,
+        headers: {
+          'Idempotency-Key' => idempotency_key.presence || SecureRandom.uuid,
+          'Bootpay-Role'    => 'supervisor'
+        }
+      )
+    end
+
+    private
+
+    # 경로 세그먼트 인코딩 — 공백은 %20, / 는 %2F (다른 SDK 와 같은 결과)
+    def deposit_path_segment(value)
+      URI.encode_www_form_component(value.to_s).gsub('+', '%20')
+    end
+  end
+end

data/lib/bootpay_store/concern/payout.rb

@@ -0,0 +1,69 @@
+module BootpayStore::Concern::Payout
+  extend ActiveSupport::Concern
+
+  included do
+    # 입점사 지급 요청 등록 (POST /v1/sdk/payouts) — supervisor 전용
+    # @comment_by Claude
+    # @date: 26-11-12
+    # 가맹점 지정 금액(manual) 정산 쇼핑몰이 입점사와 지급액을 정해 지급 원장에 등록한다. 실제 송금은 부트페이 배치가 한다.
+    # 같은 merchant_payout_id 재호출은 처음 만든 항목을 돌려준다(금액·입점사·지급일은 바꿀 수 없다).
+    # payout_date: 'YYYY-MM-DD' (미지정시 오늘). 정산 방식이 manual 이 아니면 18360, PG 미등록 입점사는 18378.
+    def payout_create(sub_seller_id:, amount:, merchant_payout_id:, order_number: nil, payout_date: nil,
+                      idempotency_key: nil)
+      request(
+        uri:     'sdk/payouts',
+        method:  :post,
+        headers: {
+          'Idempotency-Key' => idempotency_key.presence || SecureRandom.uuid,
+          'Bootpay-Role'    => 'supervisor'
+        },
+        payload: {
+                   sub_seller_id:      sub_seller_id,
+                   amount:             amount,
+                   merchant_payout_id: merchant_payout_id,
+                   order_number:       order_number,
+                   payout_date:        payout_date
+                 }.compact
+      )
+    end
+
+    # 입점사 지급 항목 조회 (GET /v1/sdk/payouts/:id) — supervisor 전용
+    # @comment_by Claude
+    # @date: 26-11-12
+    # payout_id 는 merchant_payout_id 또는 지급 항목 id. 없으면 404 PAYOUT_RESULT_INVALID(18366).
+    def payout_detail(payout_id:, idempotency_key: nil)
+      request(
+        uri:     "sdk/payouts/#{URI.encode_www_form_component(payout_id.to_s).gsub('+', '%20')}",
+        method:  :get,
+        headers: {
+          'Idempotency-Key' => idempotency_key.presence || SecureRandom.uuid,
+          'Bootpay-Role'    => 'supervisor'
+        }
+      )
+    end
+
+    # 입점사 지급 목록 (GET /v1/sdk/payouts) — supervisor 전용
+    # @comment_by Claude
+    # @date: 26-11-12
+    # 최근 생성 순. 응답 data 는 항목 배열이다(전체 개수 없음 — 받은 수가 limit 보다 적으면 마지막 페이지).
+    # status: ready · held · sending · requested · processing · succeeded · failed · cancelled · unknown · void
+    def payouts(status: nil, sub_seller_id: nil, from: nil, to: nil, page: nil, limit: nil, idempotency_key: nil)
+      request(
+        uri:     'sdk/payouts',
+        method:  :get,
+        headers: {
+          'Idempotency-Key' => idempotency_key.presence || SecureRandom.uuid,
+          'Bootpay-Role'    => 'supervisor'
+        },
+        params:  {
+                   status:        status,
+                   sub_seller_id: sub_seller_id,
+                   from:          from,
+                   to:            to,
+                   page:          page,
+                   limit:         limit
+                 }.compact
+      )
+    end
+  end
+end

data/lib/bootpay_store/concern/product.rb

@@ -67,6 +67,8 @@ module BootpayStore::Concern::Product
     # @date: 26-08-14
     # images 가 있으면 multipart, 없으면 JSON 으로 보낸다.
     # 컨트롤러가 읽는 필드는 _product_params 참조 — 여기 명시하지 않은 값도 attrs 로 그대로 전달된다.
+    # @date: 26-11-02 Bootpay-Role manager → user. 서버 스코프는 user:product_create/update/delete/status 뿐이라
+    #   manager 로 보내면 manager:product_* 를 찾다 401 API_ROLE_NOT_SUPPORT(-50) 로 막혔다 (수정·삭제·상태변경도 같다)
     def product_create(name:, display_price: nil, desc: nil, content: nil, category_id: nil,
                        type: nil, stock: nil, status_sale: nil, status_display: nil,
                        use_subscription: nil, subscription_setting_id: nil,
@@ -88,7 +90,7 @@ module BootpayStore::Concern::Product
 
       headers = {
         'Idempotency-Key' => idempotency_key.presence || SecureRandom.uuid,
-        'Bootpay-Role'    => 'manager'
+        'Bootpay-Role'    => 'user'
       }
 
       if images.present?
@@ -104,6 +106,7 @@ module BootpayStore::Concern::Product
     # @comment_by Claude (alfred)
     # @date: 26-08-14
     # 바뀐 값만 보내면 된다. category_id 는 키 존재 여부로 '해제 의사'를 판별하므로 주의.
+    # @date: 26-11-02 Bootpay-Role manager → user (product_create 주석 참고)
     def product_update(product_id:, name: nil, display_price: nil, desc: nil, content: nil,
                        category_id: nil, stock: nil, status_sale: nil, status_display: nil,
                        save_by: nil, idempotency_key: nil, **attrs)
@@ -112,7 +115,7 @@ module BootpayStore::Concern::Product
         method:  :put,
         headers: {
           'Idempotency-Key' => idempotency_key.presence || SecureRandom.uuid,
-          'Bootpay-Role'    => 'manager'
+          'Bootpay-Role'    => 'user'
         },
         payload: {
                    name:           name,
@@ -131,13 +134,14 @@ module BootpayStore::Concern::Product
     # 상품을 삭제한다 (DELETE /v1/products/:id)
     # @comment_by Claude (alfred)
     # @date: 26-08-14
+    # @date: 26-11-02 Bootpay-Role manager → user (product_create 주석 참고)
     def product_delete(product_id:, idempotency_key: nil)
       request(
         uri:     "products/#{product_id}",
         method:  :delete,
         headers: {
           'Idempotency-Key' => idempotency_key.presence || SecureRandom.uuid,
-          'Bootpay-Role'    => 'manager'
+          'Bootpay-Role'    => 'user'
         }
       )
     end
@@ -146,6 +150,7 @@ module BootpayStore::Concern::Product
     # @comment_by Claude (alfred)
     # @date: 26-08-14
     # 컨트롤러 _status_params 기준. 재고(stock)는 여기가 아니라 product_update 로 바꾼다.
+    # @date: 26-11-02 Bootpay-Role manager → user (product_create 주석 참고)
     def product_status(product_id:, status_sale: nil, status_display: nil, status_frozen: nil,
                        status_review: nil, use_display_period: nil, display_start_at: nil, display_end_at: nil,
                        use_sale_period: nil, sale_start_at: nil, sale_end_at: nil,
@@ -155,7 +160,7 @@ module BootpayStore::Concern::Product
         method:  :put,
         headers: {
           'Idempotency-Key' => idempotency_key.presence || SecureRandom.uuid,
-          'Bootpay-Role'    => 'manager'
+          'Bootpay-Role'    => 'user'
         },
         payload: {
                    status_sale:        status_sale,

data/lib/bootpay_store/concern.rb

@@ -7,6 +7,7 @@ module BootpayStore
     require_relative 'concern/alimtalk_sender'
     require_relative 'concern/alimtalk_template'
     require_relative 'concern/alimtalk_webhook'
+    require_relative 'concern/deposit'
     require_relative 'concern/faq'
     require_relative 'concern/inquiry'
     require_relative 'concern/invoice'
@@ -15,6 +16,7 @@ module BootpayStore
     require_relative 'concern/order'
     require_relative 'concern/order_subscription'
     require_relative 'concern/payment'
+    require_relative 'concern/payout'
     require_relative 'concern/product'
     require_relative 'concern/product_qna'
     require_relative 'concern/product_review'
@@ -33,6 +35,7 @@ module BootpayStore
     include AlimtalkSender
     include AlimtalkTemplate
     include AlimtalkWebhook
+    include Deposit
     include Faq
     include Inquiry
     include Invoice
@@ -41,6 +44,7 @@ module BootpayStore
     include Order
     include OrderSubscription
     include Payment
+    include Payout
     include Product
     include ProductQna
     include ProductReview

data/lib/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Bootpay
-  VERSION = "3.1.0"
+  VERSION = "3.2.0"
 
   # 구 이름(`bootpay-backend-ruby`) 시절 gemspec·코드가 참조하던 상수.
   # 값이 갈리지 않도록 VERSION 을 그대로 가리킨다.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bootpay
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 3.2.0
 platform: ruby
 authors:
 - gosomi
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-30 00:00:00.000000000 Z
+date: 2026-11-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -106,6 +106,7 @@ files:
 - lib/bootpay_store/concern/alimtalk_sender.rb
 - lib/bootpay_store/concern/alimtalk_template.rb
 - lib/bootpay_store/concern/alimtalk_webhook.rb
+- lib/bootpay_store/concern/deposit.rb
 - lib/bootpay_store/concern/faq.rb
 - lib/bootpay_store/concern/inquiry.rb
 - lib/bootpay_store/concern/invoice.rb
@@ -114,6 +115,7 @@ files:
 - lib/bootpay_store/concern/order.rb
 - lib/bootpay_store/concern/order_subscription.rb
 - lib/bootpay_store/concern/payment.rb
+- lib/bootpay_store/concern/payout.rb
 - lib/bootpay_store/concern/product.rb
 - lib/bootpay_store/concern/product_qna.rb
 - lib/bootpay_store/concern/product_review.rb