cetustek 0.7.0 → 0.9.0

data/lib/cetustek/errors.rb

@@ -14,6 +14,26 @@ module Cetustek
   end
 
   module ResultCode
+    # Rows that are identical across the spec's result tables (7/10/17/19).
+    COMMON = {
+      'M:' => '欄位未填或格式錯誤',
+      'M0' => 'XML 格式錯誤',
+      'M1' => 'XML 格式錯誤',
+      'Invalid' => '無效 IP，請通知系統商'
+    }.freeze
+
+    # Detail-line rows, identical between Table 7 (發票) and Table 17 (折讓).
+    DETAILS = {
+      'D0' => '沒有產品明細',
+      'D0_' => '產品編號格式錯誤',
+      'D1_' => '品名未填或格式錯誤',
+      'D2_' => '數量未填或格式錯誤',
+      'D3_' => '單價未填或格式錯誤',
+      'D4_' => '單位格式錯誤',
+      'D5_' => '數量*單價，其小計整數位大於 13 位',
+      'D999' => '明細筆數最多 9999 筆'
+    }.freeze
+
     # Codes may carry a suffix naming the offending field or detail row
     # ("M:AllowanceDate", "D2_3"), so an exact miss falls back to the table key
     # without the suffix.
@@ -25,6 +45,10 @@ module Cetustek
     def self.check!(code, messages, success:)
       return code if code == success
 
+      raise!(code, messages)
+    end
+
+    def self.raise!(code, messages)
       raise ResultError.new(code, describe(code, messages))
     end
   end

data/lib/cetustek/models/allowance_data.rb

@@ -10,6 +10,8 @@ module Cetustek
       # 折讓單稅別只有應稅/零稅率/免稅，發票的 4 (特種稅率)、5 (經海關出口)
       # 與 9 (混合) 在折讓單無效。
       TAX_TYPES = [TaxType::TAXABLE, TaxType::ZERO_RATE, TaxType::TAX_FREE].freeze
+      MAX_REASON_LENGTH = 20
+      ROUND_NUMS = (0..7).freeze
 
       attr_reader :allowance_number, :allowance_date, :invoice_number,
                   :invoice_year, :buyer_address, :buyer_email, :tax_type,
@@ -23,13 +25,54 @@ module Cetustek
         @buyer_address = attributes[:buyer_address]
         @buyer_email = attributes[:buyer_email]
         @tax_type = attributes[:tax_type] || TaxType::TAXABLE
-        unless TAX_TYPES.include?(@tax_type.to_i)
-          raise ArgumentError, "tax_type must be 1 (應稅), 2 (零稅率) or 3 (免稅), got #{@tax_type.inspect}"
-        end
-
         @reason = attributes[:reason]
         @round_num = attributes[:round_num] # optional 金額計算位數
         @items = attributes[:items] || []
+        validate!
+      end
+
+      private
+
+      def validate!
+        missing = { allowance_number: @allowance_number, invoice_number: @invoice_number,
+                    invoice_year: @invoice_year, reason: @reason }.select { |_k, v| blank?(v) }.keys
+        raise ArgumentError, "#{missing.join(', ')} required" if missing.any?
+
+        validate_allowance_date!
+        validate_tax_type!
+        validate_reason!
+        validate_round_num!
+        raise ArgumentError, 'items must not be empty (沒有產品明細)' if @items.empty?
+      end
+
+      def validate_allowance_date!
+        raise ArgumentError, 'allowance_date is required' if @allowance_date.nil?
+        return if @allowance_date.respond_to?(:strftime)
+
+        raise ArgumentError, "allowance_date must be a Date or Time, got #{@allowance_date.class}"
+      end
+
+      def validate_tax_type!
+        return if TAX_TYPES.include?(@tax_type.to_i)
+
+        raise ArgumentError, "tax_type must be 1 (應稅), 2 (零稅率) or 3 (免稅), got #{@tax_type.inspect}"
+      end
+
+      def validate_reason!
+        return if @reason.to_s.length <= MAX_REASON_LENGTH
+
+        raise ArgumentError, "reason must not exceed #{MAX_REASON_LENGTH} characters"
+      end
+
+      def validate_round_num!
+        return if @round_num.nil? || ROUND_NUMS.include?(@round_num.to_i)
+
+        raise ArgumentError, "round_num must be between #{ROUND_NUMS.first} and #{ROUND_NUMS.last}, " \
+                             "got #{@round_num.inspect}"
+      end
+
+      def blank?(value)
+        value.nil? || value.to_s.strip.empty?
       end
     end
   end

data/lib/cetustek/models/invoice_data.rb

@@ -1,14 +1,26 @@
 # frozen_string_literal: true
 
 module Cetustek
-  # TaxType (稅別) codes accepted by CreateInvoiceV3 (spec V4.16, Table 1).
+  # TaxType (稅別) codes accepted by CreateInvoiceV3, spec AVM-26-03 Table 1.
   module TaxType
     TAXABLE = 1            # 應稅
     ZERO_RATE = 2          # 零稅率(非經海關出口)
     TAX_FREE = 3           # 免稅
     SPECIAL = 4            # 應稅(特種稅率) — requires TaxRate
     ZERO_RATE_CUSTOMS = 5  # 零稅率(經海關出口)
-    MIXED = 9              # 混合(應稅、零稅率與免稅，限收銀機類型發票)
+    MIXED = 9              # 混合(應稅、零稅率與免稅)
+  end
+
+  # CarrierType (載具類別) codes named in spec AVM-26-03 Table 1. The field is
+  # 6 chars and 依電子整合平台核發填入, so any other code is accepted as-is.
+  module CarrierType
+    MOBILE_BARCODE = '3J0002' # 手機條碼，以「/」起始
+    CITIZEN_CERT = 'CQ0001'   # 自然人憑證條碼，2 碼大寫字母加 14 碼數字
+    CETUSTEK_CARD = 'EJ0011'  # 鯨躍發票卡
+
+    # These carriers 「無顯碼隱碼區分」, so CarrierId1 and CarrierId2 hold the
+    # same value. Member carriers (e.g. 鯨躍發票卡) do carry distinct codes.
+    WITHOUT_HIDDEN_CODE = [MOBILE_BARCODE, CITIZEN_CERT].freeze
   end
 
   # PayWay (付款方式) codes for CreateInvoiceV3, spec AVM-26-03 Table 4.
@@ -44,14 +56,32 @@ module Cetustek
   end
 
   module Models
+    # Request data for CreateInvoiceV3 (開立發票), spec AVM-26-03 Table 1/2.
+    # Rules the spec fixes in print are enforced here; anything needing an
+    # external lookup (捐贈碼、手機條碼是否存在) is left to the caller.
     class InvoiceData
       DEFAULT_TAX_RATE = 0.05
-      DEFAULT_INVOICE_TYPE = '07' # 07: 一般稅額, 08: 特種稅額
+      DEFAULT_INVOICE_TYPE = '07'  # 一般稅額電子發票
+      SPECIAL_INVOICE_TYPE = '08'  # 特種稅額電子發票
+      # Json 回傳才拿得到平台配發的發票日期時間；Intertemporal 回開會讓本機日期失準。
+      DEFAULT_RTN_MSG = 'Json'
+      MAX_ITEMS = 9999
+      MAX_REMARK_LENGTH = 200
+      ROUND_NUMS = (0..7).freeze
+      TAX_TYPES = [TaxType::TAXABLE, TaxType::ZERO_RATE, TaxType::TAX_FREE,
+                   TaxType::SPECIAL, TaxType::ZERO_RATE_CUSTOMS, TaxType::MIXED].freeze
+      ZERO_RATE_TAX_TYPES = [TaxType::ZERO_RATE, TaxType::ZERO_RATE_CUSTOMS].freeze
+      DONATE_MARKS = [DonateMark::CARRIER, DonateMark::DONATE, DonateMark::PAPER].freeze
 
       attr_reader :order_id, :order_date, :buyer_identifier, :buyer_name,
-                  :buyer_email, :donate_mark, :carrier_type, :carrier_id,
-                  :carrier_id2, :npo_ban, :items, :payment_type,
-                  :tax_type, :tax_rate, :invoice_type, :hastax
+                  :buyer_email, :buyer_address, :buyer_person_in_charge,
+                  :buyer_telephone, :buyer_facsimile, :buyer_customer_number,
+                  :donate_mark, :carrier_type, :carrier_id1, :carrier_id2,
+                  :npo_ban, :items, :payment_type, :tax_type, :tax_rate,
+                  :zero_reason, :invoice_type, :hastax, :remark, :round_num,
+                  :mail_send, :rtn_msg
+
+      alias carrier_id carrier_id1
 
       def initialize(attributes = {})
         @order_id = attributes[:order_id]
@@ -59,27 +89,153 @@ module Cetustek
         @buyer_identifier = attributes[:buyer_identifier]
         @buyer_name = attributes[:buyer_name]
         @buyer_email = attributes[:buyer_email]
+        @buyer_address = attributes[:buyer_address]
+        @buyer_person_in_charge = attributes[:buyer_person_in_charge]
+        @buyer_telephone = attributes[:buyer_telephone]
+        @buyer_facsimile = attributes[:buyer_facsimile]
+        @buyer_customer_number = attributes[:buyer_customer_number]
         @donate_mark = attributes[:donate_mark]
         @carrier_type = attributes[:carrier_type]
-        @carrier_id = attributes[:carrier_id]
-        @carrier_id2 = attributes[:carrier_id2]
+        @carrier_id1 = attributes[:carrier_id1] || attributes[:carrier_id]
+        @carrier_id2 = attributes[:carrier_id2] || mirrored_carrier_id2
         @npo_ban = attributes[:npo_ban]
         @items = attributes[:items] || []
         @payment_type = attributes[:payment_type]
         @tax_type = attributes[:tax_type] || TaxType::TAXABLE
-        @tax_rate = attributes.fetch(:tax_rate, DEFAULT_TAX_RATE)
+        # 特種稅率是營業性質決定的，不能沿用 5% 預設值。
+        @tax_rate = attributes.fetch(:tax_rate) { special_tax? ? nil : DEFAULT_TAX_RATE }
+        @zero_reason = attributes[:zero_reason]
         @invoice_type = attributes[:invoice_type] || DEFAULT_INVOICE_TYPE
         # hastax: 0 = item prices are tax-exclusive, 1 = tax-inclusive.
         # Comes from the order (e.g. tax-free purchases), not a fixed value.
         @hastax = attributes.fetch(:hastax, 1)
+        @remark = attributes[:remark]
+        @round_num = attributes[:round_num]
+        @mail_send = attributes[:mail_send]
+        @rtn_msg = attributes.fetch(:rtn_msg, DEFAULT_RTN_MSG)
+        validate!
       end
 
-      # 混合稅率發票 (限收銀機)：每筆明細需標註 DType。
+      # 混合稅率發票：每筆明細需標註 DType。
       def mixed_tax?
         @tax_type.to_i == TaxType::MIXED
       end
+
+      # 特種稅額發票：TaxRate 必填，InvoiceType 必須為 08。
+      def special_tax?
+        @tax_type.to_i == TaxType::SPECIAL
+      end
+
+      private
+
+      # 只有無顯碼隱碼區分的載具能自動補 CarrierId2；會員載具兩碼不同，猜了就是送錯。
+      def mirrored_carrier_id2
+        @carrier_id1 if CarrierType::WITHOUT_HIDDEN_CODE.include?(@carrier_type.to_s)
+      end
+
+      def validate!
+        raise ArgumentError, 'order_id is required' if blank?(@order_id)
+
+        validate_order_date!
+        validate_items!
+        validate_donate_mark!
+        validate_pay_way!
+        validate_tax!
+        validate_remark!
+        validate_round_num!
+      end
+
+      def validate_order_date!
+        raise ArgumentError, 'order_date is required' if @order_date.nil?
+        return if @order_date.respond_to?(:strftime)
+
+        raise ArgumentError, "order_date must be a Date or Time, got #{@order_date.class}"
+      end
+
+      def validate_items!
+        raise ArgumentError, 'items must not be empty (沒有產品明細)' if @items.empty?
+        raise ArgumentError, "items must not exceed #{MAX_ITEMS} lines" if @items.size > MAX_ITEMS
+      end
+
+      def validate_donate_mark!
+        raise ArgumentError, 'donate_mark is required (0 載具, 1 捐贈, 2 紙本)' if blank?(@donate_mark)
+
+        unless DONATE_MARKS.include?(@donate_mark.to_i)
+          raise ArgumentError, "donate_mark must be 0 (載具), 1 (捐贈) or 2 (紙本), got #{@donate_mark.inspect}"
+        end
+
+        case @donate_mark.to_i
+        when DonateMark::CARRIER then validate_carrier!
+        when DonateMark::DONATE then validate_npo_ban!
+        end
+
+        return if @mail_send.nil? || @donate_mark.to_i == DonateMark::CARRIER
+
+        raise ArgumentError, 'mail_send may only be used when donate_mark is 0 (載具)'
+      end
+
+      # CarrierType is left out of the required set on purpose: 鯨躍發票卡
+      # 「載具類別可為空或填 EJ0011」, and a blank value is how the platform is
+      # told to use it.
+      def validate_carrier!
+        missing = { buyer_email: @buyer_email, carrier_id1: @carrier_id1,
+                    carrier_id2: @carrier_id2 }.select { |_name, value| blank?(value) }.keys
+        return if missing.empty?
+
+        raise ArgumentError, "#{missing.join(', ')} required when donate_mark is 0 (載具)" \
+                             "#{'; 此載具有顯碼與隱碼之分，請分別填入' if missing == [:carrier_id2]}"
+      end
+
+      def validate_npo_ban!
+        return if @npo_ban.to_s.match?(/\A\d{3,7}\z/)
+
+        raise ArgumentError, "npo_ban must be a 3-7 digit 捐贈碼 when donate_mark is 1 (捐贈), got #{@npo_ban.inspect}"
+      end
+
+      def validate_pay_way!
+        raise ArgumentError, 'payment_type is required (see Cetustek::PayWay)' if blank?(@payment_type)
+      end
+
+      def validate_tax!
+        unless TAX_TYPES.include?(@tax_type.to_i)
+          raise ArgumentError, "tax_type must be one of #{TAX_TYPES.join(', ')}, got #{@tax_type.inspect}"
+        end
+
+        validate_zero_reason!
+        return unless special_tax?
+
+        raise ArgumentError, 'tax_rate is required when tax_type is 4 (特種稅率)' if blank?(@tax_rate)
+        return if @invoice_type.to_s == SPECIAL_INVOICE_TYPE
+
+        raise ArgumentError, "invoice_type must be '08' (特種稅額) when tax_type is 4, got #{@invoice_type.inspect}"
+      end
+
+      def validate_zero_reason!
+        return if @zero_reason.nil? || ZERO_RATE_TAX_TYPES.include?(@tax_type.to_i)
+
+        raise ArgumentError, 'zero_reason may only be used when tax_type is 2 or 5 (零稅率)'
+      end
+
+      def validate_remark!
+        return if @remark.nil? || @remark.to_s.length <= MAX_REMARK_LENGTH
+
+        raise ArgumentError, "remark must not exceed #{MAX_REMARK_LENGTH} characters"
+      end
+
+      def validate_round_num!
+        return if @round_num.nil? || ROUND_NUMS.include?(@round_num.to_i)
+
+        raise ArgumentError, "round_num must be between #{ROUND_NUMS.first} and #{ROUND_NUMS.last}, " \
+                             "got #{@round_num.inspect}"
+      end
+
+      def blank?(value)
+        value.nil? || value.to_s.strip.empty?
+      end
     end
 
+    # A single 明細 row, spec AVM-26-03 Table 2 (發票) / Table 16 (折讓).
+    # 品名代號、品名、數量、單價 are 必填; 單位 is not.
     class InvoiceItem
       # Per-item 稅別註記 (DType) used for mixed-tax invoices (TaxType == 9).
       DTYPE_MAP = {
@@ -87,6 +243,7 @@ module Cetustek
         zero_rate: 'TZ', # 零稅率商品
         tax_free: 'TN'   # 免稅商品
       }.freeze
+      REQUIRED = %i[code name quantity unit_price].freeze
 
       attr_reader :code, :name, :quantity, :unit_price, :tax_type, :unit
 
@@ -97,6 +254,7 @@ module Cetustek
         @unit_price = attributes[:unit_price]
         @unit = attributes[:unit]
         @tax_type = attributes[:tax_type] || :taxable
+        validate!
       end
 
       # Returns the DType code: '', 'TZ' or 'TN'.
@@ -104,6 +262,19 @@ module Cetustek
       def d_type
         DTYPE_MAP.fetch(@tax_type) { @tax_type.to_s }
       end
+
+      private
+
+      def validate!
+        missing = REQUIRED.select { |name| blank?(public_send(name)) }
+        return if missing.empty?
+
+        raise ArgumentError, "item #{missing.join(', ')} required (品名代號、品名、數量、單價皆必填)"
+      end
+
+      def blank?(value)
+        value.nil? || value.to_s.strip.empty?
+      end
     end
   end
 end

data/lib/cetustek/queries.rb

@@ -3,21 +3,8 @@
 require 'ox'
 
 module Cetustek
-  # Read-only SOAP queries. Each returns the raw Savon response, mirroring
-  # QueryInvoiceByOrderId. Spec AVM-26-03 §2.4 / §2.6 / §2.11.
-  module Queries
-    def soap_client
-      Savon.client(wsdl: Cetustek.config.url, open_timeout: 300, read_timeout: 300)
-    end
-
-    def source
-      Cetustek.config.site_id + Cetustek.config.password
-    end
-
-    def rentid
-      Cetustek.config.username
-    end
-  end
+  # @deprecated use Cetustek::Soap. Kept so `extend Queries` keeps working.
+  Queries = Soap
 
   # 2.4 QueryInvoice 查詢發票資訊 (by invoice number + year)
   class QueryInvoice
@@ -68,14 +55,16 @@ module Cetustek
 
     # Same query, with the returned XML parsed into a Hash of snake_case keys
     # plus a :details array. Values are the raw strings from the XML; returns
-    # nil when the allowance number is unknown.
+    # nil when the platform answers with nothing at all.
     def self.find(allowance_number)
-      parse(query(allowance_number).body[:query_allowance_response][:return])
+      parse(soap_return(query(allowance_number), :query_allowance))
     end
 
     def self.parse(xml)
       body = xml.to_s.strip
-      return nil if body.empty? || body == 'nodata'
+      return nil if body.empty?
+      # §2.11 只描述成功時的 XML；非 XML 的回覆是代碼字串，原樣拋給呼叫端。
+      ResultCode.raise!(body, ResultCode::COMMON) unless body.start_with?('<')
 
       root = Ox.parse(body)
       root = root.root if root.is_a?(Ox::Document)

data/lib/cetustek/query_invoice_by_order_id.rb

@@ -1,19 +1,12 @@
+# frozen_string_literal: true
+
 module Cetustek
+  # 2.5 QueryInvoicebyOrderid 以訂單編號查詢發票資訊
   class QueryInvoiceByOrderId
-    def self.query(order_id)
-      url = Cetustek.config.url
-      client = Savon.client(
-        wsdl: url,
-        open_timeout: 300,
-        read_timeout: 300
-      )
+    extend Soap
 
-      @response = client.call(:query_invoice_by_orderid, message:
-        {
-          orderid: order_id,
-          source: Cetustek.config.site_id + Cetustek.config.password,
-          rentid: Cetustek.config.username
-        })
+    def self.query(order_id)
+      soap_call(:query_invoice_by_orderid, orderid: order_id)
     end
   end
 end

data/lib/cetustek/services/invoice_xml_builder.rb

@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-require 'ox'
-require 'cgi'
-
 module Cetustek
   module Services
     class InvoiceXmlBuilder
@@ -11,62 +8,47 @@ module Cetustek
       end
 
       def build
-        doc = Ox::Document.new
-        doc << create_xml_instruct
-        doc << create_invoice_element
-
-        Ox.dump(doc).force_encoding('UTF-8')
+        Xml.document('Invoice') do |invoice|
+          add_basic_info(invoice)
+          add_buyer_info(invoice)
+          add_invoice_type_info(invoice)
+          add_details(invoice)
+        end
       end
 
       private
 
-      def create_xml_instruct
-        instruct = Ox::Instruct.new(:xml)
-        instruct[:version] = '1.0'
-        instruct[:encoding] = 'UTF-8'
-        instruct
-      end
-
-      # Builds a raw XML element with the value HTML-escaped, so that special
-      # characters (&, <, >, ", ') in any dynamic field cannot break the XML
-      # or be used for injection.
-      def raw_tag(name, value)
-        Ox::Raw.new("<#{name}>#{CGI.escapeHTML(value.to_s)}</#{name}>")
-      end
-
-      def create_invoice_element
-        invoice = Ox::Element.new('Invoice')
-        invoice[:XSDVersion] = '2.8'
-
-        add_basic_info(invoice)
-        add_buyer_info(invoice)
-        add_invoice_type_info(invoice)
-        add_details(invoice)
-
-        invoice
-      end
-
       def add_basic_info(invoice)
-        invoice << raw_tag('OrderId', @data.order_id)
-        invoice << raw_tag('OrderDate', @data.order_date.strftime('%Y/%m/%d'))
+        Xml.append(invoice, 'OrderId', @data.order_id)
+        Xml.append(invoice, 'OrderDate', @data.order_date.strftime('%Y/%m/%d'))
       end
 
       def add_buyer_info(invoice)
-        invoice << raw_tag('BuyerIdentifier', @data.buyer_identifier)
-        invoice << raw_tag('BuyerName', @data.buyer_name)
-        invoice << raw_tag('BuyerEmailAddress', @data.buyer_email)
+        Xml.append(invoice, 'BuyerIdentifier', @data.buyer_identifier)
+        Xml.append(invoice, 'BuyerName', @data.buyer_name)
+        Xml.append(invoice, 'BuyerAddress', @data.buyer_address)
+        Xml.append(invoice, 'BuyerPersonInCharge', @data.buyer_person_in_charge)
+        Xml.append(invoice, 'BuyerTelephoneNumber', @data.buyer_telephone)
+        Xml.append(invoice, 'BuyerFacsimileNumber', @data.buyer_facsimile)
+        Xml.append(invoice, 'BuyerEmailAddress', @data.buyer_email)
+        Xml.append(invoice, 'BuyerCustomerNumber', @data.buyer_customer_number)
       end
 
       def add_invoice_type_info(invoice)
-        invoice << raw_tag('DonateMark', @data.donate_mark)
-        invoice << raw_tag('InvoiceType', @data.invoice_type)
-        invoice << raw_tag('CarrierType', @data.carrier_type)
-        invoice << raw_tag('CarrierId1', @data.carrier_id)
-        invoice << raw_tag('CarrierId2', @data.carrier_id2)
-        invoice << raw_tag('NPOBAN', @data.npo_ban)
-        invoice << raw_tag('TaxType', @data.tax_type)
-        invoice << raw_tag('TaxRate', @data.tax_rate)
-        invoice << raw_tag('PayWay', @data.payment_type)
+        Xml.append(invoice, 'DonateMark', @data.donate_mark)
+        Xml.append(invoice, 'InvoiceType', @data.invoice_type)
+        Xml.append(invoice, 'CarrierType', @data.carrier_type)
+        Xml.append(invoice, 'CarrierId1', @data.carrier_id1)
+        Xml.append(invoice, 'CarrierId2', @data.carrier_id2)
+        Xml.append(invoice, 'NPOBAN', @data.npo_ban)
+        Xml.append(invoice, 'TaxType', @data.tax_type)
+        Xml.append(invoice, 'TaxRate', @data.tax_rate)
+        Xml.append(invoice, 'ZeroReason', @data.zero_reason, skip_nil: true)
+        Xml.append(invoice, 'PayWay', @data.payment_type)
+        Xml.append(invoice, 'Remark', @data.remark)
+        Xml.append(invoice, 'MailSend', @data.mail_send, skip_nil: true)
+        Xml.append(invoice, 'RoundNum', @data.round_num, skip_nil: true)
+        Xml.append(invoice, 'RtnMsg', @data.rtn_msg, skip_nil: true)
       end
 
       def add_details(invoice)
@@ -80,21 +62,16 @@ module Cetustek
 
       def create_product_item(item)
         product = Ox::Element.new('ProductItem')
-        product << raw_tag('ProductionCode', item.code)
-        product << raw_tag('Description', item.name)
-        product << raw_tag('Quantity', item.quantity)
-        product << raw_tag('UnitPrice', item.unit_price)
-        add_dtype(product, item.d_type)
+        Xml.append(product, 'ProductionCode', item.code)
+        Xml.append(product, 'Description', item.name)
+        Xml.append(product, 'Quantity', item.quantity)
+        Xml.append(product, 'Unit', item.unit)
+        Xml.append(product, 'UnitPrice', item.unit_price)
+        # DType (稅別註記) is required on every detail line only for mixed-tax
+        # invoices (TaxType == 9).
+        Xml.append(product, 'DType', item.d_type) if @data.mixed_tax?
         product
       end
-
-      # DType (稅別註記) is required on every detail line only for mixed-tax
-      # invoices (TaxType == 9).
-      def add_dtype(product, value)
-        return unless @data.mixed_tax?
-
-        product << raw_tag('DType', value)
-      end
     end
   end
 end

data/lib/cetustek/services/response_handler.rb

@@ -1,11 +1,30 @@
 # frozen_string_literal: true
 
-require 'logger'
+require 'json'
 
 module Cetustek
   module Services
+    # Parses the CreateInvoiceV3 return value. Three shapes are possible:
+    # the Table 8 JSON object (RtnMsg=Json), the 15-character
+    # "發票號碼;隨機碼" string, or a bare Table 7 result code.
     class ResponseHandler
-      class InvalidResponseError < StandardError; end
+      # @deprecated rescue Cetustek::ResultError instead. Kept as an alias of
+      #   the class actually raised so pre-0.7 rescues keep matching.
+      InvalidResponseError = ResultError
+
+      SUCCESS_LENGTH = 15 # 發票號碼 10 碼 + ';' + 隨機碼 4 碼
+
+      # Spec AVM-26-03 Table 7.
+      RESULT_MESSAGES = ResultCode::COMMON.merge(ResultCode::DETAILS).merge(
+        'S1' => '資料庫發生錯誤',
+        'S2' => '訂單日期超過開立日期',
+        'S3' => '未在申報期內',
+        'S4' => '未取得發票號碼',
+        'S5' => '發票號碼已使用完畢',
+        'S6' => '超過租賃張數限制',
+        'S7' => '訂單號碼已存在，若需重開請先作廢原發票號碼',
+        'S8' => '開立的總金額為負值'
+      ).freeze
 
       def initialize(response, invoice_data, xml = nil)
         @response = response
@@ -14,24 +33,67 @@ module Cetustek
       end
 
       def process
-        response_body = @response.body[:create_invoice_v3_response][:return]
-        number, random_number = response_body.split(';')
+        body = @response.body[:create_invoice_v3_response][:return].to_s.strip
+        json = parse_json(body)
 
-        unless random_number
-          log_error
-          raise InvalidResponseError, "Invalid response: #{response_body}"
-        end
+        return success(json_result(json)) if json && json['msg'] == 'Success'
+        return success(string_result(body)) if json.nil? && success_string?(body)
 
-        { number: number, random_number: random_number }
+        fail_with(json ? json['msg'].to_s : body)
       end
 
       private
 
-      def log_error
-        return unless defined?(Rails) && @xml
+      # M1 (XML 格式錯誤) 與 Invalid 不會回傳 JSON，所以形狀要靠內容判斷。
+      def parse_json(body)
+        return nil unless body.start_with?('{')
+
+        JSON.parse(body)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def success_string?(body)
+        body.length == SUCCESS_LENGTH && body.include?(';')
+      end
+
+      def json_result(json)
+        {
+          number: json['invnumber'],
+          random_number: json['random'],
+          date: json['invdate'],
+          time: json['invtime'],
+          sale_amount: json['saleamt'],
+          zero_amount: json['zeroamt'],
+          free_amount: json['freeamt'],
+          tax_amount: json['taxamt'],
+          total_amount: json['totalamt'],
+          carrier_url: json['ctkurl']
+        }
+      end
+
+      def string_result(body)
+        number, random_number = body.split(';')
+        { number: number, random_number: random_number }
+      end
+
+      def success(result)
+        logger&.info("CreateInvoiceV3 #{order_id} #{result[:number]}")
+        result
+      end
+
+      def fail_with(code)
+        logger&.error("CreateInvoiceV3 #{order_id} #{code}")
+        logger&.debug(@xml) if @xml
+        ResultCode.raise!(code, RESULT_MESSAGES)
+      end
+
+      def logger
+        Cetustek.config.logger
+      end
 
-        logger = Logger.new(Rails.root.join('log/invoice_xml.log'))
-        logger.debug("#{@invoice_data.order_id} - #{@xml.force_encoding('UTF-8')}")
+      def order_id
+        @invoice_data.order_id
       end
     end
   end