bootpay-backend-ruby 3.0.0.pre.alpha.3 → 3.0.0.pre.alpha.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3c39a84c5f8ae3dc4bdde7e2b7bf99a3b570ea66f5d2368442be24e888b148c7
-  data.tar.gz: 6d29b4e6920b8a995b2bc9cd06484eee06770b91daeefa263f2c90ea72c19331
+  metadata.gz: 7dabe4bba771d7710f61b2f20a843e1e452028a723962e04de6dcdb694e83342
+  data.tar.gz: d19e63191fcfae0c2bad8ffc4c0f7835365a8c87896a90266fa5baae795e245c
 SHA512:
-  metadata.gz: 7df5bdd01f1682769cb2fb5b6a90da35ba87cc289e2e9539104f671f474963dd8451b9916a8f5016b5b46bb44017b992cf733a2ae82ae8d8b3461d9c1b3f52d6
-  data.tar.gz: f9b0fcf40002c3c579b73da89bdca1829f861ad4c661f171bdc37392f208cec4f5005d0b3ffffff187a42a127d1c7a77b393e9b58aa33310f6ed36bf5f4e44da
+  metadata.gz: 7bf6c3328a7a3097b1acee7dfc8484f782fd5d96a79cc9d04cf3c69f005a73ecc521b39d09b4c5f8d5f11568e054b978882c5ffdf4edae4d6cbb8157184c4ee7
+  data.tar.gz: b2e6b6a95fcb6d8dda0c3fa317b21bbf29565916b7839a8d8ec272af1398972d251b536f53081ad659164f949106e18597bcc782146fcd5711a2beadd9a3761a

data/.gitignore

@@ -16,4 +16,8 @@ Gemfile.lock
 /spec/bootpay/card_billing/request_rest_billing_key_spec.rb
 /spec/bootpay/__stage_test_unit_spec.rb
 /spec/bootpay/__development_test_unit_spec.rb
-.DS_Store
+/spec/bootpay/
+.DS_Store
+# 실 API 키가 들어가는 로컬 설정 — 커밋 금지 (26-08-24 추가)
+.env
+.env.local

data/CHANGELOG.md

@@ -1,3 +1,13 @@
+### 3.0.0-alpha.4
+- 알림톡 v1 API 35종 추가 — 발송·발송내역·공식 카탈로그·자체 템플릿·발신프로필·수신거부·알림톡 웹훅 7개 모듈
+  - 알림톡 요청은 `Idempotency-Key` 를 싣지 않는다 (멱등은 발송의 `ref_id` 로만 성립)
+  - `Bootpay-Role` 은 항상 `user` (스코프 키가 전부 `user:alimtalk_*`)
+  - ⚠️ 샌드박스가 없다 — 발송·OTP·발신프로필 등록·템플릿 등록/검수는 실제로 나가고 과금된다
+- 별건 현금영수증의 `pg` 를 선택 파라미터로 (미지정 시 가맹점 기본 PG 로 발행)
+- mall_setting · order_subscription · supervisor · user · user_group · product · invoice ·
+  payment · order · store · webhook · storage 모듈 확충
+- alpha.3(2025-03-27) 이후 63커밋 누적분을 릴리스한다
+
 ### 3.0.0
 - store api 추가
 - 내부용 storage api 추가

data/Gemfile

@@ -7,4 +7,4 @@ gemspec
 
 gem "rake", "~> 13.0"
 
-gem "rspec", "~> 3.0"
+gem "rspec", "~> 3.0"

data/bootpay-backend-ruby.gemspec

@@ -13,8 +13,15 @@ Gem::Specification.new do |spec|
   spec.license     = "MIT"
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  # ⚠️ 루트의 tests_*.rb / *.gem 도 제외한다 — 종전 규칙은 test/·spec/·features/ **디렉터리**만
+  #    걸러서 루트에 있던 tests_basic_auth_product_info.rb 가 gem 에 실려 나갔다.
+  #    그 파일에는 dev Commerce secret_key 가 하드코딩돼 있었다 (26-09-02).
   spec.files         = Dir.chdir(File.expand_path(__dir__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{\A(?:test|spec|features)/}) ||
+        f.match(%r{\A(?:tests?_.*\.rb|.*\.gem)\z}) ||
+        f.match(%r{\A\.env})
+    end
   end
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
@@ -23,6 +30,7 @@ Gem::Specification.new do |spec|
   # Uncomment to register a new dependency of your gem
   spec.add_dependency "activesupport"
   spec.add_dependency "http"
+  spec.add_dependency "addressable"
 
   # For more information and examples about making a new gem, checkout our
   # guide at: https://bundler.io/guides/creating_gem.html

data/lib/bootpay/bootpay-rest-client.rb

@@ -10,6 +10,8 @@ module Bootpay
   class RestClient
     include Concern
 
+    attr_accessor :application_id, :private_key, :client_key, :secret_key, :use_client_key, :mode, :token, :api_version
+
     API =
       {
         development: 'https://dev-api.bootpay.co.kr/v2',
@@ -17,11 +19,14 @@ module Bootpay
         production:  'https://api.bootpay.co.kr/v2'
       }
 
-    SDK_VERSION = '5.0.0'
+    SDK_VERSION = '5.3.0'
 
-    def initialize(application_id:, private_key:, mode: 'production')
+    def initialize(application_id: nil, private_key: nil, client_key: nil, secret_key: nil, mode: 'production')
       @application_id = application_id
       @private_key    = private_key
+      @client_key     = client_key
+      @secret_key     = secret_key
+      @use_client_key = client_key.present?
       @mode           = mode.presence || 'production'
       @token          = nil
       @api_version    = SDK_VERSION

data/lib/bootpay/concern/authenticate.rb

@@ -16,24 +16,26 @@ module Bootpay::Concern::Authenticate
     # Comment by Gosomi
     # Date: 2022-11-02
     def request_authentication(pg:, method:, username:, identity_no:, carrier:, phone:, site_url:,
-                               authenticate_type: 'sms', order_name: '', authentication_id: '', extra: {}, user: {})
+                               authenticate_type: 'sms', order_name: '', authentication_id: '', extra: {}, user: {}, client_ip: nil)
       request(
-        method:  :post,
-        uri:     'request/authentication',
-        payload: {
-          pg:                pg,
-          method:            method,
-          username:          username,
-          identity_no:       identity_no,
-          carrier:           carrier,
-          phone:             phone,
-          site_url:          site_url,
-          authenticate_type: authenticate_type,
-          order_name:        order_name,
-          authentication_id: authentication_id,
-          extra:             extra,
-          user:              user
-        }
+        method: :post,
+        uri:    'request/authentication',
+        payload:
+                {
+                  pg:                pg,
+                  method:            method,
+                  username:          username,
+                  identity_no:       identity_no,
+                  carrier:           carrier,
+                  phone:             phone,
+                  site_url:          site_url,
+                  authenticate_type: authenticate_type,
+                  order_name:        order_name,
+                  authentication_id: authentication_id,
+                  extra:             extra,
+                  user:              user,
+                  client_ip:         client_ip
+                }.compact
       )
     end
 

data/lib/bootpay/concern/cash_receipt.rb

@@ -5,7 +5,7 @@ module Bootpay::Concern::CashReceipt
     # 현금 영수증 발행 처리 하기
     # Comment by Gosomi
     # Date: 2021-12-15
-    def request_cash_receipt(pg:, order_name:, identity_no:, purchased_at:, cash_receipt_type:, price:, tax_free:, user: {},
+    def request_cash_receipt(pg: nil, order_name:, identity_no:, purchased_at:, cash_receipt_type:, price:, tax_free:, user: {},
                              metadata: {}, extra: {}, order_id:)
       request(
         method:  :post,

data/lib/bootpay/concern/payment.rb

@@ -59,7 +59,7 @@ module Bootpay::Concern::Payment
     # REST API로 결제 요청하기
     # Comment by Gosomi
     # Date: 2023-03-28
-    def request_payment(platform_application_id:, pg:, method: nil, price:, tax_free: 0, order_name:, order_id:, user_token: nil, uuid: nil, sk: nil,
+    def request_payment(platform_application_id: nil, pg:, method: nil, price:, tax_free: 0, order_name:, order_id:, user_token: nil, uuid: nil, sk: nil,
                         ti: 0, tk: nil, items: [], extra: {}, user: {}, agent: nil, commission_keys: nil, wallet_id: nil, terms: [], widget_key: nil, widget_sandbox: false,
                         redirect_url: nil)
       rand_uuid = SecureRandom.uuid
@@ -79,6 +79,7 @@ module Bootpay::Concern::Payment
                commission_keys:         commission_keys,
                terms:                   terms,
                redirect_url:            redirect_url,
+               widget:                  widget_key.present? ? 1 : 0,
                widget_key:              widget_key,
                widget_sandbox:          widget_sandbox,
                uuid:                    uuid.presence || rand_uuid,

data/lib/bootpay/concern/rest.rb

@@ -10,7 +10,7 @@ module Bootpay::Concern::Rest
     def request(method: :post, uri:, payload: {}, headers: {}, params: nil)
       response = HTTP.headers(
         {
-          Authorization:       "Bearer #{@token}",
+          Authorization:       authotization_header,
           content_type:        'application/json',
           accept:              'application/json',
           bootpay_api_version: @api_version,
@@ -34,5 +34,23 @@ module Bootpay::Concern::Rest
         backtrace: e.backtrace.join("\n")
       )
     end
+
+    # Authorize Header
+    # Comment by GOSOMI
+    # @date: 2026-03-11
+    def authotization_header
+      if @use_client_key
+        "Basic #{basic_authentification}"
+      else
+        "Bearer #{@token}" if @token.present?
+      end
+    end
+
+    # basic_authentification
+    # Comment by GOSOMI
+    # @date: 2026-03-11
+    def basic_authentification
+      @token = Base64.strict_encode64("#{@client_key}:#{@secret_key}")
+    end
   end
 end

data/lib/bootpay/concern/sdk.rb

@@ -32,5 +32,21 @@ module Bootpay::Concern::Sdk
         }
       )
     end
+
+    # Validate Password Token
+    # Comment by GOSOMI
+    # @date: 2025-12-24
+    def validate_password_token(token:, user_token:)
+      request(
+        method:  :post,
+        uri:     'sdk/password-token',
+        headers: {
+          'Bootpay-User-Token': user_token
+        },
+        payload: {
+          token: token
+        }
+      )
+    end
   end
 end

data/lib/bootpay/concern/subscription.rb

@@ -12,39 +12,15 @@ module Bootpay::Concern::Subscription
       )
     end
 
-    # 빌링키로 결제 요청하기
-    # Comment by Gosomi
-    # Date: 2021-11-02
-    def request_subscribe_card_payment(billing_key:, order_name:, price:, tax_free: 0, card_quota: '00', feedback_url: nil, content_type: nil,
-                                       card_interest: nil, order_id:, items: [], user: {}, extra: {}, metadata: {})
-      request(
-        uri:     'subscribe/payment',
-        payload: {
-          billing_key:   billing_key,
-          metadata:      metadata,
-          order_name:    order_name,
-          price:         price,
-          tax_free:      tax_free,
-          card_quota:    card_quota,
-          card_interest: card_interest,
-          order_id:      order_id,
-          items:         items,
-          user:          user,
-          extra:         extra,
-          feedback_url:  feedback_url,
-          content_type:  content_type
-        }
-      )
-    end
-
     # 빌링키로 결제 요청하기
     # Comment by ehowlsla
     # Date: 2024-05-29
-    def request_subscribe_payment(billing_key:, order_name:, price:, tax_free: 0, card_quota: '00', feedback_url: nil, content_type: nil,
-                                       card_interest: nil, order_id:, items: [], user: {}, extra: {}, metadata: {})
+    def request_subscribe_payment(wallet_key: nil, billing_key: nil, order_name:, price:, tax_free: 0, card_quota: '00', feedback_url: nil, content_type: nil,
+                                  card_interest: nil, order_id:, items: [], user: {}, extra: {}, metadata: {})
       request(
         uri:     'subscribe/payment',
         payload: {
+          wallet_key:    wallet_key,
           billing_key:   billing_key,
           metadata:      metadata,
           order_name:    order_name,
@@ -62,7 +38,6 @@ module Bootpay::Concern::Subscription
       )
     end
 
-
     # 자동결제 예약
     # Comment by Gosomi
     # Date: 2022-04-21
@@ -181,6 +156,8 @@ module Bootpay::Concern::Subscription
       )
     end
 
+    alias_method :request_subscribe_card_payment, :request_subscribe_payment
+
     # ARS나 본인인증 이후 빌링키 발급
     # Comment by GOSOMI
     # @date: 2024-01-26
@@ -220,5 +197,15 @@ module Bootpay::Concern::Subscription
         uri:    "billing_key/#{billing_key}"
       )
     end
+
+    # 우선순위 빌링키 조회기능 추가
+    # Comment by GOSOMI
+    # @date: 2026-07-03
+    def lookup_sequential_billing_key(widget_key:, billing_key:, user_id:)
+      request(
+        method: :get,
+        uri:    "subscribe/sequential_billing_key/#{billing_key}?widget_key=#{widget_key}&user_id=#{user_id}"
+      )
+    end
   end
 end

data/lib/bootpay/concern/token.rb

@@ -16,5 +16,18 @@ module Bootpay::Concern::Token
       @token   = response.data[:access_token] if response.success?
       response
     end
+
+    # 둘다 겸하는 경우 우회함수
+    # Comment by GOSOMI
+    # @date: 2026-03-11
+    def basic_or_request_access_token
+      if @use_client_key
+        Object.new.tap do |o|
+          o.define_singleton_method(:success?) { true }
+        end
+      else
+        request_access_token
+      end
+    end
   end
 end

data/lib/bootpay/concern/wallet.rb

@@ -2,38 +2,17 @@ module Bootpay::Concern::Wallet
   extend ActiveSupport::Concern
 
   included do
-    # 설정된 wallet 기준으로 결제를 진행한다
-    def request_wallet_payment(user_id:, order_name:, price:, tax_free: 0, webhook_url: nil, content_type: nil, order_id:,
-                               items: [], user: {}, extra: {}, metadata: {}, sandbox: false)
-      request(
-        uri:     'wallet/payment',
-        payload: {
-          user_id:      user_id,
-          order_name:   order_name,
-          price:        price,
-          tax_free:     tax_free,
-          webhook_url:  webhook_url,
-          content_type: content_type,
-          order_id:     order_id,
-          items:        items,
-          user:         user,
-          extra:        extra,
-          metadata:     metadata,
-          sandbox:      sandbox
-        }
-      )
-    end
-
     # 등록된 회원의 지갑 정보를 가져온다
     # Comment by GOSOMI
     # @date: 2025-02-13
-    def user_wallets(user_id:, sandbox:)
+    def user_wallets(user_id:, widget_key: nil, sandbox: false)
       request(
         uri:    'wallet',
         method: :get,
         params: {
-          user_id: user_id,
-          sandbox: sandbox
+          user_id:    user_id,
+          widget_key: widget_key,
+          sandbox:    sandbox
         }
       )
     end

data/lib/bootpay_storage/concern/csv.rb

@@ -0,0 +1,18 @@
+module BootpayStorage::Concern::Csv
+  extend ActiveSupport::Concern
+
+  included do
+
+
+    # csv 파일 업로드 - 마이그레이션 할 때 사용
+    # Comment by ehowlsla
+    # Date: 2025-07-17
+    def csv_file_upload(files:)
+      csv_upload(
+        uri:   'csvs',
+        files: files
+      )
+    end
+
+  end
+end

data/lib/bootpay_storage/concern/image.rb

@@ -14,5 +14,17 @@ module BootpayStorage::Concern::Image
       )
     end
 
+    # 업로드한 이미지를 URL 로 삭제한다.
+    # 업로드 응답이 URL 만 돌려주므로(내부 식별자 미노출) 삭제도 URL 을 키로 받는다.
+    # Comment by Claude (alfred)
+    # @date: 2026-07-28
+    def image_destroy(url:)
+      request(
+        method:  :delete,
+        uri:     'images/by_url',
+        payload: { url: url }
+      )
+    end
+
   end
 end

data/lib/bootpay_storage/concern/rest.rb

@@ -80,6 +80,51 @@ module BootpayStorage::Concern::Rest
       )
     end
 
+    # csv Multipart 파일 전송 Method
+    # Comment by ehowlsla
+    # Date: 2025-07-17
+    def csv_upload(uri:, files:, headers: {}, params: nil)
+      # 이미지 데이터를 배열로 받음
+      files = files.each_with_index.map do |data, index|
+        filename = "csv_#{Time.now.to_i}_#{index}.csv"
+        HTTP::FormData::File.new(data, filename: filename)
+      end
+
+      # HTTP 요청
+      response = HTTP.headers(
+        {
+          Authorization:       "Bearer #{@token}",
+          accept:              'application/json',
+          bootpay_api_version: @api_version,
+          bootpay_sdk_version: Bootpay::V2_VERSION,
+          bootpay_sdk_type:    '300'
+        }.merge!(headers).compact
+      ).post(
+        [BootpayStorage::RestClient::API[@mode.to_sym], uri].join('/'),
+        form: { images: files },
+        params: params
+      )
+
+      # JSON 파싱 시도
+      parsed_response = begin
+                          JSON.parse(response.body.to_s, symbolize_names: true)
+                        rescue JSON::ParserError => e
+                          { error: "응답 파싱 실패: #{e.message}", body: response.body.to_s }
+                        end
+
+      # 응답 처리
+      BootpayStorage::Response.new(
+        response.status.to_i == 200,
+        parsed_response
+      )
+    rescue Exception => e
+      BootpayStorage::Response.new(
+        false,
+        message:   "파일 업로드 실패: #{e.message}",
+        backtrace: e.backtrace.join("\n")
+      )
+    end
+
 
     # def upload(uri:, image_data:, image_name:, headers: {}, params: nil)
     #

data/lib/bootpay_storage/concern.rb

@@ -3,8 +3,10 @@ module BootpayStorage
     require_relative 'concern/rest'
     require_relative 'concern/token'
     require_relative 'concern/image'
+    require_relative 'concern/csv'
     include Rest
     include Image
     include Token
+    include Csv
   end
 end

data/lib/bootpay_store/bootpay-store-rest-client.rb

@@ -2,6 +2,7 @@
 
 require 'active_support/all'
 require 'http'
+require 'base64'
 require_relative 'response'
 require_relative '../version'
 require_relative 'concern'
@@ -19,12 +20,12 @@ module BootpayStore
 
     SDK_VERSION = '5.0.0'
 
-    def initialize(server_key:, private_key:, mode: 'production')
-      @server_key     = server_key
-      @private_key    = private_key
-      @mode           = mode.presence || 'production'
-      @token          = nil
-      @api_version    = SDK_VERSION
+    def initialize(client_key: nil, private_key: nil, server_key: nil, secret_key: nil, mode: 'production')
+      @client_key  = server_key.presence || client_key
+      @secret_key  = private_key.presence || secret_key
+      @mode        = mode.presence || 'production'
+      @token       = nil
+      @api_version = SDK_VERSION
       raise ArgumentError, "개발환경 mode는 development, stage, production 중에서 선택이 가능합니다." if API[@mode.to_sym].blank?
     end
 

data/lib/bootpay_store/concern/alimtalk_message.rb

@@ -0,0 +1,67 @@
+module BootpayStore::Concern::AlimtalkMessage
+  extend ActiveSupport::Concern
+
+  # 알림톡 발송내역·집계 — GET /v1/alimtalk/messages 계열
+  #
+  # **유료** 알림톡만 조회된다(무료 커머스 알림톡은 포함되지 않는다).
+  # 상태는 벤더 결과 동기화로 확정되므로 접수 직후에는 requested 로 보인다.
+  #
+  # @comment_by Claude (alfred)
+  # @date: 26-08-27
+  included do
+    # 발송내역 목록을 조회한다 (GET /v1/alimtalk/messages)
+    # status: requested·success·failed·canceled
+    # to: 수신번호(하이픈 무관, 정확 매칭) / ref_id: 발송 시 넘긴 멱등키
+    # ⚠️ 기간 기본값은 최근 30일이고 최대 조회 폭은 92일이다 — 초과분은 거부하지 않고 시작일을 당겨 잘라낸다.
+    #    실제 적용된 구간은 응답의 period 로 확인한다.
+    # 응답: { list: [...], count:, page:, per:, period: { from:, to: } }
+    def alimtalk_message_list(template_code: nil, status: nil, ref_id: nil, to: nil,
+                              s_at: nil, e_at: nil, page: nil, limit: nil)
+      request(
+        uri:     'alimtalk/messages',
+        method:  :get,
+        headers: { 'Bootpay-Role' => 'user' },
+        params:  {
+          template_code: template_code,
+          status:        status,
+          ref_id:        ref_id,
+          to:            to,
+          s_at:          s_at,
+          e_at:          e_at,
+          page:          page,
+          limit:         limit # 서버 기본 20, 최대 100
+        }.compact
+      )
+    end
+
+    # 기간 집계를 조회한다 (GET /v1/alimtalk/messages/stats)
+    # 일자별 집계 원장에서 읽으므로 응답이 빠르다.
+    # 응답: { period:, totals: { sent, success, failed, fallback, opted_out_hit, rejected, canceled, success_rate },
+    #        daily: [...], billing: { billable_count, unit_price, fallback_count, ..., amount } }
+    # ⚠️ billing.unit_price_source 가 'default' 면 **잠정 단가**다(확정 청구액이 아니다).
+    # ⚠️ billable_count 는 성공 − 폴백이다 — 폴백분은 LMS 단가로 따로 계산된다.
+    def alimtalk_message_stats(s_at: nil, e_at: nil)
+      request(
+        uri:     'alimtalk/messages/stats',
+        method:  :get,
+        headers: { 'Bootpay-Role' => 'user' },
+        params:  {
+          s_at: s_at,
+          e_at: e_at
+        }.compact
+      )
+    end
+
+    # 단건 발송 결과를 조회한다 (GET /v1/alimtalk/messages/:receipt_id)
+    # 실패 사유는 error_code·error_message 에 담긴다.
+    # fallback_type 은 폴백이 꺼진 건이면 null, 켜진 건이면 LMS 다.
+    # 다른 프로젝트의 건이거나 없으면 404(3025).
+    def alimtalk_message_detail(receipt_id:)
+      request(
+        uri:     "alimtalk/messages/#{receipt_id}",
+        method:  :get,
+        headers: { 'Bootpay-Role' => 'user' }
+      )
+    end
+  end
+end

data/lib/bootpay_store/concern/alimtalk_official.rb

@@ -0,0 +1,63 @@
+module BootpayStore::Concern::AlimtalkOfficial
+  extend ActiveSupport::Concern
+
+  # 부트페이 공식 알림톡 템플릿 카탈로그 — GET/POST /v1/alimtalk/official 계열
+  #
+  # 부트페이가 미리 카카오 승인을 받아 둔 템플릿이라, 그룹키가 등록된 채널이면 **검수 없이 즉시 발송**된다.
+  # `alimtalk_sender_create` 로 채널을 등록하면 그룹 등록이 함께 끝나므로 따로 채택할 것이 없다.
+  #
+  # 전부 조회 계열이라 부작용이 없다(자체 DB 만 본다).
+  # @date: 26-08-27 채택(alimtalk_official_adopt) 제거 — 서버에서도 엔드포인트를 비활성화했다.
+  #
+  # @comment_by Claude (alfred)
+  # @date: 26-08-27
+  included do
+    # 공식 템플릿을 검색한다 (GET /v1/alimtalk/official)
+    # keyword 는 본문·이름·분류를 부분일치(대소문자 무시)로 훑는다.
+    # msg_type 은 BA(기본형)·EX(부가정보형)만 존재한다 — 그룹 템플릿이라 AD/MI 는 쓸 수 없다.
+    # ksp_id 를 주면 그 채널의 변수 예문 사전으로 variable_examples 를 채워 준다(표시용).
+    # 응답: { list: [...], count:, page:, per:, categories: [...] }
+    def alimtalk_official_list(keyword: nil, category: nil, msg_type: nil, page: nil, per: nil, ksp_id: nil)
+      request(
+        uri:     'alimtalk/official',
+        method:  :get,
+        headers: { 'Bootpay-Role' => 'user' },
+        params:  {
+          q:        keyword, # 서버는 q 를 먼저 보고 없으면 keyword 를 본다 — 정본 키인 q 로 보낸다
+          category: category,
+          msg_type: msg_type,
+          page:     page,
+          per:      per, # 서버 기본 20, 최대 100 으로 clamp
+          ksp_id:   ksp_id
+        }.compact
+      )
+    end
+
+    # 보내려는 문구로 공식 템플릿을 추천받는다 (POST /v1/alimtalk/official/recommend)
+    # 유사도 score(0~1) 내림차순으로 돌려준다.
+    def alimtalk_official_recommend(text:, category: nil, limit: nil, ksp_id: nil)
+      request(
+        uri:     'alimtalk/official/recommend',
+        method:  :post,
+        headers: { 'Bootpay-Role' => 'user' },
+        payload: {
+          text:     text,
+          category: category,
+          limit:    limit, # 서버 기본 5
+          ksp_id:   ksp_id
+        }.compact
+      )
+    end
+
+    # 공식 템플릿 상세를 조회한다 (GET /v1/alimtalk/official/:code)
+    # code 는 서버 채번 코드(슬래시를 포함하지 않는다). 없거나 미노출이면 404(3015).
+    def alimtalk_official_detail(code:, ksp_id: nil)
+      request(
+        uri:     "alimtalk/official/#{code}",
+        method:  :get,
+        headers: { 'Bootpay-Role' => 'user' },
+        params:  { ksp_id: ksp_id }.compact
+      )
+    end
+  end
+end