cetustek 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 722407201f6462aed26f91e61295dc87fcfdc970db2b55adf8aa73f4a4840f1a
-  data.tar.gz: ab37a4849d55a493854202d343c2cf082fb118813eea9d491e09970209317066
+  metadata.gz: cc27cec134bbdcde72328147677ace14f302f2423128209d8ec0ddd190ceeca7
+  data.tar.gz: cfb7115017ef61ba4c928459f1d8d8815bf5a1fd616cc050a8be012a942aac3e
 SHA512:
-  metadata.gz: db34fb0378f5fd87b4c42cec44306b69afaa09ceb9ade280993f1618ed487e0c92ea6e61f3645747277e4a1e548b736f7806ced8e659c4a84a0d1a98da3efbe8
-  data.tar.gz: 5164f077cb9fff85c4879ea31e0f51710d03b6b621545c2b757deac19f3833e7f50802470577812ca95cfccb8742b271dc71c418625a8e9b5947f08e8c22bf2a
+  metadata.gz: 1a350443ea05a452ec354e1f9d7a5cb624cd04087baecef9f756c715350497bdc6d9b0fbedc41ee2087d711aba66b72ecfbb7c207d239d8b8278266335a3eae4
+  data.tar.gz: 5ac422d52d5d11b0bf71d97186ab9bd257f667ec135c942f87df934f66cb4f7653a40cda4794d62171aa72d905f98d60fe46e416409399e07abbfe679a063130

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/CHANGELOG.md

@@ -5,6 +5,28 @@ 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.3.0] - 2026-06-13
+
+### Added
+- Configurable tax handling per spec V4.16: `TaxType`, `TaxRate`, and `InvoiceType`
+  on `InvoiceData`, with a `Cetustek::TaxType` constants module
+- Zero-rate invoice support (`TaxType` 2/5)
+- Mixed-tax invoice support (`TaxType` 9): per-item `tax_type` emits the required
+  `DType` (`TZ`/`TN`/blank) on every detail line
+- `carrier_id2` attribute on `InvoiceData` (previously read by the XML builder but
+  never settable, which raised `NoMethodError` when issuing an invoice)
+- Test suite for the XML builder and data models
+
+### Changed
+- XML builder now HTML-escapes every interpolated field (previously only buyer name
+  and product name), preventing malformed XML / injection from special characters
+
+### Removed
+- **Breaking:** application-specific auto line items and their `InvoiceData` fields
+  (`total_discount`, `coupon_discount`, `delivery_fee`, `handling_fee`). These were
+  not part of the Cetustek API. Model discounts/fees as ordinary `InvoiceItem`s
+  (use a negative `unit_price` for a discount)
+
 ## [0.2.0] - 2025-01-22
 
 ### Added

data/README.md

@@ -44,7 +44,7 @@ end
 
 ## Usage
 
-### Cancel an Invoice
+### Issue an Invoice
 
 ```ruby
 invoice = YourInvoiceModel.find(invoice_id)
@@ -54,7 +54,9 @@ invoice_data = Cetustek::Models::InvoiceData.new(
   buyer_identifier: invoice.receipt,
   buyer_name: invoice.name,
   buyer_email: invoice.email,
-  items: invoice.items.map { |item| 
+  donate_mark: 0,
+  payment_type: 2,
+  items: invoice.items.map { |item|
     Cetustek::Models::InvoiceItem.new(
       code: item.sku,
       name: item.name,
@@ -65,6 +67,73 @@ invoice_data = Cetustek::Models::InvoiceData.new(
 )
 
 result = Cetustek::CreateInvoice.new(invoice_data).execute
+# => { number: "GT68514542", random_number: "9654" }
+```
+
+### Tax types (稅別)
+
+`InvoiceData` defaults to taxable (`TaxType` 1) with a tax rate of `0.05` and a
+general invoice type of `07`. Use `Cetustek::TaxType` to switch modes:
+
+| Constant | Code | Meaning |
+|----------|------|---------|
+| `TAXABLE`           | 1 | 應稅 |
+| `ZERO_RATE`         | 2 | 零稅率(非經海關出口) |
+| `TAX_FREE`          | 3 | 免稅 |
+| `SPECIAL`           | 4 | 應稅(特種稅率) — set `tax_rate`, use `invoice_type: '08'` |
+| `ZERO_RATE_CUSTOMS` | 5 | 零稅率(經海關出口) |
+| `MIXED`             | 9 | 混合(應稅/零稅率/免稅，限收銀機類型發票) |
+
+#### Zero-rate invoice (零稅率)
+
+```ruby
+Cetustek::Models::InvoiceData.new(
+  # ...buyer fields, items...
+  tax_type: Cetustek::TaxType::ZERO_RATE,
+  tax_rate: 0
+)
+```
+
+#### Mixed-tax invoice (混稅, cash-register invoices only)
+
+For `TaxType` 9 each line item must declare its own tax category via `tax_type`.
+Accepts the symbols `:taxable` (default), `:zero_rate`, `:tax_free`, or the raw
+`DType` codes (`''`, `'TZ'`, `'TN'`):
+
+```ruby
+Cetustek::Models::InvoiceData.new(
+  # ...buyer fields...
+  tax_type: Cetustek::TaxType::MIXED,
+  items: [
+    Cetustek::Models::InvoiceItem.new(code: 'A', name: '應稅品',  quantity: 1, unit_price: 100),
+    Cetustek::Models::InvoiceItem.new(code: 'B', name: '零稅率品', quantity: 1, unit_price: 100, tax_type: :zero_rate),
+    Cetustek::Models::InvoiceItem.new(code: 'C', name: '免稅品',  quantity: 1, unit_price: 100, tax_type: :tax_free)
+  ]
+)
+```
+
+### Discounts and fees
+
+The gem is a faithful wrapper of the API's invoice detail format, so it has no
+built-in discount/coupon/delivery/handling concepts. Model them as ordinary line
+items — use a negative `unit_price` for a discount:
+
+```ruby
+Cetustek::Models::InvoiceItem.new(code: 'DISCOUNT', name: '折抵', quantity: 1, unit_price: -30)
+```
+
+### 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
+```
+
+### Query an Invoice by Order ID
+
+```ruby
+response = Cetustek::QueryInvoiceByOrderId.query(order_id)
 ```
 
 ## Development
@@ -72,10 +141,11 @@ result = Cetustek::CreateInvoice.new(invoice_data).execute
 1. Clone this repository
 2. Run `bin/setup` to install dependencies
 3. Run `bin/console` for an interactive prompt to experiment
+4. Run `bundle exec rspec` to run the test suite
 
 ## Requirements
 
-- Ruby >= 2.7.0
+- Ruby >= 3.0.0
 - `ox` gem for XML processing
 - `savon` gem for SOAP services
 

data/lib/cetustek/models/invoice_data.rb

@@ -1,12 +1,25 @@
 # frozen_string_literal: true
 
 module Cetustek
+  # TaxType (稅別) codes accepted by CreateInvoiceV3 (spec V4.16, Table 1).
+  module TaxType
+    TAXABLE = 1            # 應稅
+    ZERO_RATE = 2          # 零稅率(非經海關出口)
+    TAX_FREE = 3           # 免稅
+    SPECIAL = 4            # 應稅(特種稅率) — requires TaxRate
+    ZERO_RATE_CUSTOMS = 5  # 零稅率(經海關出口)
+    MIXED = 9              # 混合(應稅、零稅率與免稅，限收銀機類型發票)
+  end
+
   module Models
     class InvoiceData
+      DEFAULT_TAX_RATE = 0.05
+      DEFAULT_INVOICE_TYPE = '07' # 07: 一般稅額, 08: 特種稅額
+
       attr_reader :order_id, :order_date, :buyer_identifier, :buyer_name,
-                 :buyer_email, :donate_mark, :carrier_type, :carrier_id,
-                 :npo_ban, :items, :payment_type, :total_discount,
-                 :coupon_discount, :delivery_fee, :handling_fee
+                  :buyer_email, :donate_mark, :carrier_type, :carrier_id,
+                  :carrier_id2, :npo_ban, :items, :payment_type,
+                  :tax_type, :tax_rate, :invoice_type
 
       def initialize(attributes = {})
         @order_id = attributes[:order_id]
@@ -17,24 +30,43 @@ module Cetustek
         @donate_mark = attributes[:donate_mark]
         @carrier_type = attributes[:carrier_type]
         @carrier_id = attributes[:carrier_id]
+        @carrier_id2 = attributes[:carrier_id2]
         @npo_ban = attributes[:npo_ban]
         @items = attributes[:items] || []
         @payment_type = attributes[:payment_type]
-        @total_discount = attributes[:total_discount] || 0
-        @coupon_discount = attributes[:coupon_discount] || 0
-        @delivery_fee = attributes[:delivery_fee] || 0
-        @handling_fee = attributes[:handling_fee] || 0
+        @tax_type = attributes[:tax_type] || TaxType::TAXABLE
+        @tax_rate = attributes.fetch(:tax_rate, DEFAULT_TAX_RATE)
+        @invoice_type = attributes[:invoice_type] || DEFAULT_INVOICE_TYPE
+      end
+
+      # 混合稅率發票 (限收銀機)：每筆明細需標註 DType。
+      def mixed_tax?
+        @tax_type.to_i == TaxType::MIXED
       end
     end
 
     class InvoiceItem
-      attr_reader :code, :name, :quantity, :unit_price
+      # Per-item 稅別註記 (DType) used for mixed-tax invoices (TaxType == 9).
+      DTYPE_MAP = {
+        taxable: '',    # 應稅商品 -> 空白
+        zero_rate: 'TZ', # 零稅率商品
+        tax_free: 'TN'   # 免稅商品
+      }.freeze
+
+      attr_reader :code, :name, :quantity, :unit_price, :tax_type
 
       def initialize(attributes = {})
         @code = attributes[:code]
         @name = attributes[:name]
         @quantity = attributes[:quantity]
         @unit_price = attributes[:unit_price]
+        @tax_type = attributes[:tax_type] || :taxable
+      end
+
+      # Returns the DType code: '', 'TZ' or 'TN'.
+      # Accepts the friendly symbols above or a raw code string.
+      def d_type
+        DTYPE_MAP.fetch(@tax_type) { @tax_type.to_s }
       end
     end
   end

data/lib/cetustek/services/invoice_xml_builder.rb

@@ -27,6 +27,13 @@ module Cetustek
         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'
@@ -40,25 +47,26 @@ module Cetustek
       end
 
       def add_basic_info(invoice)
-        invoice << Ox::Raw.new("<OrderId>#{@data.order_id}</OrderId>")
-        invoice << Ox::Raw.new("<OrderDate>#{@data.order_date.strftime('%Y/%m/%d')}</OrderDate>")
+        invoice << raw_tag('OrderId', @data.order_id)
+        invoice << raw_tag('OrderDate', @data.order_date.strftime('%Y/%m/%d'))
       end
 
       def add_buyer_info(invoice)
-        invoice << Ox::Raw.new("<BuyerIdentifier>#{@data.buyer_identifier}</BuyerIdentifier>")
-        invoice << Ox::Raw.new("<BuyerName>#{CGI.escapeHTML(@data.buyer_name)}</BuyerName>")
-        invoice << Ox::Raw.new("<BuyerEmailAddress>#{@data.buyer_email}</BuyerEmailAddress>")
+        invoice << raw_tag('BuyerIdentifier', @data.buyer_identifier)
+        invoice << raw_tag('BuyerName', @data.buyer_name)
+        invoice << raw_tag('BuyerEmailAddress', @data.buyer_email)
       end
 
       def add_invoice_type_info(invoice)
-        invoice << Ox::Raw.new("<DonateMark>#{@data.donate_mark}</DonateMark>")
-        invoice << Ox::Raw.new('<InvoiceType>07</InvoiceType>')
-        invoice << Ox::Raw.new("<CarrierType>#{@data.carrier_type}</CarrierType>")
-        invoice << Ox::Raw.new("<CarrierId1>#{@data.carrier_id}</CarrierId1>")
-        invoice << Ox::Raw.new("<CarrierId2>#{@data.carrier_id2}</CarrierId2>")
-        invoice << Ox::Raw.new("<NPOBAN>#{@data.npo_ban}</NPOBAN>")
-        invoice << Ox::Raw.new('<TaxType>1</TaxType>')
-        invoice << Ox::Raw.new("<PayWay>#{@data.payment_type}</PayWay>")
+        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_id)
+        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)
+        invoice << raw_tag('PayWay', @data.payment_type)
       end
 
       def add_details(invoice)
@@ -68,60 +76,24 @@ module Cetustek
         @data.items.each do |item|
           details << create_product_item(item)
         end
-
-        add_additional_items(details)
       end
 
       def create_product_item(item)
         product = Ox::Element.new('ProductItem')
-        product << Ox::Raw.new("<ProductionCode>#{item.code}</ProductionCode>")
-        product << Ox::Raw.new("<Description>#{CGI.escapeHTML(item.name)}</Description>")
-        product << Ox::Raw.new("<Quantity>#{item.quantity}</Quantity>")
-        product << Ox::Raw.new("<UnitPrice>#{item.unit_price}</UnitPrice>")
+        product << raw_tag('ProductionCode', item.code)
+        product << raw_tag('Description', item.name)
+        product << raw_tag('Quantity', item.quantity)
+        product << raw_tag('UnitPrice', item.unit_price)
+        add_dtype(product, item.d_type)
         product
       end
 
-      def add_additional_items(details)
-        add_discount_item(details) if @data.total_discount.positive?
-        add_coupon_item(details) if @data.coupon_discount.positive?
-        add_delivery_fee_item(details) if @data.delivery_fee.positive?
-        add_handling_fee_item(details) if @data.handling_fee.positive?
-      end
-
-      def add_discount_item(details)
-        discount = Ox::Element.new('ProductItem')
-        discount << Ox::Raw.new('<ProductionCode>DISCOUNT</ProductionCode>')
-        discount << Ox::Raw.new('<Description>折抵金額</Description>')
-        discount << Ox::Raw.new('<Quantity>1</Quantity>')
-        discount << Ox::Raw.new("<UnitPrice>#{@data.total_discount * -1}</UnitPrice>")
-        details << discount
-      end
-
-      def add_coupon_item(details)
-        coupon = Ox::Element.new('ProductItem')
-        coupon << Ox::Raw.new('<ProductionCode>COUPON</ProductionCode>')
-        coupon << Ox::Raw.new('<Description>分享折讓</Description>')
-        coupon << Ox::Raw.new('<Quantity>1</Quantity>')
-        coupon << Ox::Raw.new("<UnitPrice>#{@data.coupon_discount * -1}</UnitPrice>")
-        details << coupon
-      end
-
-      def add_delivery_fee_item(details)
-        delivery = Ox::Element.new('ProductItem')
-        delivery << Ox::Raw.new('<ProductionCode>DELIVERY_FEE</ProductionCode>')
-        delivery << Ox::Raw.new('<Description>運費</Description>')
-        delivery << Ox::Raw.new('<Quantity>1</Quantity>')
-        delivery << Ox::Raw.new("<UnitPrice>#{@data.delivery_fee}</UnitPrice>")
-        details << delivery
-      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?
 
-      def add_handling_fee_item(details)
-        handling = Ox::Element.new('ProductItem')
-        handling << Ox::Raw.new('<ProductionCode>HANDLING_FEE</ProductionCode>')
-        handling << Ox::Raw.new('<Description>手續費</Description>')
-        handling << Ox::Raw.new('<Quantity>1</Quantity>')
-        handling << Ox::Raw.new("<UnitPrice>#{@data.handling_fee}</UnitPrice>")
-        details << handling
+        product << raw_tag('DType', value)
       end
     end
   end

data/lib/cetustek/version.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: cetustek
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Zac
 bindir: exe
 cert_chain: []
-date: 2025-01-22 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ox
@@ -51,6 +51,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
 description: 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.
@@ -60,6 +74,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".rspec"
 - CHANGELOG.md
 - README.md
 - Rakefile
@@ -95,7 +110,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 4.0.10
 specification_version: 4
 summary: A Ruby gem for handling electronic invoice operations
 test_files: []