cetustek 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2914b87b1c342a5309f39629998f26cf081179b02c064177f44628c0d1853329
-  data.tar.gz: e65afdb10fcfa7c358f7eaa7f953169f0265b6f69e56b624b75e5fe4ea1fc61e
+  metadata.gz: edd228bea5d7cd37feceb6be6f790272b6bd66c8638b70518ea13d8a23454dcb
+  data.tar.gz: a365620162f118e193b9ddaa1caf50e335e43bac777831cfcff5c2b7322aff3e
 SHA512:
-  metadata.gz: 5fe69cd1d22f538861b5dde8124133db53f618b059fc6cb5f7ed6cbe85c0f894c6c4aefb7eb1fda410d883a98f4f910f049a5e9aa0687b5108f7a407f16b209c
-  data.tar.gz: 0b64ceeeda241d5f7780e8b7ced545f2309657f3dd3dfcce7b7d631658ed6b1144b2481cd510920ed08ce863970e448c65d9ec485950a41c6ea57eddbeff5f14
+  metadata.gz: 7849c00fa5e89b28fb010dc4e71061b464a06aa9ea95d8213d135c5dcf031a80fe693fa79912c96bcef6d6f7c2e9a2dc0db9e34be516cc50ab6b62f433221b1f
+  data.tar.gz: 94041a6cc510de760b50799e7b8aa8d23159da26e93a1b0312c3f2be28decd51b925504ce416a9ac48ea8c04dc412e463437dcc69a7dcff020c50b9fbc54a482

data/CHANGELOG.md

@@ -5,6 +5,33 @@ 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.7.0] - 2026-08-04
+
+### Added
+- `Cetustek::QueryAllowance.find(allowance_number)` — 查詢折讓資料 (§2.11) with the
+  returned XML parsed into a Hash (snake_case keys + `:details` array); `nil` when the
+  allowance number is unknown. `.query` still returns the raw Savon response
+- `Cetustek::ResultError` (with `#code`) plus the full 折讓 result-code tables from
+  spec Table 17/19, including the suffixed forms (`M:欄位`, `D2_3`)
+
+### Changed
+- **Breaking:** `CreateAllowance#execute` / `CancelAllowance#execute` now raise
+  `Cetustek::ResultError` on any code other than `A0` / `C0` instead of returning it
+  (e.g. `A2` 折讓金額大於原發票, `A7` 折讓日期早於發票日, `C2` 已申報無法作廢)
+- **Breaking:** `AllowanceData` validates `tax_type`; only `1` 應稅 / `2` 零稅率 /
+  `3` 免稅 are valid on a 折讓單 (spec Table 15), the invoice-only `4`/`5`/`9` now
+  raise `ArgumentError`
+- **Breaking:** `CreateAllowance.new(data, check_allowance: 1)` now raises
+  `ArgumentError`. The spec struck out the unconfirmed-allowance flag — 114/01/01 起
+  上傳的折讓單皆為已確認,只能送 `0`
+
+## [0.6.0] - 2026-06-30
+
+### Added
+- `Cetustek::DonateMark` constants for 捐贈註記 (spec AVM-26-03 Table 1):
+  `CARRIER` (0), `DONATE` (1), `PAPER` (2). Convenience only — `donate_mark`
+  still accepts any raw value.
+
 ## [0.5.0] - 2026-06-30
 
 ### Added

data/README.md

@@ -134,6 +134,11 @@ Cetustek::Models::InvoiceData.new(
 | | | | `QUAN_PAY` | `X` |
 | | | | `COIN_CARD` | `Z` |
 
+### Donation mark (`donate_mark` / DonateMark)
+
+`donate_mark` accepts any raw code, or use `Cetustek::DonateMark`:
+`CARRIER` (0, 載具), `DONATE` (1, 捐贈), `PAPER` (2, 紙本).
+
 ### Discounts and fees
 
 The gem is a faithful wrapper of the API's invoice detail format, so it has no
@@ -186,7 +191,30 @@ allowance = Cetustek::Models::AllowanceData.new(
 )
 Cetustek::CreateAllowance.new(allowance).execute              # => "A0" on success
 Cetustek::CancelAllowance.new('AA20240216000001', '明細錯誤').execute # => "C0" on success
-Cetustek::QueryAllowance.query('AA20240216000001')
+Cetustek::QueryAllowance.find('AA20240216000001')             # parsed Hash, nil if unknown
+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).
+
+Any other result code raises `Cetustek::ResultError`, whose `#code` is the raw
+code and whose message includes the documented reason (e.g. `A2 - 所有折讓金額加總
+不能大於原發票金額`, `C2 - 折讓單已申報，無法作廢`).
+
+`QueryAllowance.find` returns the Table 20 fields as snake_case symbols with the
+line items under `:details`, values kept as the raw strings from the XML:
+
+```ruby
+{ allowance_number: 'AA20240216000001', allowance_date: '2024/02/16',
+  invoice_number: 'AA10000000', invoice_date: '2024/02/14',
+  buyer_identifier: '12345678', buyer_name: '測試公司', buyer_address: nil,
+  reason: '退回', allowance_status: '開立', back_status: '已確認',
+  sale_amount: '95', tax_amount: '5',
+  details: [{ sequence_number: '1', product_code: '0001', description: '禮券',
+              quantity: '1', unit: '本', unit_price: '95', amount: '95',
+              tax: '5', tax_type: '1' }] }
 ```
 
 ### Mobile barcode validation (手機條碼)

data/lib/cetustek/cancel_allowance.rb

@@ -4,8 +4,22 @@ require 'ox'
 require 'cgi'
 
 module Cetustek
-  # 2.10 CancelAllowance 作廢折讓單. Returns the result code (C0 = success).
+  # 2.10 CancelAllowance 作廢折讓單. Returns "C0" on success, raises ResultError otherwise.
   class CancelAllowance
+    SUCCESS_CODE = 'C0'
+
+    # Spec AVM-26-03 Table 19.
+    RESULT_MESSAGES = {
+      'M:' => '欄位未填或格式錯誤',
+      'M1' => 'XML 格式錯誤',
+      'C1' => '上傳失敗',
+      'C2' => '折讓單已申報，無法作廢',
+      'C3' => '折讓單號不存在或須為已確認後的折讓單',
+      'C4' => '該作廢折讓單已經上傳',
+      'C5' => '折讓單已過作廢期限，無法作廢',
+      'Invalid' => '無效 IP，請通知系統商'
+    }.freeze
+
     def initialize(allowance_number, reason)
       @allowance_number = allowance_number
       @reason = reason
@@ -13,7 +27,8 @@ module Cetustek
 
     def execute
       perform
-      @response.body[:cancel_allowance_response][:return]
+      ResultCode.check!(@response.body[:cancel_allowance_response][:return],
+                        RESULT_MESSAGES, success: SUCCESS_CODE)
     end
 
     private

data/lib/cetustek/create_allowance.rb

@@ -4,17 +4,45 @@ require 'ox'
 require 'cgi'
 
 module Cetustek
-  # 2.9 CreateAllowance 開立折讓單. Returns the result code (A0 = success).
-  # check_allowance: 0 = confirmed allowance (default), 1 = unconfirmed.
+  # 2.9 CreateAllowance 開立折讓單. Returns "A0" on success, raises ResultError otherwise.
   class CreateAllowance
+    SUCCESS_CODE = 'A0'
+
+    # Spec AVM-26-03 Table 17.
+    RESULT_MESSAGES = {
+      'M:' => '欄位未填或格式錯誤',
+      'M1' => 'XML 格式錯誤',
+      'D0' => '沒有產品明細',
+      'D0_' => '產品編號格式錯誤',
+      'D1_' => '品名未填或格式錯誤',
+      'D2_' => '數量未填或格式錯誤',
+      'D3_' => '單價未填或格式錯誤',
+      'D4_' => '單位格式錯誤',
+      'D5_' => '數量*單價，其小計整數位大於 13 位',
+      'D999' => '明細筆數最多 9999 筆',
+      'A1' => '上傳失敗',
+      'A2' => '所有折讓金額加總不能大於原發票金額',
+      'A3' => '發票號碼不存在',
+      'A4' => '發票號碼已經被作廢',
+      'A5' => '折讓單已經上傳',
+      'A6' => '折讓總金額須大於零',
+      'A7' => '折讓日期應大於原發票開立日期',
+      'Invalid' => '無效 IP，請通知系統商'
+    }.freeze
+
+    # check_allowance 只剩 0（已確認的折讓單）：規格 §2.9 已刪除 1，
+    # 114/01/01 起上傳的折讓單皆為已確認。
     def initialize(allowance_data, check_allowance: 0)
+      raise ArgumentError, 'check_allowance must be 0 (114/01/01 起折讓單皆為已確認)' unless check_allowance.to_i.zero?
+
       @data = allowance_data
-      @check_allowance = check_allowance
+      @check_allowance = 0
     end
 
     def execute
       perform
-      @response.body[:create_allowance_response][:return]
+      ResultCode.check!(@response.body[:create_allowance_response][:return],
+                        RESULT_MESSAGES, success: SUCCESS_CODE)
     end
 
     private

data/lib/cetustek/errors.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Cetustek
+  class Error < StandardError; end
+
+  # Raised when an API call returns a result code other than the success code.
+  class ResultError < Error
+    attr_reader :code
+
+    def initialize(code, description = nil)
+      @code = code
+      super([code, description].compact.join(' - '))
+    end
+  end
+
+  module ResultCode
+    # 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.
+    def self.describe(code, messages)
+      messages[code] || messages[code.to_s.sub(/(?<=[:_]).*\z/, '')]
+    end
+
+    # Returns the code on success, otherwise raises ResultError.
+    def self.check!(code, messages, success:)
+      return code if code == success
+
+      raise ResultError.new(code, describe(code, messages))
+    end
+  end
+end

data/lib/cetustek/models/allowance_data.rb

@@ -7,6 +7,10 @@ module Cetustek
     # Request data for CreateAllowance (開立折讓單), spec AVM-26-03 Table 15/16.
     # Line items reuse InvoiceItem (code/name/quantity/unit/unit_price).
     class AllowanceData
+      # 折讓單稅別只有應稅/零稅率/免稅，發票的 4 (特種稅率)、5 (經海關出口)
+      # 與 9 (混合) 在折讓單無效。
+      TAX_TYPES = [TaxType::TAXABLE, TaxType::ZERO_RATE, TaxType::TAX_FREE].freeze
+
       attr_reader :allowance_number, :allowance_date, :invoice_number,
                   :invoice_year, :buyer_address, :buyer_email, :tax_type,
                   :reason, :round_num, :items
@@ -19,6 +23,10 @@ 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] || []

data/lib/cetustek/models/invoice_data.rb

@@ -35,6 +35,14 @@ module Cetustek
     COIN_CARD = 'Z'   # 銀角零卡
   end
 
+  # DonateMark (捐贈註記) codes for CreateInvoiceV3, spec AVM-26-03 Table 1.
+  # Convenience constants only — InvoiceData#donate_mark still accepts any raw value.
+  module DonateMark
+    CARRIER = 0 # 載具
+    DONATE = 1  # 捐贈
+    PAPER = 2   # 紙本
+  end
+
   module Models
     class InvoiceData
       DEFAULT_TAX_RATE = 0.05

data/lib/cetustek/queries.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+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.
@@ -48,6 +50,14 @@ module Cetustek
   class QueryAllowance
     extend Queries
 
+    # Spec AVM-26-03 Table 20. Note the query response uses ProductCode and
+    # InvoiceDate, unlike CreateAllowance's ProductionCode and InvoiceYear.
+    FIELDS = %w[AllowanceNumber AllowanceDate InvoiceNumber InvoiceDate
+                BuyerIdentifier BuyerName BuyerAddress Reason AllowanceStatus
+                BackStatus SaleAmount TaxAmount].freeze
+    DETAIL_FIELDS = %w[SequenceNumber ProductCode Description Quantity Unit
+                       UnitPrice Amount Tax TaxType].freeze
+
     def self.query(allowance_number)
       soap_client.call(:query_allowance, message: {
                          allowancenumber: allowance_number,
@@ -55,5 +65,36 @@ module Cetustek
                          rentid: rentid
                        })
     end
+
+    # 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.
+    def self.find(allowance_number)
+      parse(query(allowance_number).body[:query_allowance_response][:return])
+    end
+
+    def self.parse(xml)
+      body = xml.to_s.strip
+      return nil if body.empty? || body == 'nodata'
+
+      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
+
+    def self.snake_case(name)
+      name.gsub(/([a-z\d])([A-Z])/, '\1_\2').downcase.to_sym
+    end
+
+    private_class_method :text_of, :snake_case
   end
 end

data/lib/cetustek/version.rb

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

data/lib/cetustek.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "cetustek/version"
+require_relative "cetustek/errors"
 require_relative "cetustek/configuration"
 require_relative "cetustek/models/allowance_data"
 require_relative "cetustek/create_invoice"
@@ -12,8 +13,6 @@ require_relative "cetustek/cancel_allowance"
 require_relative "cetustek/phone_barcode"
 
 module Cetustek
-  class Error < StandardError; end
-
   class << self
     def configure
       yield(config)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cetustek
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Zac
@@ -84,6 +84,7 @@ files:
 - lib/cetustek/configuration.rb
 - lib/cetustek/create_allowance.rb
 - lib/cetustek/create_invoice.rb
+- lib/cetustek/errors.rb
 - lib/cetustek/models/allowance_data.rb
 - lib/cetustek/models/invoice_data.rb
 - lib/cetustek/phone_barcode.rb
@@ -115,7 +116,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.16
 specification_version: 4
 summary: A Ruby gem for handling electronic invoice operations
 test_files: []