cetustek 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 98c3af7dadac0df75cb3fc24f02e124765716e1856034ed120cead8e2f2ce1a5
-  data.tar.gz: 7d0a29575e2b24e786371b989da8107437eeb7d319bbf9514a83db6e7912fc79
+  metadata.gz: 90bc8844eac9b3eb305d59f5550be7bf6e552b0fffafe74b0e71e6afc31c55ef
+  data.tar.gz: a9337fd9f37f80a3ec6532a319c4eac87ce1db79a475d7e237e3f2b59567a850
 SHA512:
-  metadata.gz: 6243d83ecc59c97b961ec8185d46967b8e04148b752e2a810c519e238e53a9d8450944c10214cd320f465a1137e1d97c63bd1d8bf547bd59b16d6deace421916
-  data.tar.gz: 9224b032dcb1eae4facaa3278b0c732daf79fbbcfe00ea17532a27b5bf989ba862711427021f2cd5a459abdce171ff0199931b2f99531cb3baa9c406457e3be4
+  metadata.gz: 57e5c7e15f119c182c8d0f38ef0c98ce40c682bc0262ed7043a09ed8c379a2603ae88d581bef8bcdc9e0f0a95cc5be85e6a6dc502f7c883bb7f6e74c9ebd8fa3
+  data.tar.gz: c267be5d85ea54c917d932453a910bfcca464b4e5441ad4f2c98aec3e4b2f567712e65617e6250186ebd6164ec39f4157ad12014cfce6445847afe7c8db1b926

data/CHANGELOG.md

@@ -5,6 +5,72 @@ 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.10.0] - 2026-08-07
+
+延續 0.9.0 的 code review：統一驗證力度與查詢介面，讓四個查詢類別與
+`CancelInvoice`/`CancelAllowance` 的行為一致。
+
+### Added
+- `QueryInvoice.find`、`QueryInvoiceByOrderId.find`、`QueryInvoiceNumberByOrderId.find`：
+  比照既有的 `QueryAllowance.find`，把 Savon 回應解析成 snake_case 的 Hash（`QueryInvoice`
+  與 `QueryInvoiceByOrderId` 共用 Table 13 格式，含 `:seller`/`:buyer`/`:details`），
+  `nil` 表示空回覆或規格說的 `"nodata"`，非 XML 的代碼字串一律拋 `Cetustek::ResultError`
+- `CancelInvoice` 補上 `invoice_number`/`invoice_year` 必填檢查（Table 9 皆為 Y），
+  原本只驗證 `remark`，另兩個欄位空白時要等伺服器回 `M:?` 才會發現
+
+### Changed
+- 四個查詢類別的 XML 解析共用邏輯(`text_of`/`snake_case`)搬到 `Cetustek::Xml.parse_fields`，
+  不再各自留一份幾乎相同的 private method
+- `QueryInvoice`/`QueryInvoiceNumberByOrderId`/`QueryAllowance` 改用 `Soap#soap_call`，
+  不再手動組 `source`/`rentid`，與 `QueryInvoiceByOrderId`/`CancelInvoice` 等類別一致
+- `QueryInvoice.parse`/`QueryAllowance.parse` 共用的「空值/nodata 判斷、非 XML 代碼丟
+  `ResultError`、解析成 Ox root」邏輯收成 `Cetustek::Xml.parse_response`
+- `QueryInvoice.party` 改名 `parse_party`，跟同一個類別的 `parse` 放在一起看更清楚
+
+### Fixed
+- **Breaking:** `QueryInvoiceNumberByOrderId.find` 原本會把非發票號碼、非 `"nodata"`
+  的回覆(如 `Invalid`)直接當發票號碼回傳；現在會比對 Table 9 的字軌+8碼數字格式，
+  格式不符者一律丟 `Cetustek::ResultError`，跟其他 `Query*.find` 一致
+
+## [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,13 +204,18 @@ 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
 ```
 
+`invoice_number` and `invoice_year` are Table 9's other two `必填` fields, and
+raise `ArgumentError` if left blank — the same guaranteed-rejection guarantee
+`InvoiceData`/`AllowanceData` give for their own required fields.
+
 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
@@ -199,10 +223,35 @@ marking your own record as canceled is the caller's job.
 
 ### Query invoices
 
+Each query class has both a raw `.query` (the Savon response, for callers who
+want the untouched SOAP object) and a `.find` that parses the same response
+into a plain Ruby value, mirroring `QueryAllowance` below:
+
 ```ruby
-Cetustek::QueryInvoiceByOrderId.query(order_id)             # by order id
-Cetustek::QueryInvoice.query(invoice_number, invoice_year)  # by invoice number + year
-Cetustek::QueryInvoiceNumberByOrderId.query(order_id)       # just the invoice number
+Cetustek::QueryInvoiceByOrderId.query(order_id)             # raw Savon response
+Cetustek::QueryInvoiceByOrderId.find(order_id)               # parsed Hash, or nil
+Cetustek::QueryInvoice.query(invoice_number, invoice_year)   # raw Savon response
+Cetustek::QueryInvoice.find(invoice_number, invoice_year)    # parsed Hash, or nil
+Cetustek::QueryInvoiceNumberByOrderId.query(order_id)        # raw Savon response
+Cetustek::QueryInvoiceNumberByOrderId.find(order_id)          # bare invoice number String, or nil
+```
+
+`.find` returns `nil` when the platform answers with nothing at all or with
+the documented `"nodata"`; a non-XML answer (a result code) is raised as
+`Cetustek::ResultError`, same as `QueryAllowance.find`.
+
+`QueryInvoice.find`/`QueryInvoiceByOrderId.find` (both share Table 13's XML
+shape) return the fields as snake_case symbols, with `:seller`/`:buyer`
+sub-hashes and the line items under `:details`:
+
+```ruby
+{ order_id: '44556655', invoice_number: 'AA00000027', invoice_date: '2011/05/19',
+  invoice_time: '19:10:49', invoice_status: '開立', donate_mark: '0',
+  sales_amount: '120', tax_amount: '6', total_amount: '126', ctk_url: nil,
+  seller: { identifier: '53118823', name: '鯨躍科技有限公司', ... },
+  buyer: { identifier: '55669988', name: '漢客料理店', ... },
+  details: [{ product_code: 'AA783457', description: '筆記本(綠色)', quantity: '1',
+              unit: nil, unit_price: '60', amount: '60', sequence_number: '1' }] }
 ```
 
 ### Tax-inclusive vs tax-exclusive prices (`hastax`)
@@ -223,7 +272,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 +297,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,31 @@
 # 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, 'invoice_number is required' if invoice_number.to_s.strip.empty?
+      raise ArgumentError, 'invoice_year is required' if invoice_year.to_s.strip.empty?
       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 +34,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