bootpay 1.2.0 → 3.0.0

data/lib/bootpay_storage/concern/rest.rb

@@ -0,0 +1,176 @@
+module BootpayStorage::Concern::Rest
+  extend ActiveSupport::Concern
+
+  included do
+    private
+
+    # HTTP Request 기본 Method
+    # Comment by Gosomi
+    # Date: 2021-05-21
+    def request(method: :post, uri:, payload: {}, headers: {}, params: nil)
+      response = HTTP.headers(
+        {
+          Authorization:       "Bearer #{@token}",
+          content_type:        'application/json',
+          accept:              'application/json',
+          bootpay_api_version: @api_version,
+          bootpay_sdk_version: Bootpay::V2_VERSION,
+          bootpay_sdk_type:    '300'
+        }.merge!(headers).compact
+      ).send(
+        method.to_sym,
+        [BootpayStorage::RestClient::API[@mode.to_sym], uri].join('/'),
+        json:   payload,
+        params: params
+      )
+      BootpayStorage::Response.new(
+        response.status.to_i == 200,
+        JSON.parse(response.body.to_s, symbolize_names: true)
+      )
+    rescue Exception => e
+      BootpayStorage::Response.new(
+        false,
+        message:   "부트페이 API 서버와의 통신이 실패하였습니다. 오류 메세지: #{e.message}",
+        backtrace: e.backtrace.join("\n")
+      )
+    end
+
+    # Multipart 파일 전송 Method
+    # Comment by Gosomi
+    # Date: 2025-03-25
+    def upload(uri:, images:, headers: {}, params: nil)
+      # 이미지 데이터를 배열로 받음
+      files = images.each_with_index.map do |data, index|
+        filename = "image_#{Time.now.to_i}_#{index}.jpg"
+        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
+
+    # 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)
+    #
+    #   # puts [BootpayStorage::RestClient::API[@mode.to_sym], uri].join('/')
+    #
+    #   # 파일 객체 생성
+    #   file = HTTP::FormData::File.new(image_data, filename: image_name)
+    #
+    #   # 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: [file] },
+    #     params: params
+    #   )
+    #
+    #   # 응답 상태와 바디 출력
+    #   puts "Response Status: #{response.status}"
+    #   puts "Response Body: #{response.body.to_s}"
+    #
+    #   # 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
+
+  end
+end

data/lib/bootpay_storage/concern/token.rb

@@ -0,0 +1,9 @@
+module BootpayStorage::Concern::Token
+  extend ActiveSupport::Concern
+
+  included do
+    def set_token(token)
+      @token = token
+    end
+  end
+end

data/lib/bootpay_storage/concern.rb

@@ -0,0 +1,12 @@
+module BootpayStorage
+  module Concern
+    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_storage/response.rb

@@ -0,0 +1,14 @@
+module BootpayStorage
+  class Response
+    attr_reader :data
+
+    def initialize(success = true, data = {})
+      @success = success
+      @data    = data
+    end
+
+    def success?
+      @success
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'active_support/all'
+require 'http'
+require 'base64'
+require_relative 'response'
+require_relative '../version'
+require_relative 'concern'
+
+module BootpayStore
+  class RestClient
+    include Concern
+
+    API =
+      {
+        development: 'https://dev-api.bootapi.com/v1',
+        stage:       'https://stage-api.bootapi.com/v1',
+        production:  'https://api.bootapi.com/v1'
+      }
+
+    SDK_VERSION = '5.0.0'
+
+    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
+
+    # API URL을 변경
+    # Comment by GOSOMI
+    # @date: 2023-05-26
+    def set_api_url(url)
+      API[@mode.to_sym] = url
+    end
+
+    # API 버전을 설정한다
+    # Comment by Gosomi
+    # Date: 2022-07-29
+    def set_api_version(version)
+      raise ArgumentError, 'API Version은 4.0.0 이상만 설정이 가능합니다.' if version < '4.0.0'
+      @api_version = version
+    end
+  end
+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

data/lib/bootpay_store/concern/alimtalk_optout.rb

@@ -0,0 +1,72 @@
+module BootpayStore::Concern::AlimtalkOptout
+  extend ActiveSupport::Concern
+
+  # 알림톡 수신거부 — /v1/alimtalk/optouts 계열 (가맹점 CRM 수신거부 동기화용)
+  #
+  # 발송 판정과 **같은 기준**으로 다룬다 — 부트페이 전역(global) + 내 프로젝트.
+  # ⚠️ 전역 건은 **조회는 되지만 해제할 수 없다**(releasable: false).
+  #    이걸 노출하지 않으면 "화면엔 수신거부가 아닌데 발송은 3021 로 막히는" 상태가 된다.
+  #
+  # @comment_by Claude (alfred)
+  # @date: 26-08-27
+  included do
+    # 수신거부 목록을 조회한다 (GET /v1/alimtalk/optouts)
+    # phone 은 숫자만 남겨 **부분일치**로 찾는다(정확 매칭이 아니다). 50건 단위로 페이징된다.
+    # 응답: { list: [{ id:, phone:, scope:, global:, releasable:, source:, reason:, opted_out_at:, created_at: }],
+    #        count:, page: }
+    def alimtalk_optout_list(phone: nil, page: nil)
+      request(
+        uri:     'alimtalk/optouts',
+        method:  :get,
+        headers: { 'Bootpay-Role' => 'user' },
+        params:  {
+          phone: phone,
+          page:  page
+        }.compact
+      )
+    end
+
+    # 수신거부를 등록한다 (POST /v1/alimtalk/optouts)
+    # 내 프로젝트 스코프로 등록된다(source: api). 같은 번호를 다시 등록해도 멱등이다.
+    def alimtalk_optout_create(phone:, reason: nil)
+      request(
+        uri:     'alimtalk/optouts',
+        method:  :post,
+        headers: { 'Bootpay-Role' => 'user' },
+        payload: {
+          phone:  phone,
+          reason: reason
+        }.compact
+      )
+    end
+
+    # 발송 전에 수신거부를 사전 확인한다 (POST /v1/alimtalk/optouts/check)
+    # 발송 판정과 **같은 축**으로 대조하므로, 벌크에서 skipped 로 낭비될 건을 미리 뺄 수 있다.
+    # 단건(phone)·다건(phones) 모두 받는다. ⚠️ 1회 최대 1,000건이고 넘으면 -48 이다(중복은 서버가 제거).
+    # 응답: { list: [{ phone:, opted_out:, global:, releasable:, opted_out_at: }], count:, opted_out_count: }
+    def alimtalk_optout_check(phones: nil, phone: nil)
+      request(
+        uri:     'alimtalk/optouts/check',
+        method:  :post,
+        headers: { 'Bootpay-Role' => 'user' },
+        payload: {
+          phones: phones,
+          phone:  phone
+        }.compact
+      )
+    end
+
+    # 수신거부를 해제한다 (DELETE /v1/alimtalk/optouts/:phone)
+    # 내 프로젝트 스코프 건만 해제되며 멱등이다(없어도 성공).
+    # ⚠️ 전역 차단은 해제되지 않고 global_blocked: true 로 알려 준다 —
+    #    "지웠는데 여전히 막히는" 상태를 응답으로 드러내기 위함이다.
+    # 응답: { phone:, released:, global_blocked: }
+    def alimtalk_optout_release(phone:)
+      request(
+        uri:     "alimtalk/optouts/#{phone}",
+        method:  :delete,
+        headers: { 'Bootpay-Role' => 'user' }
+      )
+    end
+  end
+end

data/lib/bootpay_store/concern/alimtalk_send.rb

@@ -0,0 +1,83 @@
+module BootpayStore::Concern::AlimtalkSend
+  extend ActiveSupport::Concern
+
+  # 알림톡 발송 — POST /v1/alimtalk/send · /send/bulk · DELETE /send/:receipt_id
+  #
+  # ⚠️ **실제로 카카오톡이 발송되고 과금된다. 샌드박스가 없다.**
+  #
+  # 처리 순서: 멱등 확인 → 템플릿·채널 해석 → 발송권한 → 지갑 자격 → 발송제어 → 폴백 확정(발신번호 확보)
+  #   → 수신거부 대조 → 변수 치환·규격검증 → 접수(READY) → 워커 전송
+  #
+  # - **멱등**: 같은 (프로젝트, ref_id) 로 재요청하면 기존 receipt 를 그대로 돌려준다. 실패한 건만 재발송된다.
+  # - **필수 변수**: 템플릿 응답의 required_variables 를 모두 채워야 한다. 하나라도 비면 3017 로 거부된다.
+  #   ⚠️ 다만 실제로 치환되어 나가는 건 본문·강조 타이틀·버튼 링크뿐이다 — 보조문구와 아이템리스트형
+  #   요소는 발송 페이로드에 자리가 없어 카카오가 등록된 템플릿 문구 그대로 렌더한다.
+  # - **채널**: sender_key(공개키)로 지정한다. 생략하면 프로젝트 연동 채널로 해석하며,
+  #   연동 채널이 둘 이상일 때만 필수다(ksp_id 는 내부 문서 id 라 발송 API 에 쓰지 않는다).
+  #
+  # @comment_by Claude (alfred)
+  # @date: 26-08-27
+  included do
+    # 단건 발송 (POST /v1/alimtalk/send)
+    # variables: { company_name: '부트페이몰', user_name: '홍길동' } 형태의 치환값
+    # ref_id: 가맹점 발송 식별자 — **멱등 키**로 쓰인다
+    # reserved_at: 예약 발송 시각(ISO8601). 생략하면 즉시 발송
+    # fallback: 알림톡 실패 시 문자(LMS) 대체발송 여부.
+    #   ⚠️ **미지정(nil)과 false 는 다르다** — nil 이면 프로젝트 기본값을 따르고, false 는 명시적으로 끈다.
+    #   켜면 발신번호가 등록돼 있어야 하며 없으면 3030 으로 거부된다. 대체 문자에는 수신거부 링크가 자동 포함된다.
+    # 응답: { receipt_id:, ref_id:, to:, status: } — 접수 직후 status 는 requested
+    def alimtalk_send(template_code:, to:, variables: nil, ref_id: nil, fallback: nil,
+                      reserved_at: nil, sender_key: nil, user_id: nil)
+      request(
+        uri:     'alimtalk/send',
+        method:  :post,
+        headers: { 'Bootpay-Role' => 'user' },
+        payload: {
+          template_code: template_code,
+          to:            to,
+          variables:     variables,
+          ref_id:        ref_id,
+          fallback:      fallback, # compact 은 nil 만 걷어내므로 false 는 그대로 전달된다
+          reserved_at:   reserved_at,
+          sender_key:    sender_key,
+          user_id:       user_id
+        }.compact
+      )
+    end
+
+    # 벌크 발송 (POST /v1/alimtalk/send/bulk) — 1요청 = N수신자
+    # recipients: [{ to: '01012345678', ref_id: 'bulk-0001', variables: { ... } }, ...]
+    # ⚠️ 수신자 수만큼 실제 발송되고 과금된다.
+    # - 쿼터를 넘으면 요청 시점에 **전체 거부**된다(3022) — 일부만 나가지 않는다.
+    # - 개별 수신자의 실패는 건별 rejected 로 표시되고 나머지는 정상 발송된다.
+    # - 수신거부 번호는 skipped 이며 **과금되지 않고 발송 기록도 만들지 않는다**.
+    # - fallback 은 요청 단위로 한 번만 판정한다 — 발신번호가 없으면 요청 전체가 3030 으로 거부된다.
+    # 응답: { count:, requested:, skipped:, rejected:, receipts: [...] }
+    def alimtalk_send_bulk(template_code:, recipients:, fallback: nil, reserved_at: nil,
+                           sender_key: nil, user_id: nil)
+      request(
+        uri:     'alimtalk/send/bulk',
+        method:  :post,
+        headers: { 'Bootpay-Role' => 'user' },
+        payload: {
+          template_code: template_code,
+          recipients:    recipients,
+          fallback:      fallback,
+          reserved_at:   reserved_at,
+          sender_key:    sender_key,
+          user_id:       user_id
+        }.compact
+      )
+    end
+
+    # 예약 발송을 취소한다 (DELETE /v1/alimtalk/send/:receipt_id)
+    # 접수(READY) 상태의 예약 건만 취소할 수 있다 — 이미 전송에 들어갔으면 3023 이다.
+    def alimtalk_send_cancel(receipt_id:)
+      request(
+        uri:     "alimtalk/send/#{receipt_id}",
+        method:  :delete,
+        headers: { 'Bootpay-Role' => 'user' }
+      )
+    end
+  end
+end

data/lib/bootpay_store/concern/alimtalk_sender.rb

@@ -0,0 +1,105 @@
+module BootpayStore::Concern::AlimtalkSender
+  extend ActiveSupport::Concern
+
+  # 알림톡 발신프로필(카카오채널) 생명주기 — GET /v1/alimtalk/categories · /senders 계열
+  #
+  # 카테고리 조회 → OTP 발송 → 발신프로필 등록 → 목록/상세 → 연동 해지 순으로 쓴다.
+  # 등록이 끝나면 서버가 그룹키 등록까지 자동으로 하므로, 공식 템플릿은 별도 채택 없이 바로 발송된다.
+  #
+  # ⚠️ 실제 부작용: `alimtalk_sender_otp` 는 채널 관리자 휴대폰으로 **문자를 실제 발송**하고,
+  #    `alimtalk_sender_create` 는 카카오에 발신프로필을 **실제 등록**한다. 샌드박스가 없다.
+  #
+  # ★Idempotency-Key 를 싣지 않는다★ 알림톡 API 는 이 헤더를 읽지 않는다(멱등은 발송의 ref_id 로만 성립).
+  #   invoice/product 처럼 무조건 붙이면 서버가 주지 않는 보장을 주는 것처럼 보인다.
+  # ★Bootpay-Role 은 항상 user★ 알림톡 스코프 키가 전부 `user:alimtalk_*` 다.
+  #
+  # @comment_by Claude (alfred)
+  # @date: 26-08-27
+  included do
+    # 카카오 카테고리 목록을 조회한다 (GET /v1/alimtalk/categories)
+    # 발신프로필 등록 시 필요한 category_code 후보다. 벤더 응답을 그대로 프록시한다.
+    def alimtalk_categories
+      request(
+        uri:     'alimtalk/categories',
+        method:  :get,
+        headers: { 'Bootpay-Role' => 'user' }
+      )
+    end
+
+    # 채널 관리자폰으로 OTP 를 발송한다 (POST /v1/alimtalk/senders/otp)
+    # ⚠️ 실제로 문자가 나간다. 여기서 받은 인증번호를 alimtalk_sender_create 의 otp 로 넘긴다.
+    def alimtalk_sender_otp(yellow_id:, phone:)
+      request(
+        uri:     'alimtalk/senders/otp',
+        method:  :post,
+        headers: { 'Bootpay-Role' => 'user' },
+        payload: {
+          yellow_id: yellow_id,
+          phone:     phone
+        }.compact
+      )
+    end
+
+    # 발신프로필을 등록한다 (POST /v1/alimtalk/senders)
+    # ⚠️ 카카오에 발신프로필이 실제 등록된다. 같은 yellow_id 를 다시 등록하면 기존 프로필을 재사용한다(dedup).
+    # 등록 성공 시 그룹키 등록까지 서버가 수행하므로 공식 카탈로그 전체를 바로 발송할 수 있다.
+    def alimtalk_sender_create(otp:, yellow_id:, phone:, category_code:)
+      request(
+        uri:     'alimtalk/senders',
+        method:  :post,
+        headers: { 'Bootpay-Role' => 'user' },
+        payload: {
+          otp:           otp,
+          yellow_id:     yellow_id,
+          phone:         phone,
+          category_code: category_code
+        }.compact
+      )
+    end
+
+    # 연동한 채널 목록을 조회한다 (GET /v1/alimtalk/senders)
+    # 자체 DB 만 조회하며 벤더를 호출하지 않는다. 응답은 { list: [...], count: N }.
+    def alimtalk_sender_list
+      request(
+        uri:     'alimtalk/senders',
+        method:  :get,
+        headers: { 'Bootpay-Role' => 'user' }
+      )
+    end
+
+    # 채널 상세를 조회한다 (GET /v1/alimtalk/senders/:id)
+    # sync: true 면 벤더에서 채널 상태를 다시 읽어 반영한다(느리다). 미지정이면 자체 DB 만 본다.
+    # ⚠️ 미연동/미존재 채널은 404, 다른 프로젝트의 채널은 403 으로 오며 둘 다 error_code 는 3024 다.
+    def alimtalk_sender_detail(ksp_id:, sync: nil)
+      request(
+        uri:     "alimtalk/senders/#{ksp_id}",
+        method:  :get,
+        headers: { 'Bootpay-Role' => 'user' },
+        params:  { sync: sync }.compact
+      )
+    end
+
+    # 채널 연동을 해지한다 (DELETE /v1/alimtalk/senders/:id)
+    # 이 프로젝트와의 연동만 끊는다 — 채널 모델과 템플릿은 보존된다. 성공 시 본문은 null 이다.
+    def alimtalk_sender_release(ksp_id:)
+      request(
+        uri:     "alimtalk/senders/#{ksp_id}",
+        method:  :delete,
+        headers: { 'Bootpay-Role' => 'user' }
+      )
+    end
+
+    # 채널 변수 예문 사전을 갱신한다 (PUT /v1/alimtalk/senders/:id/variable_examples)
+    # 템플릿 미리보기에서 #{user_name} 대신 '홍길동' 처럼 읽히게 하는 **표시용** 값이다.
+    # ⚠️ 발송값이 아니다 — 벤더로 전송되지 않으므로 검수 상태와 무관하다. 보낸 키만 덮어쓴다(부분 갱신).
+    # examples: { user_name: '홍길동', company_name: '부트페이몰' } — 키에 '.' 이나 선행 '$' 는 쓸 수 없다.
+    def alimtalk_sender_variable_examples(ksp_id:, examples:)
+      request(
+        uri:     "alimtalk/senders/#{ksp_id}/variable_examples",
+        method:  :put,
+        headers: { 'Bootpay-Role' => 'user' },
+        payload: { examples: examples }.compact
+      )
+    end
+  end
+end