bootpay 1.2.0 → 3.1.0

data/lib/bootpay_store/concern/product.rb

@@ -0,0 +1,175 @@
+module BootpayStore::Concern::Product
+  extend ActiveSupport::Concern
+
+  included do
+    # 상품 목록을 조회한다 (V1 Mall API)
+    # Comment by Codex
+    # @date: 2026-02-23
+    # @date: 26-08-14 ⚠️ keyword 는 서버(v1/products_controller#index)가 읽지 않는다.
+    #   컨트롤러는 page/limit/category_id/ex_uid/sort 만 사용 — keyword 를 보내도 조용히 무시된다.
+    #   하위호환 때문에 인자는 남겨두되, 검색이 필요하면 서버 지원 추가가 선행되어야 한다.
+    # @date: 26-08-26 ex_uid 인자 추가. 컨트롤러가 params[:ex_uid] 를 읽는데 SDK 에 인자가 없어
+    #   외부 UID 로 상품을 찾을 수 없었다.
+    def products(page: 1, limit: 20, category_id: nil, ex_uid: nil, sort: nil, keyword: nil,
+                 user_jwt: nil, idempotency_key: nil)
+      request(
+        uri:     'products',
+        method:  :get,
+        headers: {
+                   'Idempotency-Key'  => idempotency_key.presence || SecureRandom.uuid,
+                   'Bootpay-User-JWT' => user_jwt
+                 }.compact,
+        params:  {
+                   page:        page,
+                   limit:       limit,
+                   category_id: category_id,
+                   ex_uid:      ex_uid,
+                   sort:        sort,
+                   keyword:     keyword
+                 }.compact
+      )
+    end
+
+    # 상품 상세를 조회한다 (V1 Mall API)
+    # Comment by Codex
+    # @date: 2026-02-23
+    def product_detail(product_id:, user_jwt: nil, idempotency_key: nil)
+      request(
+        uri:     "products/#{product_id}",
+        method:  :get,
+        headers: {
+                   'Idempotency-Key'  => idempotency_key.presence || SecureRandom.uuid,
+                   'Bootpay-User-JWT' => user_jwt
+                 }.compact
+      )
+    end
+
+    # 상품 정보를 가져온다
+    # Comment by GOSOMI
+    # @date: 2025-10-10
+    # @date: 26-08-14 product_detail 과 uri·동작이 같다(차이는 user_jwt 인자 유무).
+    #   중복이지만 기존 사용자가 있을 수 있어 제거하지 않는다 — 신규 코드는 product_detail 을 쓸 것.
+    # @date: 26-08-26 user_jwt 를 여기에도 추가했다. 매뉴얼이 GET /v1/products/:id 에 user_jwt 를
+    #   안내하는데 이 메서드만 헤더를 안 보내 회원 컨텍스트 조회가 안 됐다. 이제 product_detail 과 동작이 같다.
+    def lookup_product(product_id:, user_jwt: nil, idempotency_key: nil)
+      request(
+        uri:     "products/#{product_id}",
+        method:  :get,
+        headers: {
+          'Idempotency-Key'  => idempotency_key.presence || SecureRandom.uuid,
+          'Bootpay-User-JWT' => user_jwt
+        }.compact
+      )
+    end
+
+    # 상품을 등록한다 (POST /v1/products)
+    # @comment_by Claude (alfred)
+    # @date: 26-08-14
+    # images 가 있으면 multipart, 없으면 JSON 으로 보낸다.
+    # 컨트롤러가 읽는 필드는 _product_params 참조 — 여기 명시하지 않은 값도 attrs 로 그대로 전달된다.
+    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,
+                       images: nil, save_by: nil, idempotency_key: nil, **attrs)
+      payload = {
+        name:                    name,
+        display_price:           display_price,
+        desc:                    desc,
+        content:                 content,
+        category_id:             category_id,
+        type:                    type,
+        stock:                   stock,
+        status_sale:             status_sale,
+        status_display:          status_display,
+        use_subscription:        use_subscription,
+        subscription_setting_id: subscription_setting_id,
+        save_by:                 save_by
+      }.merge(attrs).compact
+
+      headers = {
+        'Idempotency-Key' => idempotency_key.presence || SecureRandom.uuid,
+        'Bootpay-Role'    => 'manager'
+      }
+
+      if images.present?
+        form = payload.each_with_object({}) { |(k, v), h| h[k.to_s] = multipart_value(v) }
+        Array(images).each_with_index { |image, i| form["images[#{i}]"] = multipart_file(image) }
+        post_multipart(uri: 'products', form: form, headers: headers)
+      else
+        request(uri: 'products', method: :post, headers: headers, payload: payload)
+      end
+    end
+
+    # 상품을 수정한다 (PUT /v1/products/:id)
+    # @comment_by Claude (alfred)
+    # @date: 26-08-14
+    # 바뀐 값만 보내면 된다. category_id 는 키 존재 여부로 '해제 의사'를 판별하므로 주의.
+    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)
+      request(
+        uri:     "products/#{product_id}",
+        method:  :put,
+        headers: {
+          'Idempotency-Key' => idempotency_key.presence || SecureRandom.uuid,
+          'Bootpay-Role'    => 'manager'
+        },
+        payload: {
+                   name:           name,
+                   display_price:  display_price,
+                   desc:           desc,
+                   content:        content,
+                   category_id:    category_id,
+                   stock:          stock,
+                   status_sale:    status_sale,
+                   status_display: status_display,
+                   save_by:        save_by
+                 }.merge(attrs).compact
+      )
+    end
+
+    # 상품을 삭제한다 (DELETE /v1/products/:id)
+    # @comment_by Claude (alfred)
+    # @date: 26-08-14
+    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'
+        }
+      )
+    end
+
+    # 상품 판매/노출 상태를 변경한다 (PUT /v1/products/:id/status)
+    # @comment_by Claude (alfred)
+    # @date: 26-08-14
+    # 컨트롤러 _status_params 기준. 재고(stock)는 여기가 아니라 product_update 로 바꾼다.
+    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,
+                       idempotency_key: nil, **attrs)
+      request(
+        uri:     "products/#{product_id}/status",
+        method:  :put,
+        headers: {
+          'Idempotency-Key' => idempotency_key.presence || SecureRandom.uuid,
+          'Bootpay-Role'    => 'manager'
+        },
+        payload: {
+                   status_sale:        status_sale,
+                   status_display:     status_display,
+                   status_frozen:      status_frozen,
+                   status_review:      status_review,
+                   use_display_period: use_display_period,
+                   display_start_at:   display_start_at,
+                   display_end_at:     display_end_at,
+                   use_sale_period:    use_sale_period,
+                   sale_start_at:      sale_start_at,
+                   sale_end_at:        sale_end_at
+                 }.merge(attrs).compact
+      )
+    end
+  end
+end

data/lib/bootpay_store/concern/product_qna.rb

@@ -0,0 +1,149 @@
+module BootpayStore::Concern::ProductQna
+  extend ActiveSupport::Concern
+
+  included do
+    # 상품문의 목록 (GET /v1/product-qnas)
+    # @comment_by Claude
+    # @date: 26-09-29
+    # 고객 모드는 product_id 필수. 다른 사람의 비밀글은 is_viewable: false 로 본문 없이 온다.
+    # 회원(user_id·login_id·user_jwt)을 보내면 그 회원이 쓴 비밀글 본문이 보인다.
+    # supervisor: true + view: 'all' 이면 몰 전체(숨김 포함) — 이때 product_id 는 선택 필터다.
+    def product_qnas(product_id: nil, view: nil, page: 1, limit: 20, user_id: nil, login_id: nil, user_jwt: nil,
+                     supervisor: false, idempotency_key: nil)
+      request(
+        uri:     'product-qnas',
+        method:  :get,
+        headers: {
+          'Idempotency-Key'  => idempotency_key.presence || SecureRandom.uuid,
+          'Bootpay-Role'     => supervisor ? 'supervisor' : 'user',
+          'Bootpay-User-JWT' => user_jwt
+        }.compact,
+        params:  {
+                   product_id: product_id,
+                   view:       view,
+                   page:       page,
+                   limit:      limit,
+                   user_id:    user_id,
+                   login_id:   login_id
+                 }.compact
+      )
+    end
+
+    # 상품문의 단건 (GET /v1/product-qnas/:id)
+    # @comment_by Claude
+    # @date: 26-09-29
+    # 다른 사람의 비밀글은 403 PRODUCT_QNA_SECRET_FORBIDDEN. supervisor: true 면 비밀글·숨김 글도 본다.
+    def product_qna_detail(product_qna_id:, user_id: nil, login_id: nil, user_jwt: nil, supervisor: false,
+                           idempotency_key: nil)
+      request(
+        uri:     "product-qnas/#{product_qna_id}",
+        method:  :get,
+        headers: {
+          'Idempotency-Key'  => idempotency_key.presence || SecureRandom.uuid,
+          'Bootpay-Role'     => supervisor ? 'supervisor' : 'user',
+          'Bootpay-User-JWT' => user_jwt
+        }.compact,
+        params:  {
+                   user_id:  user_id,
+                   login_id: login_id
+                 }.compact
+      )
+    end
+
+    # 상품문의 작성 (POST /v1/product-qnas)
+    # @comment_by Claude
+    # @date: 26-09-29
+    # 회원(user_id·login_id·user_jwt) 또는 비회원(guest_name + guest_password, 몰이 비회원 작성을 허용할 때).
+    # 회원 문의면 guest_* 는 무시된다.
+    def product_qna_create(product_id:, content:, title: nil, product_option_id: nil, option_text: nil,
+                           is_secret: nil, guest_name: nil, guest_password: nil,
+                           user_id: nil, login_id: nil, user_jwt: nil, idempotency_key: nil)
+      request(
+        uri:     'product-qnas',
+        method:  :post,
+        headers: {
+          'Idempotency-Key'  => idempotency_key.presence || SecureRandom.uuid,
+          'Bootpay-Role'     => 'user',
+          'Bootpay-User-JWT' => user_jwt
+        }.compact,
+        payload: {
+                   product_id:        product_id,
+                   title:             title,
+                   content:           content,
+                   product_option_id: product_option_id,
+                   option_text:       option_text,
+                   is_secret:         is_secret,
+                   guest_name:        guest_name,
+                   guest_password:    guest_password,
+                   user_id:           user_id,
+                   login_id:          login_id
+                 }.compact
+      )
+    end
+
+    # 상품문의 수정 (PUT /v1/product-qnas/:id) — 작성 회원 본인 또는 비회원 비밀번호, 답변 전만
+    # @comment_by Claude
+    # @date: 26-09-29
+    # 답변이 달린 문의는 409 PRODUCT_QNA_ALREADY_ANSWERED, 비회원 비밀번호가 틀리면 403 PRODUCT_QNA_GUEST_PASSWORD_INVALID.
+    def product_qna_update(product_qna_id:, title: nil, content: nil, is_secret: nil, guest_password: nil,
+                           user_id: nil, login_id: nil, user_jwt: nil, idempotency_key: nil)
+      request(
+        uri:     "product-qnas/#{product_qna_id}",
+        method:  :put,
+        headers: {
+          'Idempotency-Key'  => idempotency_key.presence || SecureRandom.uuid,
+          'Bootpay-Role'     => 'user',
+          'Bootpay-User-JWT' => user_jwt
+        }.compact,
+        payload: {
+                   title:          title,
+                   content:        content,
+                   is_secret:      is_secret,
+                   guest_password: guest_password,
+                   user_id:        user_id,
+                   login_id:       login_id
+                 }.compact
+      )
+    end
+
+    # 상품문의 삭제 (DELETE /v1/product-qnas/:id) — 작성 회원 본인·비회원 비밀번호 또는 supervisor
+    # @comment_by Claude
+    # @date: 26-09-29
+    # guest_password 는 URL 쿼리가 아닌 본문으로 보낸다(서버는 둘 다 받는다).
+    def product_qna_delete(product_qna_id:, guest_password: nil, user_id: nil, login_id: nil, user_jwt: nil,
+                           supervisor: false, idempotency_key: nil)
+      request(
+        uri:     "product-qnas/#{product_qna_id}",
+        method:  :delete,
+        headers: {
+          'Idempotency-Key'  => idempotency_key.presence || SecureRandom.uuid,
+          'Bootpay-Role'     => supervisor ? 'supervisor' : 'user',
+          'Bootpay-User-JWT' => user_jwt
+        }.compact,
+        payload: {
+                   guest_password: guest_password,
+                   user_id:        user_id,
+                   login_id:       login_id
+                 }.compact
+      )
+    end
+
+    # 상품문의 답변 등록·수정 (PUT /v1/product-qnas/:id/answer) — supervisor 전용
+    # @comment_by Claude
+    # @date: 26-09-29
+    # 답변이 없으면 만들고, 있으면 내용을 바꾼다. 응답은 답변이 반영된 상품문의 객체다.
+    def product_qna_answer(product_qna_id:, content:, idempotency_key: nil)
+      request(
+        uri:     "product-qnas/#{product_qna_id}/answer",
+        method:  :put,
+        headers: {
+          'Idempotency-Key' => idempotency_key.presence || SecureRandom.uuid,
+          'Bootpay-Role'    => 'supervisor'
+        },
+        payload: {
+          content: content
+        }
+      )
+    end
+  end
+end

data/lib/bootpay_store/concern/product_review.rb

@@ -0,0 +1,145 @@
+module BootpayStore::Concern::ProductReview
+  extend ActiveSupport::Concern
+
+  included do
+    # 상품평 목록 (GET /v1/reviews)
+    # @comment_by Claude
+    # @date: 26-09-29
+    # 회원 모드: user_id·login_id·user_jwt 로 정한 회원이 쓴 상품평만 본다.
+    # supervisor: true 면 몰 전체 상품평 — 이때 user_id 는 작성 회원 필터(선택)다.
+    # 상품 상세의 공개 상품평 목록은 기존 GET /v1/products/:id/reviews 를 쓴다.
+    def reviews(page: 1, limit: 20, product_id: nil, view: nil, user_id: nil, login_id: nil, user_jwt: nil,
+                supervisor: false, idempotency_key: nil)
+      request(
+        uri:     'reviews',
+        method:  :get,
+        headers: {
+          'Idempotency-Key'  => idempotency_key.presence || SecureRandom.uuid,
+          'Bootpay-Role'     => supervisor ? 'supervisor' : 'user',
+          'Bootpay-User-JWT' => user_jwt
+        }.compact,
+        params:  {
+                   page:       page,
+                   limit:      limit,
+                   product_id: product_id,
+                   view:       view,
+                   user_id:    user_id,
+                   login_id:   login_id
+                 }.compact
+      )
+    end
+
+    # 상품평 단건 (GET /v1/reviews/:id)
+    # @comment_by Claude
+    # @date: 26-09-29
+    # 공개 상품평은 누구나, 숨김 상품평은 작성 회원 본인 또는 supervisor 만 본다.
+    def review_detail(product_review_id:, user_id: nil, login_id: nil, user_jwt: nil, supervisor: false,
+                      idempotency_key: nil)
+      request(
+        uri:     "reviews/#{product_review_id}",
+        method:  :get,
+        headers: {
+          'Idempotency-Key'  => idempotency_key.presence || SecureRandom.uuid,
+          'Bootpay-Role'     => supervisor ? 'supervisor' : 'user',
+          'Bootpay-User-JWT' => user_jwt
+        }.compact,
+        params:  {
+                   user_id:  user_id,
+                   login_id: login_id
+                 }.compact
+      )
+    end
+
+    # 상품평 작성 (POST /v1/reviews) — 회원 전용
+    # @comment_by Claude
+    # @date: 26-09-29
+    # order_id 는 회원의 구매확정 주문, product_id(·product_option_id)는 그 주문에 담긴 상품이어야 한다.
+    # images 는 사진 URL 최대 5개(문자열 또는 { url: } 해시). 파일 업로드는 지원하지 않는다.
+    def review_create(order_id:, product_id:, rating:, content:, product_option_id: nil, images: nil,
+                      user_id: nil, login_id: nil, user_jwt: nil, idempotency_key: nil)
+      request(
+        uri:     'reviews',
+        method:  :post,
+        headers: {
+          'Idempotency-Key'  => idempotency_key.presence || SecureRandom.uuid,
+          'Bootpay-Role'     => 'user',
+          'Bootpay-User-JWT' => user_jwt
+        }.compact,
+        payload: {
+                   user_id:           user_id,
+                   login_id:          login_id,
+                   order_id:          order_id,
+                   product_id:        product_id,
+                   product_option_id: product_option_id,
+                   rating:            rating,
+                   content:           content,
+                   images:            images
+                 }.compact
+      )
+    end
+
+    # 상품평 수정 (PUT /v1/reviews/:id) — 작성 회원 본인, 작성 후 7일 이내
+    # @comment_by Claude
+    # @date: 26-09-29
+    # images 는 보내면 통째로 교체한다([] 면 모두 삭제). 7일이 지나면 REVIEW_EDIT_TIME_EXPIRED.
+    def review_update(product_review_id:, rating: nil, content: nil, images: nil,
+                      user_id: nil, login_id: nil, user_jwt: nil, idempotency_key: nil)
+      request(
+        uri:     "reviews/#{product_review_id}",
+        method:  :put,
+        headers: {
+          'Idempotency-Key'  => idempotency_key.presence || SecureRandom.uuid,
+          'Bootpay-Role'     => 'user',
+          'Bootpay-User-JWT' => user_jwt
+        }.compact,
+        payload: {
+                   user_id:  user_id,
+                   login_id: login_id,
+                   rating:   rating,
+                   content:  content,
+                   images:   images
+                 }.compact
+      )
+    end
+
+    # 상품평 삭제 (DELETE /v1/reviews/:id) — 작성 회원 본인 또는 supervisor
+    # @comment_by Claude
+    # @date: 26-09-29
+    # 지급된 적립금 회수·상품 통계 차감이 함께 일어난다. reason 은 운영자 모드의 삭제 사유.
+    def review_delete(product_review_id:, reason: nil, user_id: nil, login_id: nil, user_jwt: nil,
+                      supervisor: false, idempotency_key: nil)
+      request(
+        uri:     "reviews/#{product_review_id}",
+        method:  :delete,
+        headers: {
+          'Idempotency-Key'  => idempotency_key.presence || SecureRandom.uuid,
+          'Bootpay-Role'     => supervisor ? 'supervisor' : 'user',
+          'Bootpay-User-JWT' => user_jwt
+        }.compact,
+        params:  {
+                   user_id:  user_id,
+                   login_id: login_id,
+                   reason:   reason
+                 }.compact
+      )
+    end
+
+    # 상품평 판매자 답글 등록·수정 (PUT /v1/reviews/:id/reply) — supervisor 전용
+    # @comment_by Claude
+    # @date: 26-09-29
+    # 답글이 없으면 만들고, 있으면 내용을 바꾼다(10자 이상). 응답은 답글이 반영된 상품평 객체다.
+    def review_reply(product_review_id:, content:, idempotency_key: nil)
+      request(
+        uri:     "reviews/#{product_review_id}/reply",
+        method:  :put,
+        headers: {
+          'Idempotency-Key' => idempotency_key.presence || SecureRandom.uuid,
+          'Bootpay-Role'    => 'supervisor'
+        },
+        payload: {
+          content: content
+        }
+      )
+    end
+  end
+end

data/lib/bootpay_store/concern/rest.rb

@@ -0,0 +1,139 @@
+module BootpayStore::Concern::Rest
+  extend ActiveSupport::Concern
+
+  included do
+    private
+
+    # 요청 경로에 맞는 API 기본 주소.
+    # @comment_by Claude (alfred)
+    # @date: 26-09-18
+    # 알림톡 API 는 26-09-18 부터 커머스 API(api.bootapi.com/v1)가 아니라 메시지 API(message.bootapi.com, /v1 없음)가 받는다.
+    #   경로·파라미터·응답은 그대로이고 호스트만 다르다 — 그래서 알림톡 메서드는 고치지 않고 여기서 주소만 가른다.
+    #   옛 주소(/alimtalk/*)는 410 으로 응답한다.
+    def api_base_url(uri)
+      table = uri.to_s.sub(%r{\A/}, '').start_with?('alimtalk') ? BootpayStore::RestClient::MESSAGE_API : BootpayStore::RestClient::API
+      table[@mode.to_sym]
+    end
+
+    # HTTP Request 기본 Method
+    # Comment by Gosomi
+    # Date: 2021-05-21
+    def request(method: :post, uri:, payload: {}, headers: {}, params: nil)
+      response = HTTP.headers(
+        {
+          Authorization:       @token.present? ? "Bearer #{@token}" : "Basic #{basic_authentification}",
+          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,
+        [api_base_url(uri), uri].join('/'),
+        json:   payload,
+        params: params
+      )
+      BootpayStore::Response.new(
+        response.status.to_i == 200,
+        JSON.parse(response.body.to_s, symbolize_names: true)
+      )
+    rescue Exception => e
+      BootpayStore::Response.new(
+        false,
+        message:   "부트페이 API 서버와의 통신이 실패하였습니다. 오류 메세지: #{e.message}",
+        backtrace: e.backtrace.join("\n")
+      )
+    end
+
+    # JSON 이 아닌 본문(CSV 등)을 파싱하지 않고 그대로 받는다.
+    # @comment_by Claude (alfred)
+    # @date: 26-08-27
+    # ⚠️ 공용 request 는 응답을 무조건 JSON.parse 하므로, CSV 를 돌려주는 엔드포인트
+    #    (알림톡 템플릿 내보내기 format=csv)에서는 파싱 실패가 rescue 로 흘러
+    #    **"부트페이 API 서버와의 통신이 실패하였습니다"** 라는 틀린 메시지로 보고된다.
+    #    실제로는 성공한 요청이라 그대로 두면 원인을 못 찾는다. 그래서 원문 경로를 따로 둔다.
+    # 성공 시 data 는 { body: '<원문 문자열>', content_type: '...' } 다.
+    def request_raw(uri:, method: :get, params: nil, headers: {})
+      response = HTTP.headers(
+        {
+          Authorization:       @token.present? ? "Bearer #{@token}" : "Basic #{basic_authentification}",
+          accept:              '*/*',
+          bootpay_api_version: @api_version,
+          bootpay_sdk_version: Bootpay::V2_VERSION,
+          bootpay_sdk_type:    '300'
+        }.merge!(headers).compact
+      ).send(
+        method.to_sym,
+        [api_base_url(uri), uri].join('/'),
+        params: params
+      )
+      BootpayStore::Response.new(
+        response.status.to_i == 200,
+        body:         response.body.to_s,
+        content_type: response.headers['Content-Type'].to_s
+      )
+    rescue Exception => e
+      BootpayStore::Response.new(
+        false,
+        message:   "부트페이 API 서버와의 통신이 실패하였습니다. 오류 메세지: #{e.message}",
+        backtrace: e.backtrace.join("\n")
+      )
+    end
+
+    # multipart/form-data 전송 (파일 업로드용)
+    # @comment_by Claude (alfred)
+    # @date: 26-08-14
+    # ⚠️ content_type 을 명시하지 않는다. 명시하면 HTTP.rb 가 붙이는 boundary 가 사라져 본문이 깨진다.
+    #    (Node SDK 는 인터셉터가 Content-Type 을 덮어써 본문이 null 로 전송되는 버그가 있다 — 같은 함정)
+    # 기존 request 는 json: 고정이라 손대지 않고 별도 메서드로 둔다.
+    def post_multipart(uri:, form: {}, headers: {})
+      response = HTTP.headers(
+        {
+          Authorization:       @token.present? ? "Bearer #{@token}" : "Basic #{basic_authentification}",
+          accept:              'application/json',
+          bootpay_api_version: @api_version,
+          bootpay_sdk_version: Bootpay::V2_VERSION,
+          bootpay_sdk_type:    '300'
+        }.merge!(headers).compact
+      ).post(
+        [api_base_url(uri), uri].join('/'),
+        form: form
+      )
+      BootpayStore::Response.new(
+        response.status.to_i == 200,
+        JSON.parse(response.body.to_s, symbolize_names: true)
+      )
+    rescue Exception => e
+      BootpayStore::Response.new(
+        false,
+        message:   "부트페이 API 서버와의 통신이 실패하였습니다. 오류 메세지: #{e.message}",
+        backtrace: e.backtrace.join("\n")
+      )
+    end
+
+    # multipart form 값 정규화 — 파일은 FormData::File 로, 나머지는 문자열로.
+    # 파일은 경로(String)·IO·HTTP::FormData::File 셋 다 받는다.
+    # @comment_by Claude (alfred)
+    # @date: 26-08-14
+    def multipart_file(value)
+      return value if value.is_a?(HTTP::FormData::File)
+      HTTP::FormData::File.new(value)
+    end
+
+    def multipart_value(value)
+      case value
+      when Array, Hash then value.to_json
+      when TrueClass, FalseClass then value.to_s
+      else value.to_s
+      end
+    end
+
+    # basic authenticate 추가
+    # Comment by GOSOMI
+    # @date: 2026-02-20
+    def basic_authentification
+      Base64.strict_encode64("#{@client_key}:#{@secret_key}")
+    end
+  end
+end

data/lib/bootpay_store/concern/store.rb

@@ -0,0 +1,31 @@
+module BootpayStore::Concern::Store
+  extend ActiveSupport::Concern
+
+  included do
+    # 가맹점 기본 정보를 조회한다 (/v1/store)
+    # Comment by Codex
+    # @date: 2026-02-23
+    def get_store(idempotency_key: nil)
+      request(
+        uri:     'store',
+        method:  :get,
+        headers: {
+          'Idempotency-Key' => idempotency_key.presence || SecureRandom.uuid
+        }
+      )
+    end
+
+    # 가맹점 상세 정보를 조회한다 (/v1/store/detail)
+    # Comment by Codex
+    # @date: 2026-02-23
+    def get_store_detail(idempotency_key: nil)
+      request(
+        uri:     'store/detail',
+        method:  :get,
+        headers: {
+          'Idempotency-Key' => idempotency_key.presence || SecureRandom.uuid
+        }
+      )
+    end
+  end
+end