cetustek 0.9.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 887153f21f24293aa3ef9f6e4ee7ad48ec803c65f7104605a4d615894a5be19a
-  data.tar.gz: 14667650b0e2bf27c060df01cef3bb220d73bdb4ab6deb8bf5c1bf29bd9ba050
+  metadata.gz: c6a6aca36dc760878fe11e9107416c7296ef5fa7835d1e223f3cab8248970fb7
+  data.tar.gz: 96fb067d26a7cb40e0b429a8a9f502fa486bc5bc2efcded04bb136bcba4b99c1
 SHA512:
-  metadata.gz: 508a2c1acb9f548116e963c7ce6b536a8e5aec3bc3d18189a56b52403a0d32f485191d5af2d6c5a3eef4a30a1f041a0eb94fe5ba8f73e38c7b30f06022f85a55
-  data.tar.gz: e2235999236cd67ee01462050391d1de6bfb4968eea812b7c9b4c7fc96b0559334e0800d5701d485d410d30f10d8486cd68bc217e04e1a9fb80169cc3e227977
+  metadata.gz: 4cdf8f6a063bb979aecd5d974dd1482329582359831bf0cbb20f46c50987dbbb677e675dd3507c3bbd69883277103760900dc12b55c3650f3215b1e3ab3dc408
+  data.tar.gz: 6240dd9f19af70f835d4323a5fad194a77ef8be409f503013887095c1bd25ece1331507030443ae8a7ea571aa97c6a47eb6982e0142a2605f467afbd47977564

data/CHANGELOG.md

@@ -5,6 +5,51 @@ 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.11.0] - 2026-08-24
+
+### Added
+
+- `config.transport` — `:httpi` (預設，維持現有行為) 或 `:faraday`。設成其他值
+  在 `Cetustek.configure` 當下就 raise `ArgumentError`。
+
+### Fixed
+
+- 沙盒端點 `invoice.cetustek.com.tw` 的 `certificate verify failed`：savon 預設
+  的 HTTPI 首選 adapter 是 httpclient，而 httpclient 只認 gem 內附的
+  `cacert.pem`，裡面沒有該端點憑證鏈的根 Certum Trusted Root CA。只要 bundle
+  裡有 httpclient，沙盒開票就會全數失敗。`config.transport = :faraday` 改走
+  Faraday 的 `net_http`，讀系統信任庫。production (`www.ei.com.tw`) 不受影響。
+  Faraday 路徑不能傳 `open_timeout`/`read_timeout`（savon 2.17 的
+  `FaradayMigrationHint::OPTIONS` 會 raise），改由 `client.faraday.options`
+  設定，兩條路徑的 300 秒逾時一致。
+
+## [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 有幾條規則寫得比規格寬或比規格嚴,

data/README.md

@@ -50,9 +50,33 @@ Cetustek.configure do |config|
   # 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
+
+  # Optional. :httpi (default, savon's own HTTP stack) or :faraday.
+  # See "SSL on the sandbox endpoint" below — if sandbox calls fail with
+  # `certificate verify failed`, set this to :faraday.
+  config.transport = :faraday
 end
 ```
 
+### SSL on the sandbox endpoint (`certificate verify failed`)
+
+The sandbox endpoint `invoice.cetustek.com.tw` chains to **Certum Trusted Root
+CA**. Savon's default HTTP stack is HTTPI, whose first-choice adapter is
+`httpclient` — and `httpclient` ignores the system trust store, trusting only
+the `cacert.pem` bundled inside the gem, which does not include that root. So
+if anything in your bundle pulls in `httpclient` (plenty of gems do), every
+sandbox call fails with:
+
+```
+SSL_connect ... certificate verify failed (unable to get local issuer certificate)
+```
+
+Production (`www.ei.com.tw`, Sectigo/USERTrust) is unaffected.
+
+Fix it with `config.transport = :faraday`, which goes through Faraday's
+`net_http` adapter and reads the system trust store. The 300s open/read
+timeouts are applied either way.
+
 ## Usage
 
 ### Issue an Invoice
@@ -212,6 +236,10 @@ 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
@@ -219,10 +247,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)             # 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
-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
+{ 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`)

data/lib/cetustek/cancel_invoice.rb

@@ -22,6 +22,8 @@ module Cetustek
 
     # 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
 

data/lib/cetustek/configuration.rb

@@ -2,11 +2,26 @@
 
 module Cetustek
   class Configuration
+    # HTTPI (savon 的預設) 第一順位是 httpclient，而 httpclient 只認 gem 內附的
+    # cacert.pem，裡面沒有 Certum Trusted Root CA — 也就是 sandbox 端點
+    # invoice.cetustek.com.tw 憑證鏈的根。只要環境裡有 httpclient，沙盒開票就會
+    # 全數 certificate verify failed。改用 :faraday 走 net_http，讀系統信任庫。
+    TRANSPORTS = %i[httpi faraday].freeze
+
     # logger is opt-in: nil means this gem writes nothing anywhere.
     attr_accessor :environment, :site_id, :username, :password, :logger
+    attr_reader :transport
 
     def initialize
       @environment = :sandbox
+      @transport = :httpi
+    end
+
+    def transport=(value)
+      raise ArgumentError, "transport must be one of #{TRANSPORTS.join(', ')}, got #{value.inspect}" \
+        unless TRANSPORTS.include?(value)
+
+      @transport = value
     end
 
     def url

data/lib/cetustek/queries.rb

@@ -1,41 +1,81 @@
 # frozen_string_literal: true
 
-require 'ox'
-
 module Cetustek
   # @deprecated use Cetustek::Soap. Kept so `extend Queries` keeps working.
   Queries = Soap
 
   # 2.4 QueryInvoice 查詢發票資訊 (by invoice number + year)
   class QueryInvoice
-    extend Queries
+    extend Soap
+
+    # Spec AVM-26-03 Table 13.
+    FIELDS = %w[OrderID InvoiceNumber InvoiceDate InvoiceTime MainRemark CheckNumber
+                RandomNumber InvoiceStatus DonateMark SalesAmount FreeTaxSalesAmount
+                ZeroTaxSalesAmount TaxAmount TotalAmount CtkUrl].freeze
+    PARTY_FIELDS = %w[Identifier Name Address PersonInCharge TelephoneNumber
+                      FacsimileNumber EmailAddress].freeze
+    DETAIL_FIELDS = %w[ProductCode Description Quantity Unit UnitPrice Amount SequenceNumber].freeze
 
     def self.query(invoice_number, invoice_year)
-      soap_client.call(:query_invoice, message: {
-                         invoicenumber: invoice_number,
-                         invoiceyear: invoice_year,
-                         source: source,
-                         rentid: rentid
-                       })
+      soap_call(:query_invoice, invoicenumber: invoice_number, invoiceyear: invoice_year)
+    end
+
+    # Same query, with the returned XML parsed into a Hash of snake_case keys
+    # plus :seller/:buyer sub-hashes and a :details array. nil when the
+    # platform answers with nothing at all, or the documented "nodata".
+    def self.find(invoice_number, invoice_year)
+      parse(soap_return(query(invoice_number, invoice_year), :query_invoice))
+    end
+
+    # §2.5 QueryInvoicebyOrderid shares this exact XML shape (Table 13), so
+    # QueryInvoiceByOrderId#find reuses this instead of duplicating it.
+    def self.parse(xml)
+      root = Xml.parse_response(xml, nil_values: %w[nodata])
+      return nil unless root
+
+      data = Xml.parse_fields(root, FIELDS)
+      data[:seller] = parse_party(root, 'Seller')
+      data[:buyer] = parse_party(root, 'Buyer')
+      data[:details] = root.locate('Details/ProductItem').map { |item| Xml.parse_fields(item, DETAIL_FIELDS) }
+      data
+    end
+
+    def self.parse_party(root, name)
+      element = root.locate(name).first
+      element && Xml.parse_fields(element, PARTY_FIELDS)
     end
+
+    private_class_method :parse_party
   end
 
   # 2.6 QueryInvoiceNumberbyOrderid 以訂單編號查詢發票號碼
   class QueryInvoiceNumberByOrderId
-    extend Queries
+    extend Soap
+
+    # 發票號碼格式，字軌 2 碼大寫字母+8 碼數字 (Table 9). Anything else that
+    # isn't the "nodata" sentinel is a bare result code, not a number.
+    FORMAT = /\A[A-Z]{2}\d{8}\z/
 
     def self.query(order_id)
-      soap_client.call(:query_invoice_number_by_orderid, message: {
-                         orderid: order_id,
-                         source: source,
-                         rentid: rentid
-                       })
+      soap_call(:query_invoice_number_by_orderid, orderid: order_id)
+    end
+
+    # Same query, returning just the bare invoice number string, or nil for
+    # an empty response or the documented "nodata". A response that isn't
+    # either shape is a result code, raised as ResultError like the other
+    # Query* classes — it used to be returned as if it were the number.
+    def self.find(order_id)
+      body = soap_return(query(order_id), :query_invoice_number_by_orderid).to_s.strip
+      return nil if body.empty? || body == 'nodata'
+      return body if body.match?(FORMAT)
+
+      ResultCode.raise!(body, ResultCode::COMMON)
     end
   end
 
   # 2.11 QueryAllowance 查詢折讓資料
   class QueryAllowance
-    extend Queries
+    extend Soap
 
     # Spec AVM-26-03 Table 20. Note the query response uses ProductCode and
     # InvoiceDate, unlike CreateAllowance's ProductionCode and InvoiceYear.
@@ -46,11 +86,7 @@ module Cetustek
                        UnitPrice Amount Tax TaxType].freeze
 
     def self.query(allowance_number)
-      soap_client.call(:query_allowance, message: {
-                         allowancenumber: allowance_number,
-                         source: source,
-                         rentid: rentid
-                       })
+      soap_call(:query_allowance, allowancenumber: allowance_number)
     end
 
     # Same query, with the returned XML parsed into a Hash of snake_case keys
@@ -61,29 +97,12 @@ module Cetustek
     end
 
     def self.parse(xml)
-      body = xml.to_s.strip
-      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 = FIELDS.to_h { |field| [snake_case(field), text_of(root, field)] }
-      data[:details] = root.locate('Details/ProductItem').map do |item|
-        DETAIL_FIELDS.to_h { |field| [snake_case(field), text_of(item, field)] }
-      end
-      data
-    end
-
-    def self.text_of(element, name)
-      element.locate(name).first&.text
-    end
+      root = Xml.parse_response(xml)
+      return nil unless root
 
-    def self.snake_case(name)
-      name.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase.to_sym
+      data = Xml.parse_fields(root, FIELDS)
+      data[:details] = root.locate('Details/ProductItem').map { |item| Xml.parse_fields(item, DETAIL_FIELDS) }
+      data
     end
-
-    private_class_method :text_of, :snake_case
   end
 end

data/lib/cetustek/query_invoice_by_order_id.rb

@@ -8,5 +8,11 @@ module Cetustek
     def self.query(order_id)
       soap_call(:query_invoice_by_orderid, orderid: order_id)
     end
+
+    # Same query, parsed into a Hash. §2.5 shares Table 13's XML shape with
+    # §2.4, so this reuses QueryInvoice.parse instead of duplicating it.
+    def self.find(order_id)
+      QueryInvoice.parse(soap_return(query(order_id), :query_invoice_by_orderid))
+    end
   end
 end

data/lib/cetustek/soap.rb

@@ -6,8 +6,26 @@ module Cetustek
   # Shared SOAP plumbing: every operation hits the same WSDL and authenticates
   # with 網站代碼+APIPassword (source) and the 租賃者統編 (rentid).
   module Soap
+    TIMEOUT = 300
+
     def soap_client
-      Savon.client(wsdl: Cetustek.config.url, open_timeout: 300, read_timeout: 300)
+      return httpi_client unless Cetustek.config.transport == :faraday
+
+      faraday_client
+    end
+
+    def httpi_client
+      Savon.client(wsdl: Cetustek.config.url, open_timeout: TIMEOUT, read_timeout: TIMEOUT)
+    end
+
+    # savon 2.17 的 FaradayMigrationHint::OPTIONS 會讓 open_timeout/read_timeout
+    # 在 transport: :faraday 下直接 raise，逾時改由 faraday 連線自己設。
+    def faraday_client
+      require 'faraday'
+      Savon.client(wsdl: Cetustek.config.url, transport: :faraday).tap do |client|
+        client.faraday.options.open_timeout = TIMEOUT
+        client.faraday.options.read_timeout = TIMEOUT
+      end
     end
 
     def source

data/lib/cetustek/version.rb

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

data/lib/cetustek/xml.rb

@@ -39,5 +39,34 @@ module Cetustek
 
       element << tag(name, value)
     end
+
+    # Shared guard every Query* class needs before it can parse a response
+    # body: nil for an empty answer or one of the documented sentinel strings
+    # (e.g. "nodata"); ResultError for a bare result code; otherwise the
+    # parsed root element, ready for parse_fields.
+    def parse_response(body, nil_values: [])
+      text = body.to_s.strip
+      return nil if text.empty? || nil_values.include?(text)
+
+      ResultCode.raise!(text, ResultCode::COMMON) unless text.start_with?('<')
+
+      root = Ox.parse(text)
+      root.is_a?(Ox::Document) ? root.root : root
+    end
+
+    # Shared response-parsing side: every Query* class turns a response
+    # element into a Hash of snake_case keys, so this lives here once instead
+    # of once per query class.
+    def parse_fields(element, fields)
+      fields.to_h { |field| [snake_case(field), text_of(element, field)] }
+    end
+
+    def text_of(element, name)
+      element&.locate(name)&.first&.text
+    end
+
+    def snake_case(name)
+      name.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase.to_sym
+    end
   end
 end

data/lib/cetustek.rb

@@ -8,8 +8,8 @@ require_relative "cetustek/soap"
 require_relative "cetustek/models/allowance_data"
 require_relative "cetustek/create_invoice"
 require_relative "cetustek/cancel_invoice"
-require_relative "cetustek/query_invoice_by_order_id"
 require_relative "cetustek/queries"
+require_relative "cetustek/query_invoice_by_order_id"
 require_relative "cetustek/create_allowance"
 require_relative "cetustek/cancel_allowance"
 require_relative "cetustek/phone_barcode"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cetustek
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.11.0
 platform: ruby
 authors:
 - Zac