cetustek 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: edd228bea5d7cd37feceb6be6f790272b6bd66c8638b70518ea13d8a23454dcb
-  data.tar.gz: a365620162f118e193b9ddaa1caf50e335e43bac777831cfcff5c2b7322aff3e
+  metadata.gz: 887153f21f24293aa3ef9f6e4ee7ad48ec803c65f7104605a4d615894a5be19a
+  data.tar.gz: 14667650b0e2bf27c060df01cef3bb220d73bdb4ab6deb8bf5c1bf29bd9ba050
 SHA512:
-  metadata.gz: 7849c00fa5e89b28fb010dc4e71061b464a06aa9ea95d8213d135c5dcf031a80fe693fa79912c96bcef6d6f7c2e9a2dc0db9e34be516cc50ab6b62f433221b1f
-  data.tar.gz: 94041a6cc510de760b50799e7b8aa8d23159da26e93a1b0312c3f2be28decd51b925504ce416a9ac48ea8c04dc412e463437dcc69a7dcff020c50b9fbc54a482
+  metadata.gz: 508a2c1acb9f548116e963c7ce6b536a8e5aec3bc3d18189a56b52403a0d32f485191d5af2d6c5a3eef4a30a1f041a0eb94fe5ba8f73e38c7b30f06022f85a55
+  data.tar.gz: e2235999236cd67ee01462050391d1de6bfb4968eea812b7c9b4c7fc96b0559334e0800d5701d485d410d30f10d8486cd68bc217e04e1a9fb80169cc3e227977

data/CHANGELOG.md

@@ -5,6 +5,77 @@ 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
+- `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,67 @@ 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: Cetustek::CarrierType::MOBILE_BARCODE, # 3J0002
+  carrier_id: invoice.barcode,   # 手機條碼無顯隱碼之分，CarrierId2 自動填相同值
+  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
+- 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.
+
+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
@@ -86,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 (零稅率)
 
@@ -149,14 +201,22 @@ 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
+# remark 是 Table 9 的必填作廢原因，最多 20 字，沒有預設值
+Cetustek::CancelInvoice.new('AB12345678', 2024, remark: '退貨').execute # => "C0"
+
+# 超過申報期間才需要專案作廢核准文號 (否則會收到 C3)
+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
+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 +235,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` 自行處理;限 `donate_mark: 0` |
+| `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
@@ -191,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,54 +1,51 @@
+# frozen_string_literal: true
+
 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
+    include Soap
+
+    SUCCESS_CODE = 'C0'
+    MAX_REMARK_LENGTH = 20
+
+    # Spec AVM-26-03 Table 10.
+    RESULT_MESSAGES = ResultCode::COMMON.merge(
+      'C1' => '資料庫發生錯誤',
+      'C2' => '資料有誤',
+      'C3' => '該發票已過申報期間，需填入核准作廢文號 (return_tax_document_number)',
+      'C4' => '無此發票號碼可以作廢',
+      'C5' => '該發票已經作廢過',
+      'C6' => '作廢資訊已經傳送過'
+    ).freeze
+
+    # 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
+      @remark = remark
+      @return_tax_document_number = return_tax_document_number
     end
 
     def execute
-      generate_xml
-      perform
-      analize_response
+      response = soap_call(:cancel_invoice, invoicexml: generate_xml)
+      ResultCode.check!(soap_return(response, :cancel_invoice), 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 })
-    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
-
-    def analize_response
-      return unless @response.body[:cancel_invoice_response][:return] == 'C0'
-
-      @invoice.update(canceled: true)
+      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/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_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,37 +2,23 @@
 
 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.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
-      )
+      # 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
 end