adding untaxed invoices and a nop tax calc mode

- Allows for untaxed invoices
- Allows for single-tax invoices with slight rounding errors

Author: halfbyte

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 3.4.0
+
+- [FEATURE] Allow for "untaxable" invoices. This is, for example the case when you deliver services to US states that don't tax these, or if you're falling below the registration threshold.
+- [FEATURE] To support valid "untaxable" invoices, `:tax_id`, `:global_id` and `:global_id_scheme_id` are introduced on `TradeParty` as attributes. ZUGFeRD does not allow VAT ids on invoices that are untaxable, so you need a global id (and other validators want you to add the local tax id as well, but that's mandatory, I think). This could be a SWIFT id, for example, which would be an IBAN for EU folks. (IANAL!) 
+- [FEATURE] Introduce tax_calculation_method = :NONE, which skips collecting taxes from line items and just uses the global values. It also skips some of the validations. This is a hack-ish solution to a problem I ran into where the invoicing service calculated the VAT and net amounts backwards from a round gross amount, resulting in rounding errors when trying to calculate them the correct way round. This is easier to use when you only have one tax rate and all the values are already known.
+
 ## 3.3.0
 
 - [FEATURE] Allow for vertical tax calculation. PR by @RST-J

README.md

@@ -7,7 +7,7 @@ See tests for examples.
 1. This is an opinionated library optimised for my very specific usecase
 2. While I did start to add some validations to make sure you can't input absolute garbage into this, I cannot guarantee factual (as in taxation law) correctness of the resulting XML.
 1. The library, for ZUGFeRD 2.x, currently only supports the EN16931 variant. This is probably what you want as well. PRs welcome.
-3. This does not contain any code to attach the XML to a PDF file, mainly because I have yet to find a ruby library to do that. For software that does this, take a look at [this python library](https://github.com/akretion/factur-x).
+3. This does not contain any code to attach the XML to a PDF file, mainly because I have yet to find a ruby library to do that. For software that does this, take a look at [this python library](https://github.com/akretion/factur-x) or [this Java library which also does extended validation](https://mustangproject.org)
 
 ## Contributors
 

lib/secretariat/constants.rb

@@ -66,7 +66,7 @@ module Secretariat
 
   # For the background of vertical and horizontal tax calculation see https://hilfe.pacemo.de/de-form/articles/3489851-rundungsfehler-bei-rechnungen
   # The idea of introducing an unknown value is that this could be inferred from the given invoice total and line items by probing both variants and selecting the matching one - or reporting a taxation error if neither matches.
-  TAX_CALCULATION_METHODS = %i[HORIZONTAL VERTICAL UNKNOWN].freeze
+  TAX_CALCULATION_METHODS = %i[HORIZONTAL VERTICAL NONE UNKNOWN].freeze
 
   UNIT_CODES = {
     :PIECE => "C62",

lib/secretariat/invoice.rb

@@ -65,11 +65,26 @@ def tax_category_code(tax, version: 2)
 
     def taxes
       taxes = {}
+      # Shortcut for cases where invoices only have one tax and the calculation is off by a cent because of rounding errors
+      # (This can happen if the VAT and the net amount is calculated backwards from a round gross amount)
+      if tax_calculation_method == :NONE
+        tax = Tax.new(tax_percent: BigDecimal(tax_percent || BigDecimal(0)), tax_category: tax_category)
+        tax.base_amount = BigDecimal(basis_amount)
+        tax.tax_amount = BigDecimal(tax_amount || 0)
+        return [tax]
+      end
+
       line_items.each do |line_item|
-        taxes[line_item.tax_percent] = Tax.new(tax_percent: BigDecimal(line_item.tax_percent), tax_category: line_item.tax_category) if taxes[line_item.tax_percent].nil?
-        taxes[line_item.tax_percent].tax_amount += BigDecimal(line_item.tax_amount)
-        taxes[line_item.tax_percent].base_amount += BigDecimal(line_item.net_amount) * line_item.quantity
+        if line_item.tax_percent.nil?
+          taxes['0'] = Tax.new(tax_percent: BigDecimal(0), tax_category: line_item.tax_category, tax_amount: BigDecimal(0)) if taxes['0'].nil?
+          taxes['0'].base_amount += BigDecimal(line_item.net_amount) * line_item.quantity
+        else
+          taxes[line_item.tax_percent] = Tax.new(tax_percent: BigDecimal(line_item.tax_percent), tax_category: line_item.tax_category) if taxes[line_item.tax_percent].nil?
+          taxes[line_item.tax_percent].tax_amount += BigDecimal(line_item.tax_amount)
+          taxes[line_item.tax_percent].base_amount += BigDecimal(line_item.net_amount) * line_item.quantity
+        end
       end
+      
       if tax_calculation_method == :VERTICAL
         taxes.values.map do |tax|
           tax.tax_amount = (tax.base_amount * tax.tax_percent / 100).round(2)
@@ -98,12 +113,14 @@ def valid?
         @errors << "Base amount and summed tax base amount deviate: #{basis} / #{summed_tax_base_amount}"
         return false
       end
-      taxes.each do |tax|
-        calc_tax = tax.base_amount * BigDecimal(tax.tax_percent) / BigDecimal(100)
-        calc_tax = calc_tax.round(2)
-        if tax.tax_amount != calc_tax
-          @errors << "Tax amount and calculated tax amount deviate for rate #{tax.tax_percent}: #{tax.tax_amount} / #{calc_tax}"
-          return false
+      if tax_calculation_method != :NONE
+        taxes.each do |tax|
+          calc_tax = tax.base_amount * BigDecimal(tax.tax_percent) / BigDecimal(100)
+          calc_tax = calc_tax.round(2)
+          if tax.tax_amount != calc_tax
+            @errors << "Tax amount and calculated tax amount deviate for rate #{tax.tax_percent}: #{tax.tax_amount} / #{calc_tax}"
+            return false
+          end
         end
       end
       grand_total = BigDecimal(grand_total_amount)
@@ -250,9 +267,10 @@ def to_xml(version: 1, validate: true)
                   end
                   Helpers.currency_element(xml, 'ram', 'BasisAmount', tax.base_amount, currency_code, add_currency: version == 1)
                   xml['ram'].CategoryCode tax_category_code(tax, version: version)
-
-                  percent = by_version(version, 'ApplicablePercent', 'RateApplicablePercent')
-                  xml['ram'].send(percent, Helpers.format(tax.tax_percent))
+                  # unless tax.untaxable?
+                    percent = by_version(version, 'ApplicablePercent', 'RateApplicablePercent')
+                    xml['ram'].send(percent, Helpers.format(tax.tax_percent))
+                  # end
                 end
               end
               if version == 2 && service_period_start && service_period_end

lib/secretariat/line_item.rb

@@ -14,8 +14,6 @@
 limitations under the License.
 =end
 
-
-
 require 'bigdecimal'
 module Secretariat
 
@@ -63,13 +61,15 @@ def valid?
           return false
         end
       end
-
-      calculated_tax = charge_price * BigDecimal(tax_percent) / BigDecimal(100)
-      calculated_tax = calculated_tax.round(2)
-      calculated_tax = -calculated_tax if quantity.negative?
-      if calculated_tax != tax
-        @errors << "Tax and calculated tax deviate: #{tax} / #{calculated_tax}"
-        return false
+      if tax_category != :UNTAXEDSERVICE
+        self.tax_percent ||= BigDecimal(0)
+        calculated_tax = charge_price * BigDecimal(tax_percent) / BigDecimal(100)
+        calculated_tax = calculated_tax.round(2)
+        calculated_tax = -calculated_tax if quantity.negative?
+        if calculated_tax != tax
+          @errors << "Tax and calculated tax deviate: #{tax} / #{calculated_tax}"
+          return false
+        end
       end
       return true
     end
@@ -85,11 +85,17 @@ def tax_category_code(version: 2)
       TAX_CATEGORY_CODES[tax_category] || 'S'
     end
 
+    def untaxable?
+      tax_category == :UNTAXEDSERVICE
+    end
+
     def to_xml(xml, line_item_index, version: 2, validate: true)
       net_price = net_amount && BigDecimal(net_amount)
       gross_price = gross_amount && BigDecimal(gross_amount)
       charge_price = charge_amount && BigDecimal(charge_amount)
 
+      self.tax_percent ||= BigDecimal(0)
+
       if net_price&.zero?
         self.tax_percent = 0
       end
@@ -170,10 +176,10 @@ def to_xml(xml, line_item_index, version: 2, validate: true)
           xml['ram'].ApplicableTradeTax do
             xml['ram'].TypeCode 'VAT'
             xml['ram'].CategoryCode tax_category_code(version: version)
-
-            percent = by_version(version, 'ApplicablePercent', 'RateApplicablePercent')
-            xml['ram'].send(percent,Helpers.format(tax_percent))
-
+            unless untaxable?
+              percent = by_version(version, 'ApplicablePercent', 'RateApplicablePercent')
+              xml['ram'].send(percent,Helpers.format(tax_percent))            
+            end
           end
           monetary_summation = by_version(version, 'SpecifiedTradeSettlementMonetarySummation', 'SpecifiedTradeSettlementLineMonetarySummation')
           xml['ram'].send(monetary_summation) do

lib/secretariat/tax.rb

@@ -30,5 +30,10 @@ def initialize(*)
       self.tax_amount = 0
       self.base_amount = 0
     end
+
+    def untaxable?
+      tax_category == :UNTAXEDSERVICE
+    end
+
   end
 end

lib/secretariat/trade_party.rb

@@ -16,10 +16,15 @@
 
 module Secretariat
   TradeParty = Struct.new('TradeParty',
-    :name, :street1, :street2, :city, :postal_code, :country_id, :vat_id,
+    :name, :street1, :street2, :city, :postal_code, :country_id, :vat_id, :global_id, :global_id_scheme_id, :tax_id,
     keyword_init: true,
   ) do
     def to_xml(xml, exclude_tax: false, version: 2)
+      if global_id && global_id != '' && global_id_scheme_id && global_id_scheme_id != ''
+        xml['ram'].GlobalID(schemeID: global_id_scheme_id) do
+          xml.text(global_id)
+        end
+      end
       xml['ram'].Name name
       xml['ram'].PostalTradeAddress do
         xml['ram'].PostcodeCode postal_code
@@ -36,9 +41,13 @@ def to_xml(xml, exclude_tax: false, version: 2)
             xml.text(vat_id)
           end
         end
+      elsif tax_id && tax_id != ''
+        xml['ram'].SpecifiedTaxRegistration do
+          xml['ram'].ID(schemeID: 'FC') do
+            xml.text(tax_id)
+          end
+        end
       end
     end
   end
-
-
 end

test/invoice_test.rb

@@ -63,7 +63,6 @@ def make_foreign_invoice(tax_category: :TAXEXEMPT)
         city: 'Hamburg',
         postal_code: '20253',
         country_id: 'DE',
-        vat_id: 'DE304755032'
       )
       buyer = TradeParty.new(
         name: 'Another Corp Inc.',
@@ -362,6 +361,10 @@ def test_simple_eu_invoice_v2
         pp e.errors
       end
 
+      assert_match(/<ram:CategoryCode>AE<\/ram:CategoryCode>/, xml)
+      assert_match(/<ram:ExemptionReason>Reverse Charge<\/ram:ExemptionReason>/, xml)
+      assert_match(/<ram:RateApplicablePercent>/, xml)
+
       v = Validator.new(xml, version: 2)
       errors = v.validate_against_schema
       if !errors.empty?
@@ -375,7 +378,7 @@ def test_simple_eu_invoice_v2
       puts e.errors
     end
 
-    def test_simple_foreign_invoice_v2
+    def test_simple_foreign_invoice_v2_taxexpempt
       begin
         xml = make_foreign_invoice(tax_category: :TAXEXEMPT).to_xml(version: 2)
       rescue ValidationError => e
@@ -384,6 +387,30 @@ def test_simple_foreign_invoice_v2
 
       assert_match(/<ram:CategoryCode>E<\/ram:CategoryCode>/, xml)
       assert_match(/<ram:ExemptionReason>VAT exempt<\/ram:ExemptionReason>/, xml)
+      assert_match(/<ram:RateApplicablePercent>/, xml)
+
+      v = Validator.new(xml, version: 2)
+      errors = v.validate_against_schema
+      if !errors.empty?
+        puts xml
+        errors.each do |error|
+          puts error
+        end
+      end
+      assert_equal [], errors
+    rescue ValidationError => e
+      puts e.errors
+    end
+    
+    def test_simple_foreign_invoice_v2_untaxed
+      begin
+        xml = make_foreign_invoice(tax_category: :UNTAXEDSERVICE).to_xml(version: 2)
+      rescue ValidationError => e
+        pp e.errors
+      end
+
+      assert_match(/<ram:CategoryCode>O<\/ram:CategoryCode>/, xml)
+      assert_match(/<ram:ExemptionReason>Not subject to VAT<\/ram:ExemptionReason>/, xml)
 
       v = Validator.new(xml, version: 2)
       errors = v.validate_against_schema