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

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

data/lib/bootpay_store/concern/alimtalk_template.rb

@@ -0,0 +1,215 @@
+module BootpayStore::Concern::AlimtalkTemplate
+  extend ActiveSupport::Concern
+
+  # 가맹점 자체 알림톡 템플릿 CRUD·등록·검수 — /v1/alimtalk/templates 계열
+  #
+  # 흐름: (초안 생성 → 확인 → 대행사 등록) → 검수 요청 → 승인(APR) → 발송 가능
+  #   `alimtalk_template_create(register: false)` 로 초안만 만들고, 내용을 확인한 뒤
+  #   `alimtalk_template_register` 로 올리는 것을 권장한다.
+  #
+  # ⚠️ `register` 를 명시적으로 false 로 주지 않으면 **생성 즉시 대행사·카카오에 실제 등록**된다.
+  # ⚠️ 본문 변수는 `#{변수명}` 형식이고 템플릿 전체에서 최대 40개다.
+  #
+  # @comment_by Claude (alfred)
+  # @date: 26-08-27
+  included do
+    # 내 자체 템플릿 목록을 조회한다 (GET /v1/alimtalk/templates)
+    # ins: 검수상태 필터 — 1 REG(등록) / 2 REQ(검수요청) / 3 APR(승인) / 4 KRR(등록거절) / 5 REJ(승인반려).
+    #      숫자·숫자문자열·벤더 문자열('APR' 등)을 모두 받는다. 해석 못 하는 값은 필터 없음으로 떨어진다.
+    # keyword: 코드·이름·본문·분류 부분일치. sort: latest(기본)·oldest·code.
+    # ⚠️ 페이지네이션이 없다 — 필터에 걸린 템플릿을 한 번에 모두 돌려준다.
+    def alimtalk_template_list(ins: nil, sort: nil, keyword: nil)
+      request(
+        uri:     'alimtalk/templates',
+        method:  :get,
+        headers: { 'Bootpay-Role' => 'user' },
+        params:  {
+          ins:     ins,
+          sort:    sort,
+          keyword: keyword
+        }.compact
+      )
+    end
+
+    # 자체 템플릿을 생성한다 (POST /v1/alimtalk/templates)
+    # ⚠️ register 를 false 로 주지 않으면 대행사·카카오에 **실제 등록**된다(되돌리려면 삭제해야 한다).
+    #
+    # emphasize_type: NONE·TEXT(강조표기형)·IMAGE(이미지형)·ITEM_LIST(아이템리스트형)
+    #   - TEXT 는 emphasize_title·emphasize_subtitle 둘 다 필수(각 50자·40자)
+    #   - IMAGE 는 이미지 필수 — alimtalk_template_image 로 올린 URL 을 storage_image_url 로 넘긴다
+    #   - ITEM_LIST 는 template_item.list(2~10개) 필수 + template_header·item_highlight·이미지 중 하나 이상
+    # msg_type: BA(기본형)·EX(부가정보형, template_extra 필수)·AD(채널추가형)·MI(복합형)
+    #   - AD·MI 는 채널추가(AC) 버튼이 필수다
+    # examples: 변수 예문(표시용). 주면 **모든 변수에 예문이 있어야** 한다(없으면 3017).
+    def alimtalk_template_create(ksp_id:, name: nil, content: nil, register: nil, buttons: nil,
+                                 msg_type: nil, emphasize_type: nil, emphasize_title: nil,
+                                 emphasize_subtitle: nil, template_extra: nil, template_header: nil,
+                                 item_highlight: nil, template_item: nil, image_url: nil,
+                                 storage_image_url: nil, security_flag: nil, category: nil, tags: nil,
+                                 examples: nil, template_code: nil, **attrs)
+      request(
+        uri:     'alimtalk/templates',
+        method:  :post,
+        headers: { 'Bootpay-Role' => 'user' },
+        payload: {
+          ksp_id:             ksp_id,
+          register:           register,
+          name:               name,
+          content:            content,
+          buttons:            buttons,
+          msg_type:           msg_type,
+          emphasize_type:     emphasize_type,
+          emphasize_title:    emphasize_title,
+          emphasize_subtitle: emphasize_subtitle,
+          template_extra:     template_extra,
+          template_header:    template_header,
+          item_highlight:     item_highlight,
+          template_item:      template_item,
+          image_url:          image_url,
+          storage_image_url:  storage_image_url,
+          security_flag:      security_flag,
+          category:           category,
+          tags:               tags,
+          examples:           examples,
+          template_code:      template_code
+        }.merge(attrs).compact
+      )
+    end
+
+    # 자체 템플릿 상세를 조회한다 (GET /v1/alimtalk/templates/:id)
+    # template_id 는 문서 id 이고, ObjectId 형식이 아니면 **템플릿 코드**로 해석한다.
+    # ⚠️ sync 는 서버 기본값이 **true** 라 조회만 해도 벤더 상태 동기화가 일어난다.
+    #    초안(등록 전)을 조회할 때는 sync: false 를 권장한다.
+    def alimtalk_template_detail(template_id:, sync: nil)
+      request(
+        uri:     "alimtalk/templates/#{template_id}",
+        method:  :get,
+        headers: { 'Bootpay-Role' => 'user' },
+        params:  { sync: sync }.compact
+      )
+    end
+
+    # 자체 템플릿을 수정한다 (PUT /v1/alimtalk/templates/:id)
+    # ⚠️ **부분 수정이 아니다.** 보내지 않은 필드는 nil 로 덮어써지므로 항상 전체 필드를 보낸다.
+    # ⚠️ 등록된 템플릿을 수정하면 벤더에도 수정 요청이 나간다.
+    #    수정 가능 상태는 초안 / REG(등록) / REJ(승인반려) / KRR(등록거절) 뿐이다 — APR·REQ 는 거부된다.
+    # storage_image_url 을 빈 값으로 보내면 **이미지 삭제**로 처리되어 벤더에도 전달된다.
+    def alimtalk_template_update(template_id:, name: nil, content: nil, buttons: nil, msg_type: nil,
+                                 emphasize_type: nil, emphasize_title: nil, emphasize_subtitle: nil,
+                                 template_extra: nil, template_header: nil, item_highlight: nil,
+                                 template_item: nil, image_url: nil, storage_image_url: nil,
+                                 security_flag: nil, category: nil, tags: nil, examples: nil,
+                                 template_code: nil, **attrs)
+      request(
+        uri:     "alimtalk/templates/#{template_id}",
+        method:  :put,
+        headers: { 'Bootpay-Role' => 'user' },
+        payload: {
+          name:               name,
+          content:            content,
+          buttons:            buttons,
+          msg_type:           msg_type,
+          emphasize_type:     emphasize_type,
+          emphasize_title:    emphasize_title,
+          emphasize_subtitle: emphasize_subtitle,
+          template_extra:     template_extra,
+          template_header:    template_header,
+          item_highlight:     item_highlight,
+          template_item:      template_item,
+          image_url:          image_url,
+          storage_image_url:  storage_image_url,
+          security_flag:      security_flag,
+          category:           category,
+          tags:               tags,
+          examples:           examples,
+          template_code:      template_code
+        }.merge(attrs).compact
+      )
+    end
+
+    # 자체 템플릿을 삭제한다 (DELETE /v1/alimtalk/templates/:id)
+    # 초안(등록 전)은 대행사 거부와 무관하게 로컬에서 삭제된다.
+    # ⚠️ 등록분은 **대행사 삭제가 성공해야** 삭제된다 — 승인(APR) 템플릿은 카카오가 거부하므로
+    #    500(3013)이 오고 템플릿은 남는다. 같은 코드가 대행사에 선점된 채 로컬만 사라지는 것을 막기 위함이다.
+    def alimtalk_template_delete(template_id:)
+      request(
+        uri:     "alimtalk/templates/#{template_id}",
+        method:  :delete,
+        headers: { 'Bootpay-Role' => 'user' }
+      )
+    end
+
+    # 초안을 대행사에 등록한다 (POST /v1/alimtalk/templates/:id/register)
+    # ⚠️ 대행사·카카오에 실제 등록된다. 등록 전(초안) 상태에서만 호출할 수 있다.
+    def alimtalk_template_register(template_id:)
+      request(
+        uri:     "alimtalk/templates/#{template_id}/register",
+        method:  :post,
+        headers: { 'Bootpay-Role' => 'user' }
+      )
+    end
+
+    # 검수를 요청한다 (POST /v1/alimtalk/templates/:id/inspect)
+    # ⚠️ **카카오에 검수를 요청하며 취소할 수 없다.**
+    # 대행사 등록이 끝난 대기(R) + REG(등록) 상태에서만 호출할 수 있다 — 초안은 먼저 register 를 부른다.
+    # 반려(REJ/KRR)된 건은 재요청이 아니라 **수정 후 재요청**이다. 반려 사유는 응답의 comments 에 담긴다.
+    def alimtalk_template_inspect(template_id:)
+      request(
+        uri:     "alimtalk/templates/#{template_id}/inspect",
+        method:  :post,
+        headers: { 'Bootpay-Role' => 'user' }
+      )
+    end
+
+    # 템플릿 목록을 내보낸다 (GET /v1/alimtalk/templates/export)
+    # scope: private(기본, 내 채널 자체 템플릿)·official(공식 카탈로그)·all
+    # ⚠️ 기본 format 을 **json 으로 둔다** — 서버 기본은 csv 지만, csv 본문은 JSON 이 아니라서
+    #    공용 request 의 파싱을 통과하지 못한다. csv 를 주면 파싱 없이 원문 문자열을 담아 돌려준다.
+    # 1회 5,000건을 넘으면 3031 로 거부되므로 채널·상태 필터로 좁힌다.
+    def alimtalk_template_export(format: 'json', scope: nil, ksp_id: nil, status: nil, include_content: nil)
+      params = {
+        format:          format,
+        scope:           scope,
+        ksp_id:          ksp_id,
+        status:          status,
+        include_content: include_content
+      }.compact
+
+      return request_raw(uri: 'alimtalk/templates/export', params: params,
+                         headers: { 'Bootpay-Role' => 'user' }) if format.to_s == 'csv'
+
+      request(
+        uri:     'alimtalk/templates/export',
+        method:  :get,
+        headers: { 'Bootpay-Role' => 'user' },
+        params:  params
+      )
+    end
+
+    # 이미지형 템플릿의 원본 이미지를 올린다 (POST /v1/alimtalk/templates/image)
+    # 돌려받은 image_url 을 템플릿 생성/수정의 storage_image_url 로 넘긴다.
+    # 규격을 업로드 **전에** 서버가 검사한다 — jpg/png · 500KB 이하 · 가로 500px 이상 · 2:1.
+    # image 는 파일 경로(String)·IO·HTTP::FormData::File 을 모두 받는다.
+    # replace_url 을 주면 업로드 성공 후에 기존 파일을 지운다.
+    def alimtalk_template_image(image:, replace_url: nil)
+      form = { 'image' => multipart_file(image) }
+      form['replace_url'] = multipart_value(replace_url) if replace_url.present?
+
+      post_multipart(uri: 'alimtalk/templates/image', form: form,
+                     headers: { 'Bootpay-Role' => 'user' })
+    end
+
+    # 아이템리스트형의 하이라이트 썸네일을 올린다 (POST /v1/alimtalk/templates/highlight_image)
+    # ⚠️ 본문 이미지와 **규격이 다르다** — jpg/png · 500KB 이하 · 가로 **108px** 이상 · **1:1**.
+    #    본문 이미지 엔드포인트로 올리면 거부된다.
+    # 돌려받은 image_url 은 item_highlight.storage_image_url 로 넘긴다.
+    # ⚠️ 썸네일을 붙이면 하이라이트 글자 한도가 줄어든다(타이틀 30→21, 설명 19→13).
+    def alimtalk_template_highlight_image(image:, replace_url: nil)
+      form = { 'image' => multipart_file(image) }
+      form['replace_url'] = multipart_value(replace_url) if replace_url.present?
+
+      post_multipart(uri: 'alimtalk/templates/highlight_image', form: form,
+                     headers: { 'Bootpay-Role' => 'user' })
+    end
+  end
+end

data/lib/bootpay_store/concern/alimtalk_webhook.rb

@@ -0,0 +1,84 @@
+module BootpayStore::Concern::AlimtalkWebhook
+  extend ActiveSupport::Concern
+
+  # 알림톡 발송결과·검수결과 웹훅 설정 — /v1/alimtalk/webhook 계열
+  #
+  # ⚠️ **주문·구독 통합 웹훅과 완전히 별개다.** 알림톡 이벤트를 기존 주문 웹훅 URL 로 태우면
+  #    그 수신 서버가 모르는 payload 를 받아 기존 연동이 깨진다. 그래서 수신 URL 을 따로 둔다.
+  #    (`send_test_webhook` 은 주문 웹훅용이다 — 이 파일의 `alimtalk_webhook_test` 와 혼동하지 말 것)
+  #
+  # ## 서명 검증
+  # 요청에 다음 헤더가 붙는다.
+  #   X-Bootpay-Signature: sha256=HMAC_SHA256(secret, "{X-Bootpay-Timestamp}.{raw_body}")
+  # 타임스탬프가 5분 이상 지난 요청은 거부한다(replay 방지).
+  #
+  # @comment_by Claude (alfred)
+  # @date: 26-08-27
+  included do
+    # 웹훅 설정을 조회한다 (GET /v1/alimtalk/webhook)
+    # 시크릿은 앞 12자만 노출된다. 미설정이면 { configured: false } 로 온다.
+    def alimtalk_webhook_detail
+      request(
+        uri:     'alimtalk/webhook',
+        method:  :get,
+        headers: { 'Bootpay-Role' => 'user' }
+      )
+    end
+
+    # 웹훅 설정을 저장한다 (PUT /v1/alimtalk/webhook)
+    # url 은 **https 만** 허용한다(아니면 3028). 최초 저장 시 서명 시크릿이 자동 발급된다.
+    # events: 구독할 이벤트 코드. 목록에 없는 값은 저장 시 조용히 버려진다(유령 구독 방지).
+    #   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)
+      request(
+        uri:     'alimtalk/webhook',
+        method:  :put,
+        headers: { 'Bootpay-Role' => 'user' },
+        payload: {
+          url:     url,
+          events:  events,
+          enabled: enabled
+        }.compact
+      )
+    end
+
+    # 테스트 이벤트를 1건 발송한다 (POST /v1/alimtalk/webhook/test)
+    # ⚠️ **설정된 URL 로 실제 HTTP 요청이 나간다.** 구독 여부와 무관하게 보낸다.
+    # 웹훅이 설정돼 있지 않으면 3029. 응답: { delivery_id:, url:, queued: }
+    def alimtalk_webhook_test
+      request(
+        uri:     'alimtalk/webhook/test',
+        method:  :post,
+        headers: { 'Bootpay-Role' => 'user' }
+      )
+    end
+
+    # 서명 시크릿을 재발급한다 (POST /v1/alimtalk/webhook/secret)
+    # ⚠️ **이 응답에서만 secret 원문을 돌려준다**(이후 조회는 마스킹된다).
+    # ⚠️ 이미 큐에 있는 전송 건은 발송 당시 시크릿으로 서명된다.
+    def alimtalk_webhook_rotate_secret
+      request(
+        uri:     'alimtalk/webhook/secret',
+        method:  :post,
+        headers: { 'Bootpay-Role' => 'user' }
+      )
+    end
+
+    # 웹훅 전송 이력을 조회한다 (GET /v1/alimtalk/webhook/deliveries)
+    # 성공·실패를 모두 남긴다. 응답: { list: [{ delivery_id:, event:, event_code:, url:, status:,
+    #   retry_count:, max_retry:, tags:, created_at: }], count:, page:, per: }
+    def alimtalk_webhook_deliveries(page: nil, limit: nil)
+      request(
+        uri:     'alimtalk/webhook/deliveries',
+        method:  :get,
+        headers: { 'Bootpay-Role' => 'user' },
+        params:  {
+          page:  page,
+          limit: limit # 서버 기본 20, 최대 100
+        }.compact
+      )
+    end
+  end
+end

data/lib/bootpay_store/concern/invoice.rb

@@ -0,0 +1,102 @@
+module BootpayStore::Concern::Invoice
+  extend ActiveSupport::Concern
+
+  included do
+    # 청구서를 생성한다
+    # Comment by GOSOMI
+    # @date: 2025-10-03
+    def request_checkout(sdk: false, idempotency_key: nil, name:, memo: nil, user: {}, products: [], price: 0, tax_free_price: 0, delivery_price: 0,
+                         redirect_url: nil, request_id: nil, use_notification: false, use_auto_login: false, expired_at: nil, metadata: {},
+                         webhook_url: nil, header_content_type: 'application/json', usage_api_url: nil, extra: {})
+      request(
+        uri:     'invoices',
+        method:  :post,
+        headers: {
+          'Idempotency-Key' => idempotency_key.presence || SecureRandom.uuid,
+          'Bootpay-Role'    => 'user'
+        },
+        payload:
+                 {
+                   sdk:                 sdk,
+                   name:                name,
+                   memo:                memo,
+                   user:                user,
+                   products:            products,
+                   price:               price,
+                   tax_free_price:      tax_free_price,
+                   delivery_price:      delivery_price,
+                   redirect_url:        redirect_url,
+                   request_id:          request_id,
+                   use_notification:    use_notification,
+                   use_auto_login:      use_auto_login,
+                   expired_at:          expired_at,
+                   metadata:            metadata,
+                   webhook_url:         webhook_url,
+                   header_content_type: header_content_type,
+                   usage_api_url:       usage_api_url,
+                   extra:               extra
+                 }.compact
+      )
+    end
+
+    alias :create_invoice :request_checkout
+
+    # 청구서 목록을 조회한다 (GET /v1/invoices)
+    # @comment_by Claude (alfred)
+    # @date: 26-08-14
+    # 응답은 { list: [...], count: N } 구조다 ({ items, total } 아님 — Node SDK 타입선언이 틀렸던 지점).
+    # 서버 기본 limit 은 24.
+    def invoice_list(page: 1, limit: 24, keyword: nil, cs_type: nil, user_id: nil,
+                     product_type: nil, css_at: nil, cse_at: nil, idempotency_key: nil)
+      request(
+        uri:     'invoices',
+        method:  :get,
+        headers: {
+          'Idempotency-Key' => idempotency_key.presence || SecureRandom.uuid,
+          'Bootpay-Role'    => 'user'
+        },
+        params:  {
+                   page:         page,
+                   limit:        limit,
+                   keyword:      keyword,
+                   cs_type:      cs_type,
+                   user_id:      user_id,
+                   product_type: product_type,
+                   css_at:       css_at,
+                   cse_at:       cse_at
+                 }.compact
+      )
+    end
+
+    # 청구서 상세를 조회한다 (GET /v1/invoices/:id)
+    # @comment_by Claude (alfred)
+    # @date: 26-08-14
+    def invoice_detail(invoice_id:, idempotency_key: nil)
+      request(
+        uri:     "invoices/#{invoice_id}",
+        method:  :get,
+        headers: {
+          'Idempotency-Key' => idempotency_key.presence || SecureRandom.uuid,
+          'Bootpay-Role'    => 'user'
+        }
+      )
+    end
+
+    # 청구서를 재안내한다 (POST /v1/invoices/:id/notify)
+    # @comment_by Claude (alfred)
+    # @date: 26-08-14
+    # send_types 미전달 시 서버가 빈 배열로 처리한다.
+    # ⚠️ 실제 고객에게 알림이 발송되므로 테스트 호출 주의.
+    def invoice_notify(invoice_id:, send_types: nil, idempotency_key: nil)
+      request(
+        uri:     "invoices/#{invoice_id}/notify",
+        method:  :post,
+        headers: {
+          'Idempotency-Key' => idempotency_key.presence || SecureRandom.uuid,
+          'Bootpay-Role'    => 'user'
+        },
+        payload: { send_types: send_types }.compact
+      )
+    end
+  end
+end