cetustek 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc27cec134bbdcde72328147677ace14f302f2423128209d8ec0ddd190ceeca7
-  data.tar.gz: cfb7115017ef61ba4c928459f1d8d8815bf5a1fd616cc050a8be012a942aac3e
+  metadata.gz: 2914b87b1c342a5309f39629998f26cf081179b02c064177f44628c0d1853329
+  data.tar.gz: e65afdb10fcfa7c358f7eaa7f953169f0265b6f69e56b624b75e5fe4ea1fc61e
 SHA512:
-  metadata.gz: 1a350443ea05a452ec354e1f9d7a5cb624cd04087baecef9f756c715350497bdc6d9b0fbedc41ee2087d711aba66b72ecfbb7c207d239d8b8278266335a3eae4
-  data.tar.gz: 5ac422d52d5d11b0bf71d97186ab9bd257f667ec135c942f87df934f66cb4f7653a40cda4794d62171aa72d905f98d60fe46e416409399e07abbfe679a063130
+  metadata.gz: 5fe69cd1d22f538861b5dde8124133db53f618b059fc6cb5f7ed6cbe85c0f894c6c4aefb7eb1fda410d883a98f4f910f049a5e9aa0687b5108f7a407f16b209c
+  data.tar.gz: 0b64ceeeda241d5f7780e8b7ced545f2309657f3dd3dfcce7b7d631658ed6b1144b2481cd510920ed08ce863970e448c65d9ec485950a41c6ea57eddbeff5f14

data/CHANGELOG.md

@@ -5,6 +5,32 @@ 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.5.0] - 2026-06-30
+
+### Added
+- `Cetustek::PayWay` constants for the 付款方式 codes (spec AVM-26-03 Table 4):
+  `CASH`/`ATM`/`CREDIT_CARD`/`CVS`/`OTHER`/`E_PAYMENT` plus `APPLE_PAY`, `LINE_PAY`,
+  `GOOGLE_PAY`, `JKO_PAY`, `TAIWAN_PAY`, etc. Convenience only — `payment_type` still
+  accepts any raw value, so new platform codes need no gem update.
+
+## [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

data/README.md

@@ -1,5 +1,9 @@
 # Cetustek
 
+[![Gem Version](https://img.shields.io/gem/v/cetustek)](https://rubygems.org/gems/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
@@ -112,6 +116,24 @@ Cetustek::Models::InvoiceData.new(
 )
 ```
 
+### Payment method (`payment_type` / PayWay)
+
+`payment_type` accepts any raw code, or use `Cetustek::PayWay` for readability
+(`payment_type: Cetustek::PayWay::LINE_PAY`):
+
+| Constant | Code | | Constant | Code |
+|----------|------|-|----------|------|
+| `CASH` | 1 | | `GOOGLE_PAY` | `G` |
+| `ATM` | 2 | | `JKO_PAY` | `J` |
+| `CREDIT_CARD` | 3 | | `LINE_PAY` | `L` |
+| `CVS` | 4 | | `PI_WALLET` | `P` |
+| `OTHER` | 5 | | `SAMSUNG_PAY` | `S` |
+| `E_PAYMENT` | 6 | | `TAIWAN_PAY` | `T` |
+| `APPLE_PAY` | `A` | | `EASY_WALLET` | `U` |
+| `AFTEE` | `E` | | `PX_PAY` | `W` |
+| | | | `QUAN_PAY` | `X` |
+| | | | `COIN_CARD` | `Z` |
+
 ### Discounts and fees
 
 The gem is a faithful wrapper of the API's invoice detail format, so it has no
@@ -130,10 +152,47 @@ Cetustek::Models::InvoiceItem.new(code: 'DISCOUNT', name: '折抵', quantity: 1,
 Cetustek::CancelInvoice.new(invoice).execute
 ```
 
-### Query an Invoice by Order ID
+### 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
-response = Cetustek::QueryInvoiceByOrderId.query(order_id)
+Cetustek::PhoneBarcode.valid?('/ABC123')  # => true / false
 ```
 
 ## Development

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

@@ -11,6 +11,30 @@ module Cetustek
     MIXED = 9              # 混合(應稅、零稅率與免稅，限收銀機類型發票)
   end
 
+  # PayWay (付款方式) codes for CreateInvoiceV3, spec AVM-26-03 Table 4.
+  # Codes are mixed: 1-6 are integers, A-Z are strings. Convenience constants
+  # only — InvoiceData#payment_type still accepts any raw value.
+  module PayWay
+    CASH = 1          # 現金
+    ATM = 2           # ATM
+    CREDIT_CARD = 3   # 信用卡
+    CVS = 4           # 超商代收
+    OTHER = 5         # 其他
+    E_PAYMENT = 6     # 電子支付
+    APPLE_PAY = 'A'   # Apple Pay
+    AFTEE = 'E'       # 先享後付 Aftee
+    GOOGLE_PAY = 'G'  # Google Pay
+    JKO_PAY = 'J'     # 街口支付
+    LINE_PAY = 'L'    # Line Pay
+    PI_WALLET = 'P'   # Pi 拍錢包、慢點付
+    SAMSUNG_PAY = 'S' # Samsung Pay
+    TAIWAN_PAY = 'T'  # 台灣 Pay
+    EASY_WALLET = 'U' # 悠遊付
+    PX_PAY = 'W'      # 全盈+PAY
+    QUAN_PAY = 'X'    # 全支付
+    COIN_CARD = 'Z'   # 銀角零卡
+  end
+
   module Models
     class InvoiceData
       DEFAULT_TAX_RATE = 0.05
@@ -19,7 +43,7 @@ module Cetustek
       attr_reader :order_id, :order_date, :buyer_identifier, :buyer_name,
                   :buyer_email, :donate_mark, :carrier_type, :carrier_id,
                   :carrier_id2, :npo_ban, :items, :payment_type,
-                  :tax_type, :tax_rate, :invoice_type
+                  :tax_type, :tax_rate, :invoice_type, :hastax
 
       def initialize(attributes = {})
         @order_id = attributes[:order_id]
@@ -37,6 +61,9 @@ module Cetustek
         @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。
@@ -53,13 +80,14 @@ module Cetustek
         tax_free: 'TN'   # 免稅商品
       }.freeze
 
-      attr_reader :code, :name, :quantity, :unit_price, :tax_type
+      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
 

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

data/lib/cetustek/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cetustek
-  VERSION = "0.3.0"
+  VERSION = "0.5.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,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cetustek
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Zac
@@ -79,10 +79,15 @@ files:
 - 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