cetustek 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 722407201f6462aed26f91e61295dc87fcfdc970db2b55adf8aa73f4a4840f1a
-  data.tar.gz: ab37a4849d55a493854202d343c2cf082fb118813eea9d491e09970209317066
+  metadata.gz: 5134abbcc8b7229469df2b15f6efa704828f745e499f2609e04251bca8ed90c0
+  data.tar.gz: 50312823ef3166581b9518d97955ce8f839a80ad25e3a1f155fd48ea102a919d
 SHA512:
-  metadata.gz: db34fb0378f5fd87b4c42cec44306b69afaa09ceb9ade280993f1618ed487e0c92ea6e61f3645747277e4a1e548b736f7806ced8e659c4a84a0d1a98da3efbe8
-  data.tar.gz: 5164f077cb9fff85c4879ea31e0f51710d03b6b621545c2b757deac19f3833e7f50802470577812ca95cfccb8742b271dc71c418625a8e9b5947f08e8c22bf2a
+  metadata.gz: b35ecc731affbcf77b48d858de62eae3e2e9dfe8f5bc328af30af2d6d9b27e51abe03de5633eedac8fc60106b9b50647b1c5b1a640c70e965b8a2267ff856685
+  data.tar.gz: 5192ff08c159704e14548beb39bfb132acb4bd929308ada3f882edbd18132fe1123997030792897102c77402e5a1aa7c11ea48a8015f967609b3121ee006a263

data/.rspec

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

data/CHANGELOG.md

@@ -5,6 +5,46 @@ 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.4.0] - 2026-06-29
+
+### Added
+- `Cetustek::QueryInvoice.query(invoice_number, invoice_year)` — 查詢發票資訊 (§2.4)
+- `Cetustek::QueryInvoiceNumberByOrderId.query(order_id)` — 以訂單編號查發票號碼 (§2.6)
+- `Cetustek::CreateAllowance.new(allowance_data, check_allowance:).execute` — 開立折讓單 (§2.9)
+- `Cetustek::CancelAllowance.new(allowance_number, reason).execute` — 作廢折讓單 (§2.10)
+- `Cetustek::QueryAllowance.query(allowance_number)` — 查詢折讓資料 (§2.11)
+- `Cetustek::PhoneBarcode.valid?(phone_code)` — 手機條碼驗證 (§3.1, HTTP/JSON, not SOAP)
+- `Cetustek::Models::AllowanceData` value object and an optional `unit` on `InvoiceItem`
+
+### Changed
+- `hastax` is now taken from the order via `InvoiceData.new(hastax:)` (default `1`,
+  tax-inclusive) instead of being hardcoded — e.g. tax-exclusive/tax-free purchases
+  can send `0`
+- All generated XML is forced to UTF-8 encoding, preventing `Encoding::CompatibilityError`
+  from Savon when invoices/allowances contain Chinese text
+
+## [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

@@ -1,5 +1,8 @@
 # Cetustek
 
+[![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.
 
 ## Features
@@ -44,7 +47,7 @@ end
 
 ## Usage
 
-### Cancel an Invoice
+### Issue an Invoice
 
 ```ruby
 invoice = YourInvoiceModel.find(invoice_id)
@@ -54,7 +57,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 +70,110 @@ 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 invoices
+
+```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
+```
+
+### Tax-inclusive vs tax-exclusive prices (`hastax`)
+
+`hastax` comes from the order, not a fixed value: `1` (default) means the item
+`unit_price`s already include tax; `0` means they are tax-exclusive (e.g. a tax-free
+purchase). Set it on `InvoiceData`:
+
+```ruby
+Cetustek::Models::InvoiceData.new(hastax: 0, items: [...])
+```
+
+### Allowances (折讓單)
+
+```ruby
+allowance = Cetustek::Models::AllowanceData.new(
+  allowance_number: 'AA20240216000001',
+  allowance_date: Time.zone.today,
+  invoice_number: 'AA10000000',
+  invoice_year: '2024',
+  tax_type: 1,
+  reason: '退回',
+  items: [
+    Cetustek::Models::InvoiceItem.new(code: '0001', name: '禮券', quantity: 1, unit: '本', unit_price: 800)
+  ]
+)
+Cetustek::CreateAllowance.new(allowance).execute              # => "A0" on success
+Cetustek::CancelAllowance.new('AA20240216000001', '明細錯誤').execute # => "C0" on success
+Cetustek::QueryAllowance.query('AA20240216000001')
+```
+
+### Mobile barcode validation (手機條碼)
+
+```ruby
+Cetustek::PhoneBarcode.valid?('/ABC123')  # => true / false
 ```
 
 ## Development
@@ -72,10 +181,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/cancel_allowance.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'ox'
+require 'cgi'
+
+module Cetustek
+  # 2.10 CancelAllowance 作廢折讓單. Returns the result code (C0 = success).
+  class CancelAllowance
+    def initialize(allowance_number, reason)
+      @allowance_number = allowance_number
+      @reason = reason
+    end
+
+    def execute
+      perform
+      @response.body[:cancel_allowance_response][:return]
+    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}>")
+    end
+  end
+end

data/lib/cetustek/cancel_invoice.rb

@@ -42,7 +42,7 @@ module Cetustek
       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)
+      @xml = Ox.dump(doc).force_encoding('UTF-8')
     end
 
     def analize_response

data/lib/cetustek/create_allowance.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'ox'
+require 'cgi'
+
+module Cetustek
+  # 2.9 CreateAllowance 開立折讓單. Returns the result code (A0 = success).
+  # check_allowance: 0 = confirmed allowance (default), 1 = unconfirmed.
+  class CreateAllowance
+    def initialize(allowance_data, check_allowance: 0)
+      @data = allowance_data
+      @check_allowance = check_allowance
+    end
+
+    def execute
+      perform
+      @response.body[:create_allowance_response][:return]
+    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')
+    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)
+        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

@@ -13,7 +13,7 @@ module Cetustek
 
     def execute
       xml = Services::InvoiceXmlBuilder.new(@invoice_data).build
-      response = Services::InvoiceService.new(xml, @invoice_data.order_id).create
+      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]

data/lib/cetustek/models/allowance_data.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative 'invoice_data'
+
+module Cetustek
+  module Models
+    # Request data for CreateAllowance (開立折讓單), spec AVM-26-03 Table 15/16.
+    # Line items reuse InvoiceItem (code/name/quantity/unit/unit_price).
+    class AllowanceData
+      attr_reader :allowance_number, :allowance_date, :invoice_number,
+                  :invoice_year, :buyer_address, :buyer_email, :tax_type,
+                  :reason, :round_num, :items
+
+      def initialize(attributes = {})
+        @allowance_number = attributes[:allowance_number]
+        @allowance_date = attributes[:allowance_date]
+        @invoice_number = attributes[:invoice_number]
+        @invoice_year = attributes[:invoice_year]
+        @buyer_address = attributes[:buyer_address]
+        @buyer_email = attributes[:buyer_email]
+        @tax_type = attributes[:tax_type] || TaxType::TAXABLE
+        @reason = attributes[:reason]
+        @round_num = attributes[:round_num] # optional 金額計算位數
+        @items = attributes[:items] || []
+      end
+    end
+  end
+end

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, :hastax
 
       def initialize(attributes = {})
         @order_id = attributes[:order_id]
@@ -17,24 +30,47 @@ 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
+        # hastax: 0 = item prices are tax-exclusive, 1 = tax-inclusive.
+        # Comes from the order (e.g. tax-free purchases), not a fixed value.
+        @hastax = attributes.fetch(:hastax, 1)
+      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, :unit
 
       def initialize(attributes = {})
         @code = attributes[:code]
         @name = attributes[:name]
         @quantity = attributes[:quantity]
         @unit_price = attributes[:unit_price]
+        @unit = attributes[:unit]
+        @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/phone_barcode.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+
+module Cetustek
+  # 3.1 手機條碼 API — validates a mobile barcode (手機條碼) against the
+  # 財政部 platform. Plain HTTP GET returning JSON, NOT the SOAP service.
+  class PhoneBarcode
+    ENDPOINT = 'https://api.cetustek.com.tw/PhoneBar.php'
+    AUTH_KEY = 'Cetus9Phone1API7' # spec: fixed for now, may become per-account
+
+    def self.valid?(phone_code)
+      new(phone_code).valid?
+    end
+
+    def initialize(phone_code)
+      @phone_code = phone_code
+    end
+
+    # true when the barcode exists (isExist == 'Y').
+    def valid?
+      response['isExist'] == 'Y'
+    end
+
+    # Full parsed JSON response: { "isExist", "code", "msg", "TxID", "version" }.
+    def response
+      uri = URI(ENDPOINT)
+      uri.query = URI.encode_www_form(
+        rentid: Cetustek.config.username,
+        authkey: AUTH_KEY,
+        phonecode: @phone_code
+      )
+      JSON.parse(Net::HTTP.get_response(uri).body)
+    end
+  end
+end

data/lib/cetustek/queries.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Cetustek
+  # Read-only SOAP queries. Each returns the raw Savon response, mirroring
+  # QueryInvoiceByOrderId. Spec AVM-26-03 §2.4 / §2.6 / §2.11.
+  module Queries
+    def soap_client
+      Savon.client(wsdl: Cetustek.config.url, open_timeout: 300, read_timeout: 300)
+    end
+
+    def source
+      Cetustek.config.site_id + Cetustek.config.password
+    end
+
+    def rentid
+      Cetustek.config.username
+    end
+  end
+
+  # 2.4 QueryInvoice 查詢發票資訊 (by invoice number + year)
+  class QueryInvoice
+    extend Queries
+
+    def self.query(invoice_number, invoice_year)
+      soap_client.call(:query_invoice, message: {
+                         invoicenumber: invoice_number,
+                         invoiceyear: invoice_year,
+                         source: source,
+                         rentid: rentid
+                       })
+    end
+  end
+
+  # 2.6 QueryInvoiceNumberbyOrderid 以訂單編號查詢發票號碼
+  class QueryInvoiceNumberByOrderId
+    extend Queries
+
+    def self.query(order_id)
+      soap_client.call(:query_invoice_number_by_orderid, message: {
+                         orderid: order_id,
+                         source: source,
+                         rentid: rentid
+                       })
+    end
+  end
+
+  # 2.11 QueryAllowance 查詢折讓資料
+  class QueryAllowance
+    extend Queries
+
+    def self.query(allowance_number)
+      soap_client.call(:query_allowance, message: {
+                         allowancenumber: allowance_number,
+                         source: source,
+                         rentid: rentid
+                       })
+    end
+  end
+end

data/lib/cetustek/services/invoice_service.rb

@@ -6,9 +6,10 @@ require 'logger'
 module Cetustek
   module Services
     class InvoiceService
-      def initialize(xml, order_id = nil)
+      def initialize(xml, order_id = nil, hastax = 1)
         @xml = xml
         @order_id = order_id
+        @hastax = hastax
       end
 
       def create
@@ -33,7 +34,7 @@ module Cetustek
           invoicexml: @xml,
           source: Cetustek.config.site_id + Cetustek.config.password,
           rentid: Cetustek.config.username,
-          hastax: 1
+          hastax: @hastax
         })
       end
 

data/lib/cetustek/services/invoice_xml_builder.rb

@@ -15,7 +15,7 @@ module Cetustek
         doc << create_xml_instruct
         doc << create_invoice_element
 
-        Ox.dump(doc)
+        Ox.dump(doc).force_encoding('UTF-8')
       end
 
       private
@@ -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.4.0"
 end

data/lib/cetustek.rb

@@ -2,9 +2,14 @@
 
 require_relative "cetustek/version"
 require_relative "cetustek/configuration"
+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/create_allowance"
+require_relative "cetustek/cancel_allowance"
+require_relative "cetustek/phone_barcode"
 
 module Cetustek
   class Error < StandardError; end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: cetustek
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.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,14 +74,20 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".rspec"
 - CHANGELOG.md
 - README.md
 - Rakefile
 - lib/cetustek.rb
+- lib/cetustek/cancel_allowance.rb
 - lib/cetustek/cancel_invoice.rb
 - lib/cetustek/configuration.rb
+- lib/cetustek/create_allowance.rb
 - lib/cetustek/create_invoice.rb
+- lib/cetustek/models/allowance_data.rb
 - lib/cetustek/models/invoice_data.rb
+- lib/cetustek/phone_barcode.rb
+- lib/cetustek/queries.rb
 - lib/cetustek/query_invoice_by_order_id.rb
 - lib/cetustek/services/invoice_service.rb
 - lib/cetustek/services/invoice_xml_builder.rb
@@ -95,7 +115,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: []