cetustek 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: edd228bea5d7cd37feceb6be6f790272b6bd66c8638b70518ea13d8a23454dcb
-  data.tar.gz: a365620162f118e193b9ddaa1caf50e335e43bac777831cfcff5c2b7322aff3e
+  metadata.gz: 98c3af7dadac0df75cb3fc24f02e124765716e1856034ed120cead8e2f2ce1a5
+  data.tar.gz: 7d0a29575e2b24e786371b989da8107437eeb7d319bbf9514a83db6e7912fc79
 SHA512:
-  metadata.gz: 7849c00fa5e89b28fb010dc4e71061b464a06aa9ea95d8213d135c5dcf031a80fe693fa79912c96bcef6d6f7c2e9a2dc0db9e34be516cc50ab6b62f433221b1f
-  data.tar.gz: 94041a6cc510de760b50799e7b8aa8d23159da26e93a1b0312c3f2be28decd51b925504ce416a9ac48ea8c04dc412e463437dcc69a7dcff020c50b9fbc54a482
+  metadata.gz: 6243d83ecc59c97b961ec8185d46967b8e04148b752e2a810c519e238e53a9d8450944c10214cd320f465a1137e1d97c63bd1d8bf547bd59b16d6deace421916
+  data.tar.gz: 9224b032dcb1eae4facaa3278b0c732daf79fbbcfe00ea17532a27b5bf989ba862711427021f2cd5a459abdce171ff0199931b2f99531cb3baa9c406457e3be4

data/CHANGELOG.md

@@ -5,6 +5,38 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.0] - 2026-08-04
+
+### Added
+- `Cetustek.config.logger`(預設 `nil`,即這個 gem 不寫任何東西)。只記訂單編號、
+  發票號碼與結果代碼,失敗時才以 debug 記下請求 XML
+- 開立發票補上規格 Table 1/2 缺漏的欄位:明細的 `Unit`,主檔的 `Remark`、`ZeroReason`、
+  `RoundNum`、`MailSend`、`RtnMsg`,以及 `BuyerAddress`/`BuyerPersonInCharge`/
+  `BuyerTelephoneNumber`/`BuyerFacsimileNumber`/`BuyerCustomerNumber`
+- `InvoiceData` 依規格驗證必填與條件欄位(`order_id`/`order_date`/`items`/
+  `donate_mark`/`payment_type` 必填;`donate_mark=0` 需 email 與載具三欄;
+  `donate_mark=1` 需 3-7 碼 `npo_ban`;`tax_type=4` 需明確 `tax_rate` 且
+  `invoice_type` 為 `08`),違反時建構就丟 `ArgumentError`
+- `carrier_id1` 成為顯碼的正式名稱(`carrier_id` 保留為別名),`carrier_id2` 未填時
+  自動鏡射顯碼 —— 手機條碼與自然人憑證沒有顯隱碼之分
+- `CancelInvoice` 支援 `remark:`(作廢原因,預設 `'退貨'`)與
+  `return_tax_document_number:`(專案作廢核准文號,超過申報期間作廢時需要)
+
+### Changed
+- **Breaking:** 開立發票預設帶 `<RtnMsg>Json</RtnMsg>`,`CreateInvoice#execute` 除了
+  既有的 `:number`/`:random_number` 另外回傳 `:date`/`:time` 與各項金額。發票日期改以
+  API 回傳為準,不再用本機 `Time.zone.today` 推測(`Intertemporal` 回開會讓本機日期錯誤)。
+  傳 `rtn_msg: nil` 可退回舊的 15 碼字串模式
+- **Breaking:** 開立與作廢發票失敗一律丟 `Cetustek::ResultError`,帶原始代碼與 Table 7 /
+  Table 10 的中文說明。`ResponseHandler::InvalidResponseError` 降為 `ResultError` 的子類
+  (deprecated,既有 rescue 仍可運作);`CancelInvoice` 不再靜默回傳 nil
+- **Breaking:** `CancelInvoice.new(invoice_number, invoice_year, remark:)` 改收明確參數,
+  不再接受 invoice 物件,也不再回寫 `canceled: true`
+- **Breaking:** 移除 `CreateInvoice` 的 `invoice_info` 回寫與兩處 `Rails.root/log/*` 寫檔
+  (原本會把含買受人 email 的整包回應寫進固定路徑);`InvoiceService.new(xml, hastax)`
+  不再接受 `order_id`
+- 成功判斷改用規格寫的 15 碼規則(`發票號碼;隨機碼`),而非「字串含分號」
+
 ## [0.7.0] - 2026-08-04
 
 ### Added

data/README.md

@@ -4,16 +4,18 @@
 [![RSpec Tests](https://github.com/7a6163/cetustek/actions/workflows/rspec.yml/badge.svg)](https://github.com/7a6163/cetustek/actions/workflows/rspec.yml)
 [![codecov](https://codecov.io/gh/7a6163/cetustek/graph/badge.svg?token=N951Y9SE15)](https://codecov.io/gh/7a6163/cetustek)
 
-Cetustek is a Ruby gem designed for handling electronic invoice operations, including invoice cancellation. It communicates with the e-invoice system through SOAP Web Services.
+Cetustek is a Ruby wrapper for the 鯨躍 Cetustek e-invoice API (虛擬多通路,
+spec AVM-26-03), covering 電子發票 and 折讓單 over SOAP Web Services.
 
 ## Features
 
-- Electronic invoice cancellation
-- XML format generation
-- SOAP Web Services integration
-- Environment-specific configuration (sandbox/production)
-- Service-oriented architecture
-- Robust error handling
+- 開立發票 (CreateInvoiceV3) with 載具/捐贈/紙本, 零稅率, 混合稅率 and 特種稅額 support
+- 作廢發票 (CancelInvoice), including the 專案作廢核准文號 for late cancellations
+- 折讓單: 開立 (CreateAllowance), 作廢 (CancelAllowance), 查詢 (QueryAllowance)
+- Queries by invoice number or order id, plus 手機條碼 validation
+- Validation of the rules the spec fixes in print, before anything is sent
+- Result codes raised as `Cetustek::ResultError` with the documented reason
+- Environment-specific configuration (sandbox/production) and opt-in logging
 
 ## Installation
 
@@ -43,6 +45,11 @@ Cetustek.configure do |config|
   config.site_id = ENV['CETUSTEK_SITE_ID']
   config.username = ENV['CETUSTEK_USERNAME']
   config.password = ENV['CETUSTEK_PASSWORD']
+
+  # Optional. Defaults to nil, i.e. this gem writes nothing anywhere.
+  # Only the order id, invoice number and result code are logged (never the
+  # response body); the request XML is logged at debug level on failure.
+  config.logger = Rails.logger
 end
 ```
 
@@ -58,22 +65,48 @@ invoice_data = Cetustek::Models::InvoiceData.new(
   buyer_identifier: invoice.receipt,
   buyer_name: invoice.name,
   buyer_email: invoice.email,
-  donate_mark: 0,
-  payment_type: 2,
+  donate_mark: Cetustek::DonateMark::CARRIER,
+  carrier_type: '3J0002',        # 手機條碼
+  carrier_id: invoice.barcode,   # CarrierId2 is mirrored automatically
+  payment_type: Cetustek::PayWay::ATM,
   items: invoice.items.map { |item|
     Cetustek::Models::InvoiceItem.new(
       code: item.sku,
       name: item.name,
       quantity: item.quantity,
+      unit: item.unit,
       unit_price: item.price
     )
   }
 )
 
 result = Cetustek::CreateInvoice.new(invoice_data).execute
-# => { number: "GT68514542", random_number: "9654" }
+# => { number: "WB02100001", random_number: "3690",
+#      date: "2026/02/10", time: "11:19:57",
+#      sale_amount: 666, zero_amount: 0, free_amount: 0,
+#      tax_amount: 0, total_amount: 666, carrier_url: "..." }
 ```
 
+Always use the returned `:date`/`:time` as the invoice date. The platform's
+`Intertemporal` default issues invoices dated in the previous filing period on
+the 1st–2nd of a month, so the local date can be wrong.
+Persisting the result is the caller's job — this gem writes to no database.
+
+`InvoiceData.new` raises `ArgumentError` for the rules the spec fixes in print,
+so a guaranteed rejection never leaves your process:
+
+- `order_id`, `order_date` (a `Date`/`Time`), `items`, `donate_mark` and `payment_type` are required
+- `donate_mark: 0` (載具) requires `buyer_email`, `carrier_type` and `carrier_id`
+- `donate_mark: 1` (捐贈) requires a 3–7 digit `npo_ban`
+- `tax_type: 4` (特種稅率) requires an explicit `tax_rate` and `invoice_type: '08'`
+
+Anything needing an external lookup (是否為有效手機條碼、捐贈碼是否存在) is left
+to the caller — see `Cetustek::PhoneBarcode` below.
+
+Any result code other than a successful issue raises `Cetustek::ResultError`,
+whose `#code` is the raw Table 7 code and whose message carries the documented
+reason (`S7 - 訂單號碼已存在，若需重開請先作廢原發票號碼`, `D3_2 - 單價未填或格式錯誤`, …).
+
 ### Tax types (稅別)
 
 `InvoiceData` defaults to taxable (`TaxType` 1) with a tax rate of `0.05` and a
@@ -149,14 +182,21 @@ items — use a negative `unit_price` for a discount:
 Cetustek::Models::InvoiceItem.new(code: 'DISCOUNT', name: '折抵', quantity: 1, unit_price: -30)
 ```
 
-### Cancel an Invoice
+### Cancel an Invoice (作廢發票確認)
 
 ```ruby
-# `invoice` responds to #number and #created_at; on success (return code "C0")
-# it is updated with canceled: true.
-Cetustek::CancelInvoice.new(invoice).execute
+Cetustek::CancelInvoice.new('AB12345678', 2024).execute                    # => "C0"
+Cetustek::CancelInvoice.new('AB12345678', 2024, remark: '明細錯誤').execute # 作廢原因，預設 '退貨'
+
+# 超過申報期間才需要專案作廢核准文號 (否則會收到 C3)
+Cetustek::CancelInvoice.new('AB12345678', 2024, return_tax_document_number: '65327645').execute
 ```
 
+Uploading is not the end of it: the cancellation still has to be confirmed
+manually on the 鯨躍 platform before the invoice counts as void. Any code other
+than `"C0"` raises `Cetustek::ResultError` (`C5 - 該發票已經作廢過`, …), and
+marking your own record as canceled is the caller's job.
+
 ### Query invoices
 
 ```ruby
@@ -175,6 +215,23 @@ purchase). Set it on `InvoiceData`:
 Cetustek::Models::InvoiceData.new(hastax: 0, items: [...])
 ```
 
+### Other Table 1 fields
+
+| Attribute | Tag | Notes |
+|-----------|-----|-------|
+| `buyer_address` / `buyer_person_in_charge` / `buyer_telephone` / `buyer_facsimile` / `buyer_customer_number` | `BuyerAddress` / `BuyerPersonInCharge` / `BuyerTelephoneNumber` / `BuyerFacsimileNumber` / `BuyerCustomerNumber` | 選填，常用於 B2B |
+| `remark` | `Remark` | 備註，200 字 |
+| `zero_reason` | `ZeroReason` | 零稅率原因;未填時平台預設 `72`(TaxType 2)或 `71`(TaxType 5) |
+| `round_num` | `RoundNum` | 金額計算位數,未填預設 4 |
+| `mail_send` | `MailSend` | `0`(預設)由加值中心寄送通知,`1` 自行處理 |
+| `rtn_msg` | `RtnMsg` | 預設 `'Json'`;傳 `nil` 退回只回傳 15 碼字串的舊模式 |
+
+Fields with a platform-side default (`ZeroReason`, `RoundNum`, `MailSend`,
+`RtnMsg`) are omitted from the XML entirely when `nil`, so the platform applies
+its own default. `Intertemporal`(發票回開)is deliberately not exposed: it changes
+which filing period's 字軌 the invoice is issued under, and the platform default
+is the right behaviour.
+
 ### Allowances (折讓單)
 
 ```ruby

data/lib/cetustek/cancel_invoice.rb

@@ -1,54 +1,77 @@
+# frozen_string_literal: true
+
+require 'ox'
+require 'cgi'
+
 module Cetustek
+  # 2.2 CancelInvoice 作廢發票確認. Returns "C0" on success, raises ResultError
+  # otherwise. Uploading is not the end of it — the cancellation still has to be
+  # confirmed manually on the 鯨躍 platform before the invoice counts as void.
   class CancelInvoice
-    def initialize(invoice)
-      @invoice = invoice
+    SUCCESS_CODE = 'C0'
+
+    # Spec AVM-26-03 Table 10.
+    RESULT_MESSAGES = {
+      'M:' => '欄位未填或格式錯誤',
+      'M0' => 'XML 格式錯誤',
+      'M1' => 'XML 格式錯誤',
+      'C1' => '資料庫發生錯誤',
+      'C2' => '資料有誤',
+      'C3' => '該發票已過申報期間，需填入核准作廢文號 (return_tax_document_number)',
+      'C4' => '無此發票號碼可以作廢',
+      'C5' => '該發票已經作廢過',
+      'C6' => '作廢資訊已經傳送過',
+      'Invalid' => '無效 IP，請通知系統商'
+    }.freeze
+
+    def initialize(invoice_number, invoice_year, remark: '退貨', return_tax_document_number: nil)
+      raise ArgumentError, 'remark (作廢原因) is required' if remark.to_s.strip.empty?
+
+      @invoice_number = invoice_number
+      @invoice_year = invoice_year
+      @remark = remark
+      @return_tax_document_number = return_tax_document_number
     end
 
     def execute
-      generate_xml
       perform
-      analize_response
+      ResultCode.check!(@response.body[:cancel_invoice_response][:return],
+                        RESULT_MESSAGES, success: SUCCESS_CODE)
     end
 
     private
 
     def perform
-      url = Cetustek.config.url
-      client = Savon.client(
-        wsdl: url,
-        open_timeout: 300,
-        read_timeout: 300
-      )
-
-      @response = client.call(:cancel_invoice, message:
-        { invoicexml: @xml,
-          source: Cetustek.config.site_id + Cetustek.config.password,
-          rentid: Cetustek.config.username })
+      client = Savon.client(wsdl: Cetustek.config.url, open_timeout: 300, read_timeout: 300)
+      @response = client.call(:cancel_invoice, message: {
+                                invoicexml: generate_xml,
+                                source: Cetustek.config.site_id + Cetustek.config.password,
+                                rentid: Cetustek.config.username
+                              })
     end
 
     def generate_xml
       doc = Ox::Document.new
-
       instruct = Ox::Instruct.new(:xml)
       instruct[:version] = '1.0'
       instruct[:encoding] = 'UTF-8'
-      instruct[:standalone] = 'yes'
       doc << instruct
 
       invoice = Ox::Element.new('Invoice')
       invoice[:XSDVersion] = '2.8'
       doc << invoice
 
-      invoice << Ox::Raw.new("<InvoiceNumber>#{@invoice.number}</InvoiceNumber>")
-      invoice << Ox::Raw.new("<InvoiceYear>#{@invoice.created_at.year}</InvoiceYear>")
-      invoice << Ox::Raw.new('<Remark>退貨</Remark>')
-      @xml = Ox.dump(doc).force_encoding('UTF-8')
-    end
+      invoice << raw_tag('InvoiceNumber', @invoice_number)
+      invoice << raw_tag('InvoiceYear', @invoice_year)
+      # 專案作廢核准文號：只在超過申報期間作廢時才需要 (Table 10 的 C3)。
+      invoice << raw_tag('ReturnTaxDocumentNumber', @return_tax_document_number) if @return_tax_document_number
+      invoice << raw_tag('Remark', @remark)
 
-    def analize_response
-      return unless @response.body[:cancel_invoice_response][:return] == 'C0'
+      Ox.dump(doc).force_encoding('UTF-8')
+    end
 
-      @invoice.update(canceled: true)
+    def raw_tag(name, value)
+      Ox::Raw.new("<#{name}>#{CGI.escapeHTML(value.to_s)}</#{name}>")
     end
   end
 end

data/lib/cetustek/configuration.rb

@@ -2,7 +2,8 @@
 
 module Cetustek
   class Configuration
-    attr_accessor :environment, :site_id, :username, :password
+    # logger is opt-in: nil means this gem writes nothing anywhere.
+    attr_accessor :environment, :site_id, :username, :password, :logger
 
     def initialize
       @environment = :sandbox

data/lib/cetustek/create_invoice.rb

@@ -6,6 +6,8 @@ require_relative 'services/invoice_service'
 require_relative 'services/response_handler'
 
 module Cetustek
+  # 2.1 CreateInvoiceV3 開立發票. Returns the issued invoice on success and
+  # raises ResultError otherwise. Persisting the result is the caller's job.
   class CreateInvoice
     def initialize(invoice_data)
       @invoice_data = invoice_data
@@ -13,26 +15,8 @@ module Cetustek
 
     def execute
       xml = Services::InvoiceXmlBuilder.new(@invoice_data).build
-      response = Services::InvoiceService.new(xml, @invoice_data.order_id, @invoice_data.hastax).create
-      result = Services::ResponseHandler.new(response, @invoice_data, xml).process
-      
-      if defined?(Rails) && result[:number] && result[:random_number]
-        update_invoice_info(result)
-      end
-      
-      result
-    end
-
-    private
-
-    def update_invoice_info(result)
-      return unless @invoice_data.respond_to?(:invoice_info)
-      
-      @invoice_data.invoice_info.update(
-        number: result[:number],
-        random_number: result[:random_number],
-        created_at: Time.zone.today
-      )
+      response = Services::InvoiceService.new(xml, @invoice_data.hastax).create
+      Services::ResponseHandler.new(response, @invoice_data, xml).process
     end
   end
 end

data/lib/cetustek/models/invoice_data.rb

@@ -44,14 +44,29 @@ 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
+      TAX_TYPES = [TaxType::TAXABLE, TaxType::ZERO_RATE, TaxType::TAX_FREE,
+                   TaxType::SPECIAL, TaxType::ZERO_RATE_CUSTOMS, TaxType::MIXED].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,25 +74,114 @@ 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] || @carrier_id1
         @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。
       def mixed_tax?
         @tax_type.to_i == TaxType::MIXED
       end
+
+      # 特種稅額發票：TaxRate 必填，InvoiceType 必須為 08。
+      def special_tax?
+        @tax_type.to_i == TaxType::SPECIAL
+      end
+
+      private
+
+      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!
+      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
+      end
+
+      def validate_carrier!
+        missing = { buyer_email: @buyer_email, carrier_type: @carrier_type,
+                    carrier_id1: @carrier_id1 }.select { |_name, value| blank?(value) }.keys
+        return if missing.empty?
+
+        raise ArgumentError, "#{missing.join(', ')} required when donate_mark is 0 (載具)"
+      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
+        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 blank?(value)
+        value.nil? || value.to_s.strip.empty?
+      end
     end
 
     class InvoiceItem

data/lib/cetustek/services/invoice_service.rb

@@ -1,48 +1,27 @@
 # frozen_string_literal: true
 
 require 'savon'
-require 'logger'
 
 module Cetustek
   module Services
+    # 2.1 CreateInvoiceV3(invoicexml, hastax, rentid, source)
     class InvoiceService
-      def initialize(xml, order_id = nil, hastax = 1)
+      def initialize(xml, hastax = 1)
         @xml = xml
-        @order_id = order_id
         @hastax = hastax
       end
 
       def create
-        client = build_soap_client
-        response = call_create_invoice(client)
-        log_response(response)
-        response
-      end
-
-      private
-
-      def build_soap_client
         Savon.client(
           wsdl: Cetustek.config.url,
           open_timeout: 300,
           read_timeout: 300
-        )
-      end
-
-      def call_create_invoice(client)
-        client.call(:create_invoice_v3, message: {
-          invoicexml: @xml,
-          source: Cetustek.config.site_id + Cetustek.config.password,
-          rentid: Cetustek.config.username,
-          hastax: @hastax
-        })
-      end
-
-      def log_response(response)
-        return unless defined?(Rails)
-
-        logger = Logger.new(Rails.root.join('log/invoice.log'))
-        logger.debug("#{@order_id} - #{response.body}") if @order_id
+        ).call(:create_invoice_v3, message: {
+                 invoicexml: @xml,
+                 source: Cetustek.config.site_id + Cetustek.config.password,
+                 rentid: Cetustek.config.username,
+                 hastax: @hastax
+               })
       end
     end
   end

data/lib/cetustek/services/invoice_xml_builder.rb

@@ -46,6 +46,12 @@ module Cetustek
         invoice
       end
 
+      # Fields whose 備註 says "若未填，預設 X" are omitted entirely when nil, so
+      # the platform applies its own default instead of parsing an empty value.
+      def optional_tag(invoice, name, value)
+        invoice << raw_tag(name, value) unless value.nil?
+      end
+
       def add_basic_info(invoice)
         invoice << raw_tag('OrderId', @data.order_id)
         invoice << raw_tag('OrderDate', @data.order_date.strftime('%Y/%m/%d'))
@@ -54,19 +60,29 @@ module Cetustek
       def add_buyer_info(invoice)
         invoice << raw_tag('BuyerIdentifier', @data.buyer_identifier)
         invoice << raw_tag('BuyerName', @data.buyer_name)
+        invoice << raw_tag('BuyerAddress', @data.buyer_address)
+        invoice << raw_tag('BuyerPersonInCharge', @data.buyer_person_in_charge)
+        invoice << raw_tag('BuyerTelephoneNumber', @data.buyer_telephone)
+        invoice << raw_tag('BuyerFacsimileNumber', @data.buyer_facsimile)
         invoice << raw_tag('BuyerEmailAddress', @data.buyer_email)
+        invoice << raw_tag('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('CarrierId1', @data.carrier_id1)
         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)
+        optional_tag(invoice, 'ZeroReason', @data.zero_reason)
         invoice << raw_tag('PayWay', @data.payment_type)
+        invoice << raw_tag('Remark', @data.remark)
+        optional_tag(invoice, 'MailSend', @data.mail_send)
+        optional_tag(invoice, 'RoundNum', @data.round_num)
+        optional_tag(invoice, 'RtnMsg', @data.rtn_msg)
       end
 
       def add_details(invoice)
@@ -83,6 +99,7 @@ module Cetustek
         product << raw_tag('ProductionCode', item.code)
         product << raw_tag('Description', item.name)
         product << raw_tag('Quantity', item.quantity)
+        product << raw_tag('Unit', item.unit)
         product << raw_tag('UnitPrice', item.unit_price)
         add_dtype(product, item.d_type)
         product

data/lib/cetustek/services/response_handler.rb

@@ -1,37 +1,111 @@
 # 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
+      # Kept as a ResultError subclass so pre-0.7 rescues keep working.
+      # @deprecated rescue Cetustek::ResultError instead.
+      class InvalidResponseError < ResultError; end
 
-      def initialize(response, invoice_data, xml = nil)
+      SUCCESS_LENGTH = 15 # 發票號碼 10 碼 + ';' + 隨機碼 4 碼
+
+      # Spec AVM-26-03 Table 7.
+      RESULT_MESSAGES = {
+        'M:' => '欄位未填或格式錯誤',
+        'M0' => 'XML 格式錯誤',
+        'M1' => 'XML 格式錯誤',
+        'D0' => '沒有產品明細',
+        'D0_' => '產品編號格式錯誤',
+        'D1_' => '品名未填或格式錯誤',
+        'D2_' => '數量未填或格式錯誤',
+        'D3_' => '單價未填或格式錯誤',
+        'D4_' => '單位格式錯誤',
+        'D5_' => '數量*單價，其小計整數位大於 13 位',
+        'D999' => '明細筆數最多 9999 筆',
+        'S1' => '資料庫發生錯誤',
+        'S2' => '訂單日期超過開立日期',
+        'S3' => '未在申報期內',
+        'S4' => '未取得發票號碼',
+        'S5' => '發票號碼已使用完畢',
+        'S6' => '超過租賃張數限制',
+        'S7' => '訂單號碼已存在，若需重開請先作廢原發票號碼',
+        'S8' => '開立的總金額為負值',
+        'Invalid' => '無效 IP，請通知系統商'
+      }.freeze
+
+      def initialize(response, invoice_data = nil, xml = nil)
         @response = response
         @invoice_data = invoice_data
         @xml = xml
       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
+        raise InvalidResponseError.new(code, ResultCode.describe(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

data/lib/cetustek/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cetustek
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cetustek
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Zac
@@ -65,9 +65,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.12'
-description: Cetustek is a Ruby gem designed for handling electronic invoice operations,
-  including invoice cancellation. It communicates with the e-invoice system through
-  SOAP Web Services.
+description: 'Cetustek is a Ruby wrapper for the 鯨躍 Cetustek e-invoice API (虛擬多通路,
+  spec AVM-26-03): issuing and cancelling 電子發票 and 折讓單, the read-only queries, and
+  手機條碼 validation, over SOAP Web Services.'
 email:
 - 579103+7a6163@users.noreply.github.com
 executables: []
@@ -118,5 +118,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.16
 specification_version: 4
-summary: A Ruby gem for handling electronic invoice operations
+summary: A Ruby client for the Cetustek e-invoice API (電子發票加值中心)
 test_files: []