cetustek 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98c3af7dadac0df75cb3fc24f02e124765716e1856034ed120cead8e2f2ce1a5
-  data.tar.gz: 7d0a29575e2b24e786371b989da8107437eeb7d319bbf9514a83db6e7912fc79
+  metadata.gz: 887153f21f24293aa3ef9f6e4ee7ad48ec803c65f7104605a4d615894a5be19a
+  data.tar.gz: 14667650b0e2bf27c060df01cef3bb220d73bdb4ab6deb8bf5c1bf29bd9ba050
 SHA512:
-  metadata.gz: 6243d83ecc59c97b961ec8185d46967b8e04148b752e2a810c519e238e53a9d8450944c10214cd320f465a1137e1d97c63bd1d8bf547bd59b16d6deace421916
-  data.tar.gz: 9224b032dcb1eae4facaa3278b0c732daf79fbbcfe00ea17532a27b5bf989ba862711427021f2cd5a459abdce171ff0199931b2f99531cb3baa9c406457e3be4
+  metadata.gz: 508a2c1acb9f548116e963c7ce6b536a8e5aec3bc3d18189a56b52403a0d32f485191d5af2d6c5a3eef4a30a1f041a0eb94fe5ba8f73e38c7b30f06022f85a55
+  data.tar.gz: e2235999236cd67ee01462050391d1de6bfb4968eea812b7c9b4c7fc96b0559334e0800d5701d485d410d30f10d8486cd68bc217e04e1a9fb80169cc3e227977

data/CHANGELOG.md

@@ -5,6 +5,45 @@ 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.9.0] - 2026-08-05
+
+比對規格 AVM-26-03 做的 code review 修正:0.8.0 有幾條規則寫得比規格寬或比規格嚴,
+另外把四份重複的 SOAP/XML 樣板收成共用模組。
+
+### Fixed
+- **Breaking:** `carrier_id2` 只在無顯碼隱碼區分的載具(手機條碼 `3J0002`、自然人憑證
+  `CQ0001`)自動鏡射顯碼。會員載具(如鯨躍發票卡 `EJ0011`)兩碼本來就不同,0.8.0 會把顯碼
+  當隱碼送出;現在未填 `carrier_id2` 會直接丟 `ArgumentError`
+- `donate_mark: 0` 不再強制 `carrier_type`:規格註明「使用鯨躍發票卡,電子郵件必填,
+  載具類別可為空或填 EJ0011」,原本的檢查讓這個情境無法送出。必填改為 `buyer_email`
+  與 `carrier_id1`/`carrier_id2`
+- `QueryAllowance.find` 移除規格沒有的 `'nodata'` 哨兵值;非 XML 的回覆(代碼字串)
+  改為丟 `ResultError`,只有真的空回覆才回傳 `nil`
+- 修掉註解裡捏造的規格出處(`spec V4.16`)與 TaxType 9 的「限收銀機類型發票」限制,
+  Table 1 只寫「9:混合(應稅、零稅率與免稅)」
+
+### Added
+- `Cetustek::CarrierType`:`MOBILE_BARCODE` / `CITIZEN_CERT` / `CETUSTEK_CARD` 常數
+- `AllowanceData` 依 Table 15 驗證必填(折讓單號、折讓日期、發票號碼、發票年份、
+  折讓原因、至少一筆明細)與 `round_num` 0-7、`reason` 20 字。原本 `allowance_date`
+  為 nil 會在組 XML 時炸成 `NoMethodError`
+- `InvoiceItem` 依 Table 2/16 驗證 `code`/`name`/`quantity`/`unit_price` 必填(`unit` 選填)
+- `CancelAllowance` 驗證 Table 18 的兩個必填欄位與 20 字上限
+- `InvoiceData` 補上規格寫死的條件與範圍:`zero_reason` 限 `tax_type` 2/5、
+  `mail_send` 限 `donate_mark: 0`、`round_num` 0-7、`remark` 200 字
+
+### Changed
+- **Breaking:** `CancelInvoice` 的 `remark:`(作廢原因)改為必填且限 20 字 —— Table 9 是
+  必填欄位,預設 `'退貨'` 等於幫呼叫端編造理由
+- **Breaking:** 移除 `Services::InvoiceService`,它只剩一次 Savon 呼叫;`CreateInvoice`
+  直接送出
+- `ResponseHandler` 失敗時丟 `ResultError` 本身,與折讓路徑一致。
+  `ResponseHandler::InvalidResponseError` 改為 `ResultError` 的別名常數(deprecated),
+  既有 `rescue InvalidResponseError` 仍然攔得到
+- 新增 `Cetustek::Xml` 與 `Cetustek::Soap`,收掉五份 Savon client 與四份 `raw_tag` 複製;
+  Table 7/10/17/19 共用的代碼列集中在 `ResultCode::COMMON` 與 `ResultCode::DETAILS`。
+  `Cetustek::Queries` 成為 `Cetustek::Soap` 的別名(deprecated)
+
 ## [0.8.0] - 2026-08-04
 
 ### Added

data/README.md

@@ -66,8 +66,8 @@ invoice_data = Cetustek::Models::InvoiceData.new(
   buyer_name: invoice.name,
   buyer_email: invoice.email,
   donate_mark: Cetustek::DonateMark::CARRIER,
-  carrier_type: '3J0002',        # 手機條碼
-  carrier_id: invoice.barcode,   # CarrierId2 is mirrored automatically
+  carrier_type: Cetustek::CarrierType::MOBILE_BARCODE, # 3J0002
+  carrier_id: invoice.barcode,   # 手機條碼無顯隱碼之分，CarrierId2 自動填相同值
   payment_type: Cetustek::PayWay::ATM,
   items: invoice.items.map { |item|
     Cetustek::Models::InvoiceItem.new(
@@ -96,9 +96,28 @@ Persisting the result is the caller's job — this gem writes to no database.
 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`
+- every item needs `code`, `name`, `quantity` and `unit_price` (`unit` is optional)
+- `donate_mark: 0` (載具) requires `buyer_email`, `carrier_id1` and `carrier_id2`
 - `donate_mark: 1` (捐贈) requires a 3–7 digit `npo_ban`
 - `tax_type: 4` (特種稅率) requires an explicit `tax_rate` and `invoice_type: '08'`
+- `zero_reason` only with `tax_type` 2 or 5; `mail_send` only with `donate_mark: 0`
+- `round_num` 0–7, `remark` at most 200 characters
+
+### Carriers (載具)
+
+`Cetustek::CarrierType` names the codes the spec spells out:
+
+| Constant | Code | Meaning |
+|----------|------|---------|
+| `MOBILE_BARCODE` | `3J0002` | 手機條碼 |
+| `CITIZEN_CERT`   | `CQ0001` | 自然人憑證條碼 |
+| `CETUSTEK_CARD`  | `EJ0011` | 鯨躍發票卡 |
+
+手機條碼與自然人憑證「無顯碼隱碼區分」, so passing `carrier_id` (or `carrier_id1`)
+alone is enough and `CarrierId2` is filled with the same value. Member carriers
+do carry two different codes, so both `carrier_id1` and `carrier_id2` must be
+given — the gem will not guess a 隱碼 it cannot know. 鯨躍發票卡 may be requested
+with a blank `carrier_type`, as the spec allows.
 
 Anything needing an external lookup (是否為有效手機條碼、捐贈碼是否存在) is left
 to the caller — see `Cetustek::PhoneBarcode` below.
@@ -119,7 +138,7 @@ general invoice type of `07`. Use `Cetustek::TaxType` to switch modes:
 | `TAX_FREE`          | 3 | 免稅 |
 | `SPECIAL`           | 4 | 應稅(特種稅率) — set `tax_rate`, use `invoice_type: '08'` |
 | `ZERO_RATE_CUSTOMS` | 5 | 零稅率(經海關出口) |
-| `MIXED`             | 9 | 混合(應稅/零稅率/免稅，限收銀機類型發票) |
+| `MIXED`             | 9 | 混合(應稅/零稅率/免稅) |
 
 #### Zero-rate invoice (零稅率)
 
@@ -185,11 +204,12 @@ Cetustek::Models::InvoiceItem.new(code: 'DISCOUNT', name: '折抵', quantity: 1,
 ### Cancel an Invoice (作廢發票確認)
 
 ```ruby
-Cetustek::CancelInvoice.new('AB12345678', 2024).execute                    # => "C0"
-Cetustek::CancelInvoice.new('AB12345678', 2024, remark: '明細錯誤').execute # 作廢原因，預設 '退貨'
+# remark 是 Table 9 的必填作廢原因，最多 20 字，沒有預設值
+Cetustek::CancelInvoice.new('AB12345678', 2024, remark: '退貨').execute # => "C0"
 
 # 超過申報期間才需要專案作廢核准文號 (否則會收到 C3)
-Cetustek::CancelInvoice.new('AB12345678', 2024, return_tax_document_number: '65327645').execute
+Cetustek::CancelInvoice.new('AB12345678', 2024, remark: '明細錯誤',
+                            return_tax_document_number: '65327645').execute
 ```
 
 Uploading is not the end of it: the cancellation still has to be confirmed
@@ -223,7 +243,7 @@ Cetustek::Models::InvoiceData.new(hastax: 0, items: [...])
 | `remark` | `Remark` | 備註，200 字 |
 | `zero_reason` | `ZeroReason` | 零稅率原因;未填時平台預設 `72`(TaxType 2)或 `71`(TaxType 5) |
 | `round_num` | `RoundNum` | 金額計算位數,未填預設 4 |
-| `mail_send` | `MailSend` | `0`(預設)由加值中心寄送通知,`1` 自行處理 |
+| `mail_send` | `MailSend` | `0`(預設)由加值中心寄送通知,`1` 自行處理;限 `donate_mark: 0` |
 | `rtn_msg` | `RtnMsg` | 預設 `'Json'`;傳 `nil` 退回只回傳 15 碼字串的舊模式 |
 
 Fields with a platform-side default (`ZeroReason`, `RoundNum`, `MailSend`,
@@ -248,13 +268,19 @@ allowance = Cetustek::Models::AllowanceData.new(
 )
 Cetustek::CreateAllowance.new(allowance).execute              # => "A0" on success
 Cetustek::CancelAllowance.new('AA20240216000001', '明細錯誤').execute # => "C0" on success
-Cetustek::QueryAllowance.find('AA20240216000001')             # parsed Hash, nil if unknown
+Cetustek::QueryAllowance.find('AA20240216000001')             # parsed Hash
 Cetustek::QueryAllowance.query('AA20240216000001')            # raw Savon response
 ```
 
-`tax_type` on an allowance only accepts `1` 應稅, `2` 零稅率 or `3` 免稅 — the
-invoice-only values (`4`, `5`, `9`) raise `ArgumentError`. `unit_price` is
-**tax-inclusive** (there is no `hastax` on allowances).
+`AllowanceData.new` raises `ArgumentError` for the Table 15 rules: `allowance_number`,
+`allowance_date` (a `Date`/`Time`), `invoice_number`, `invoice_year`, `reason` (20 字)
+and at least one item are required, and `round_num` must be 0–7. `tax_type` only
+accepts `1` 應稅, `2` 零稅率 or `3` 免稅 — the invoice-only values (`4`, `5`, `9`)
+raise. `unit_price` is **tax-inclusive** (there is no `hastax` on allowances).
+`CancelAllowance` takes the two Table 18 fields, both required, 作廢原因 up to 20 字.
+
+`QueryAllowance.find` returns `nil` only when the platform answers with nothing at
+all; a non-XML answer is a result code and is raised as `ResultError`.
 
 Any other result code raises `Cetustek::ResultError`, whose `#code` is the raw
 code and whose message includes the documented reason (e.g. `A2 - 所有折讓金額加總

data/lib/cetustek/cancel_allowance.rb

@@ -1,66 +1,44 @@
 # frozen_string_literal: true
 
-require 'ox'
-require 'cgi'
-
 module Cetustek
   # 2.10 CancelAllowance 作廢折讓單. Returns "C0" on success, raises ResultError otherwise.
   class CancelAllowance
+    include Soap
+
     SUCCESS_CODE = 'C0'
+    MAX_REASON_LENGTH = 20
 
     # Spec AVM-26-03 Table 19.
-    RESULT_MESSAGES = {
-      'M:' => '欄位未填或格式錯誤',
-      'M1' => 'XML 格式錯誤',
+    RESULT_MESSAGES = ResultCode::COMMON.merge(
       'C1' => '上傳失敗',
       'C2' => '折讓單已申報，無法作廢',
       'C3' => '折讓單號不存在或須為已確認後的折讓單',
       'C4' => '該作廢折讓單已經上傳',
-      'C5' => '折讓單已過作廢期限，無法作廢',
-      'Invalid' => '無效 IP，請通知系統商'
-    }.freeze
+      'C5' => '折讓單已過作廢期限，無法作廢'
+    ).freeze
 
+    # Table 18 has only these two fields, both 必填.
     def initialize(allowance_number, reason)
+      raise ArgumentError, 'allowance_number is required' if allowance_number.to_s.strip.empty?
+      raise ArgumentError, 'reason (作廢原因) is required' if reason.to_s.strip.empty?
+      raise ArgumentError, "reason must not exceed #{MAX_REASON_LENGTH} characters" if reason.length > MAX_REASON_LENGTH
+
       @allowance_number = allowance_number
       @reason = reason
     end
 
     def execute
-      perform
-      ResultCode.check!(@response.body[:cancel_allowance_response][:return],
-                        RESULT_MESSAGES, success: SUCCESS_CODE)
+      response = soap_call(:cancel_allowance, allowancexml: generate_xml)
+      ResultCode.check!(soap_return(response, :cancel_allowance), RESULT_MESSAGES, success: SUCCESS_CODE)
     end
 
     private
 
-    def perform
-      client = Savon.client(wsdl: Cetustek.config.url, open_timeout: 300, read_timeout: 300)
-      @response = client.call(:cancel_allowance, message: {
-                                allowancexml: 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'
-      doc << instruct
-
-      allowance = Ox::Element.new('Allowance')
-      allowance[:XSDVersion] = '2.8'
-      doc << allowance
-
-      allowance << raw_tag('AllowanceNumber', @allowance_number)
-      allowance << raw_tag('Reason', @reason)
-
-      Ox.dump(doc).force_encoding('UTF-8')
-    end
-
-    def raw_tag(name, value)
-      Ox::Raw.new("<#{name}>#{CGI.escapeHTML(value.to_s)}</#{name}>")
+      Xml.document('Allowance') do |allowance|
+        Xml.append(allowance, 'AllowanceNumber', @allowance_number)
+        Xml.append(allowance, 'Reason', @reason)
+      end
     end
   end
 end

data/lib/cetustek/cancel_invoice.rb

@@ -1,31 +1,29 @@
 # 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
+    include Soap
+
     SUCCESS_CODE = 'C0'
+    MAX_REMARK_LENGTH = 20
 
     # Spec AVM-26-03 Table 10.
-    RESULT_MESSAGES = {
-      'M:' => '欄位未填或格式錯誤',
-      'M0' => 'XML 格式錯誤',
-      'M1' => 'XML 格式錯誤',
+    RESULT_MESSAGES = ResultCode::COMMON.merge(
       'C1' => '資料庫發生錯誤',
       'C2' => '資料有誤',
       'C3' => '該發票已過申報期間，需填入核准作廢文號 (return_tax_document_number)',
       'C4' => '無此發票號碼可以作廢',
       'C5' => '該發票已經作廢過',
-      'C6' => '作廢資訊已經傳送過',
-      'Invalid' => '無效 IP，請通知系統商'
-    }.freeze
+      'C6' => '作廢資訊已經傳送過'
+    ).freeze
 
-    def initialize(invoice_number, invoice_year, remark: '退貨', return_tax_document_number: nil)
+    # remark 是 Table 9 的必填作廢原因，沒有預設值可用：理由是業務決定的。
+    def initialize(invoice_number, invoice_year, remark:, return_tax_document_number: nil)
       raise ArgumentError, 'remark (作廢原因) is required' if remark.to_s.strip.empty?
+      raise ArgumentError, "remark must not exceed #{MAX_REMARK_LENGTH} characters" if remark.length > MAX_REMARK_LENGTH
 
       @invoice_number = invoice_number
       @invoice_year = invoice_year
@@ -34,44 +32,20 @@ module Cetustek
     end
 
     def execute
-      perform
-      ResultCode.check!(@response.body[:cancel_invoice_response][:return],
-                        RESULT_MESSAGES, success: SUCCESS_CODE)
+      response = soap_call(:cancel_invoice, invoicexml: generate_xml)
+      ResultCode.check!(soap_return(response, :cancel_invoice), RESULT_MESSAGES, success: SUCCESS_CODE)
     end
 
     private
 
-    def perform
-      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'
-      doc << instruct
-
-      invoice = Ox::Element.new('Invoice')
-      invoice[:XSDVersion] = '2.8'
-      doc << invoice
-
-      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)
-
-      Ox.dump(doc).force_encoding('UTF-8')
-    end
-
-    def raw_tag(name, value)
-      Ox::Raw.new("<#{name}>#{CGI.escapeHTML(value.to_s)}</#{name}>")
+      Xml.document('Invoice') do |invoice|
+        Xml.append(invoice, 'InvoiceNumber', @invoice_number)
+        Xml.append(invoice, 'InvoiceYear', @invoice_year)
+        # 專案作廢核准文號：只在超過申報期間作廢時才需要 (Table 10 的 C3)。
+        Xml.append(invoice, 'ReturnTaxDocumentNumber', @return_tax_document_number, skip_nil: true)
+        Xml.append(invoice, 'Remark', @remark)
+      end
     end
   end
 end

data/lib/cetustek/create_allowance.rb

@@ -1,34 +1,22 @@
 # frozen_string_literal: true
 
-require 'ox'
-require 'cgi'
-
 module Cetustek
   # 2.9 CreateAllowance 開立折讓單. Returns "A0" on success, raises ResultError otherwise.
   class CreateAllowance
+    include Soap
+
     SUCCESS_CODE = 'A0'
 
     # Spec AVM-26-03 Table 17.
-    RESULT_MESSAGES = {
-      'M:' => '欄位未填或格式錯誤',
-      'M1' => 'XML 格式錯誤',
-      'D0' => '沒有產品明細',
-      'D0_' => '產品編號格式錯誤',
-      'D1_' => '品名未填或格式錯誤',
-      'D2_' => '數量未填或格式錯誤',
-      'D3_' => '單價未填或格式錯誤',
-      'D4_' => '單位格式錯誤',
-      'D5_' => '數量*單價，其小計整數位大於 13 位',
-      'D999' => '明細筆數最多 9999 筆',
+    RESULT_MESSAGES = ResultCode::COMMON.merge(ResultCode::DETAILS).merge(
       'A1' => '上傳失敗',
       'A2' => '所有折讓金額加總不能大於原發票金額',
       'A3' => '發票號碼不存在',
       'A4' => '發票號碼已經被作廢',
       'A5' => '折讓單已經上傳',
       'A6' => '折讓總金額須大於零',
-      'A7' => '折讓日期應大於原發票開立日期',
-      'Invalid' => '無效 IP，請通知系統商'
-    }.freeze
+      'A7' => '折讓日期應大於原發票開立日期'
+    ).freeze
 
     # check_allowance 只剩 0（已確認的折讓單）：規格 §2.9 已刪除 1，
     # 114/01/01 起上傳的折讓單皆為已確認。
@@ -40,64 +28,39 @@ module Cetustek
     end
 
     def execute
-      perform
-      ResultCode.check!(@response.body[:create_allowance_response][:return],
-                        RESULT_MESSAGES, success: SUCCESS_CODE)
+      response = soap_call(:create_allowance, allowancexml: generate_xml, checkallowance: @check_allowance)
+      ResultCode.check!(soap_return(response, :create_allowance), RESULT_MESSAGES, success: SUCCESS_CODE)
     end
 
     private
 
-    def perform
-      client = Savon.client(wsdl: Cetustek.config.url, open_timeout: 300, read_timeout: 300)
-      @response = client.call(:create_allowance, message: {
-                                allowancexml: generate_xml,
-                                checkallowance: @check_allowance,
-                                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'
-      doc << instruct
-
-      allowance = Ox::Element.new('Allowance')
-      allowance[:XSDVersion] = '2.8'
-      doc << allowance
-
-      allowance << raw_tag('AllowanceNumber', @data.allowance_number)
-      allowance << raw_tag('AllowanceDate', @data.allowance_date.strftime('%Y/%m/%d'))
-      allowance << raw_tag('InvoiceNumber', @data.invoice_number)
-      allowance << raw_tag('InvoiceYear', @data.invoice_year)
-      allowance << raw_tag('BuyerAddress', @data.buyer_address)
-      allowance << raw_tag('BuyerEmailAddress', @data.buyer_email)
-      allowance << raw_tag('TaxType', @data.tax_type)
-      allowance << raw_tag('Reason', @data.reason)
-      allowance << raw_tag('RoundNum', @data.round_num) unless @data.round_num.nil?
-      allowance << build_details
-
-      Ox.dump(doc).force_encoding('UTF-8')
+      Xml.document('Allowance') do |allowance|
+        Xml.append(allowance, 'AllowanceNumber', @data.allowance_number)
+        Xml.append(allowance, 'AllowanceDate', @data.allowance_date.strftime('%Y/%m/%d'))
+        Xml.append(allowance, 'InvoiceNumber', @data.invoice_number)
+        Xml.append(allowance, 'InvoiceYear', @data.invoice_year)
+        Xml.append(allowance, 'BuyerAddress', @data.buyer_address)
+        Xml.append(allowance, 'BuyerEmailAddress', @data.buyer_email)
+        Xml.append(allowance, 'TaxType', @data.tax_type)
+        Xml.append(allowance, 'Reason', @data.reason)
+        Xml.append(allowance, 'RoundNum', @data.round_num, skip_nil: true)
+        allowance << build_details
+      end
     end
 
     def build_details
       details = Ox::Element.new('Details')
       @data.items.each do |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('Unit', item.unit)
-        product << raw_tag('UnitPrice', item.unit_price)
+        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)
         details << product
       end
       details
     end
-
-    def raw_tag(name, value)
-      Ox::Raw.new("<#{name}>#{CGI.escapeHTML(value.to_s)}</#{name}>")
-    end
   end
 end

data/lib/cetustek/create_invoice.rb

@@ -2,20 +2,22 @@
 
 require_relative 'models/invoice_data'
 require_relative 'services/invoice_xml_builder'
-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
+    include Soap
+
     def initialize(invoice_data)
       @invoice_data = invoice_data
     end
 
     def execute
       xml = Services::InvoiceXmlBuilder.new(@invoice_data).build
-      response = Services::InvoiceService.new(xml, @invoice_data.hastax).create
+      # hastax: 0 = 明細單價未稅, 1 = 含稅; comes from the order, not a constant.
+      response = soap_call(:create_invoice_v3, invoicexml: xml, hastax: @invoice_data.hastax)
       Services::ResponseHandler.new(response, @invoice_data, xml).process
     end
   end

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.
@@ -54,8 +66,11 @@ module Cetustek
       # 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,
@@ -82,8 +97,7 @@ module Cetustek
         @donate_mark = attributes[:donate_mark]
         @carrier_type = attributes[:carrier_type]
         @carrier_id1 = attributes[:carrier_id1] || attributes[:carrier_id]
-        # 手機條碼與自然人憑證沒有顯碼隱碼之分，兩欄填相同值。
-        @carrier_id2 = attributes[:carrier_id2] || @carrier_id1
+        @carrier_id2 = attributes[:carrier_id2] || mirrored_carrier_id2
         @npo_ban = attributes[:npo_ban]
         @items = attributes[:items] || []
         @payment_type = attributes[:payment_type]
@@ -102,7 +116,7 @@ module Cetustek
         validate!
       end
 
-      # 混合稅率發票 (限收銀機)：每筆明細需標註 DType。
+      # 混合稅率發票：每筆明細需標註 DType。
       def mixed_tax?
         @tax_type.to_i == TaxType::MIXED
       end
@@ -114,6 +128,11 @@ module Cetustek
 
       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)
 
@@ -122,6 +141,8 @@ module Cetustek
         validate_donate_mark!
         validate_pay_way!
         validate_tax!
+        validate_remark!
+        validate_round_num!
       end
 
       def validate_order_date!
@@ -147,14 +168,22 @@ module Cetustek
         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_type: @carrier_type,
-                    carrier_id1: @carrier_id1 }.select { |_name, value| blank?(value) }.keys
+        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 (載具)"
+        raise ArgumentError, "#{missing.join(', ')} required when donate_mark is 0 (載具)" \
+                             "#{'; 此載具有顯碼與隱碼之分，請分別填入' if missing == [:carrier_id2]}"
       end
 
       def validate_npo_ban!
@@ -171,6 +200,8 @@ module Cetustek
         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)
@@ -179,11 +210,32 @@ module Cetustek
         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 = {
@@ -191,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
 
@@ -201,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'.
@@ -208,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,78 +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
-
-      # 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'))
+        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('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)
+        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_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)
+        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)
@@ -96,22 +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('Unit', item.unit)
-        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

@@ -8,25 +8,14 @@ module Cetustek
     # the Table 8 JSON object (RtnMsg=Json), the 15-character
     # "發票號碼;隨機碼" string, or a bare Table 7 result code.
     class ResponseHandler
-      # Kept as a ResultError subclass so pre-0.7 rescues keep working.
-      # @deprecated rescue Cetustek::ResultError instead.
-      class InvalidResponseError < ResultError; 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 = {
-        'M:' => '欄位未填或格式錯誤',
-        'M0' => 'XML 格式錯誤',
-        'M1' => 'XML 格式錯誤',
-        'D0' => '沒有產品明細',
-        'D0_' => '產品編號格式錯誤',
-        'D1_' => '品名未填或格式錯誤',
-        'D2_' => '數量未填或格式錯誤',
-        'D3_' => '單價未填或格式錯誤',
-        'D4_' => '單位格式錯誤',
-        'D5_' => '數量*單價，其小計整數位大於 13 位',
-        'D999' => '明細筆數最多 9999 筆',
+      RESULT_MESSAGES = ResultCode::COMMON.merge(ResultCode::DETAILS).merge(
         'S1' => '資料庫發生錯誤',
         'S2' => '訂單日期超過開立日期',
         'S3' => '未在申報期內',
@@ -34,11 +23,10 @@ module Cetustek
         'S5' => '發票號碼已使用完畢',
         'S6' => '超過租賃張數限制',
         'S7' => '訂單號碼已存在，若需重開請先作廢原發票號碼',
-        'S8' => '開立的總金額為負值',
-        'Invalid' => '無效 IP，請通知系統商'
-      }.freeze
+        'S8' => '開立的總金額為負值'
+      ).freeze
 
-      def initialize(response, invoice_data = nil, xml = nil)
+      def initialize(response, invoice_data, xml = nil)
         @response = response
         @invoice_data = invoice_data
         @xml = xml
@@ -97,7 +85,7 @@ module Cetustek
       def fail_with(code)
         logger&.error("CreateInvoiceV3 #{order_id} #{code}")
         logger&.debug(@xml) if @xml
-        raise InvalidResponseError.new(code, ResultCode.describe(code, RESULT_MESSAGES))
+        ResultCode.raise!(code, RESULT_MESSAGES)
       end
 
       def logger
@@ -105,7 +93,7 @@ module Cetustek
       end
 
       def order_id
-        @invoice_data&.order_id
+        @invoice_data.order_id
       end
     end
   end

data/lib/cetustek/soap.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'savon'
+
+module Cetustek
+  # Shared SOAP plumbing: every operation hits the same WSDL and authenticates
+  # with 網站代碼+APIPassword (source) and the 租賃者統編 (rentid).
+  module Soap
+    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
+
+    def soap_call(operation, message)
+      soap_client.call(operation, message: message.merge(source: source, rentid: rentid))
+    end
+
+    def soap_return(response, operation)
+      response.body[:"#{operation}_response"][:return]
+    end
+  end
+end

data/lib/cetustek/version.rb

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

data/lib/cetustek/xml.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'ox'
+require 'cgi'
+
+module Cetustek
+  # Every request document in the spec is the same shape: a UTF-8 declaration
+  # and a single <Invoice>/<Allowance> root carrying XSDVersion.
+  module Xml
+    XSD_VERSION = '2.8'
+
+    module_function
+
+    def document(root_name)
+      doc = Ox::Document.new
+      instruct = Ox::Instruct.new(:xml)
+      instruct[:version] = '1.0'
+      instruct[:encoding] = 'UTF-8'
+      doc << instruct
+
+      root = Ox::Element.new(root_name)
+      root[:XSDVersion] = XSD_VERSION
+      doc << root
+      yield root
+
+      Ox.dump(doc).force_encoding('UTF-8')
+    end
+
+    # Values are HTML-escaped so that special characters (&, <, >, ", ') in any
+    # dynamic field cannot break the XML or be used for injection.
+    def tag(name, value)
+      Ox::Raw.new("<#{name}>#{CGI.escapeHTML(value.to_s)}</#{name}>")
+    end
+
+    # Fields whose 備註 says "若未填，預設 X" are left out entirely when nil, so
+    # the platform applies its own default instead of parsing an empty value.
+    def append(element, name, value, skip_nil: false)
+      return if skip_nil && value.nil?
+
+      element << tag(name, value)
+    end
+  end
+end

data/lib/cetustek.rb

@@ -3,6 +3,8 @@
 require_relative "cetustek/version"
 require_relative "cetustek/errors"
 require_relative "cetustek/configuration"
+require_relative "cetustek/xml"
+require_relative "cetustek/soap"
 require_relative "cetustek/models/allowance_data"
 require_relative "cetustek/create_invoice"
 require_relative "cetustek/cancel_invoice"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cetustek
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Zac
@@ -90,10 +90,11 @@ files:
 - lib/cetustek/phone_barcode.rb
 - lib/cetustek/queries.rb
 - lib/cetustek/query_invoice_by_order_id.rb
-- lib/cetustek/services/invoice_service.rb
 - lib/cetustek/services/invoice_xml_builder.rb
 - lib/cetustek/services/response_handler.rb
+- lib/cetustek/soap.rb
 - lib/cetustek/version.rb
+- lib/cetustek/xml.rb
 - sig/cetustek.rbs
 homepage: https://github.com/7a6163/cetustek
 licenses:

data/lib/cetustek/services/invoice_service.rb

@@ -1,28 +0,0 @@
-# frozen_string_literal: true
-
-require 'savon'
-
-module Cetustek
-  module Services
-    # 2.1 CreateInvoiceV3(invoicexml, hastax, rentid, source)
-    class InvoiceService
-      def initialize(xml, hastax = 1)
-        @xml = xml
-        @hastax = hastax
-      end
-
-      def create
-        Savon.client(
-          wsdl: Cetustek.config.url,
-          open_timeout: 300,
-          read_timeout: 300
-        ).call(:create_invoice_v3, message: {
-                 invoicexml: @xml,
-                 source: Cetustek.config.site_id + Cetustek.config.password,
-                 rentid: Cetustek.config.username,
-                 hastax: @hastax
-               })
-      end
-    end
-  end
-end