secretariat 3.2.0 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8fb7cefb10c5f0b91d7b501d0501be8d52094de356e29f4bf0bbacb08bff3f25
-  data.tar.gz: 5ac439e6180ad5c51a6dcc6b835f28ca7b9ee4d63d4e42734ef186502a0dfd63
+  metadata.gz: f1a42571c7c3ceb77877659b076fbd8974ee661843dbc4f4d294012163a4c99f
+  data.tar.gz: 871cf260400cdf9470c867572a77d6ac5d109886b30b9d99120bbbfa94b5f950
 SHA512:
-  metadata.gz: 9df593f5068171fb4d6f7aaaf114981eb08edc51e621e1f0f782b8615ce461f16a41e6c80b3557dbac2271805b5e1d22f56807ef35503cb67a07c7ba89d8a75f
-  data.tar.gz: 2bc606ddd72a5f442a8c2c042859a566a0da3cff6a9e20b34b3b95f31cd9e0516fba1ab8b01b15ce3bf5e29c27bc562bb88a241504ccd34963d085d85fc02a06
+  metadata.gz: e69622419e9e48946ddf0dc4921515a02fa3e8c1f53cd1fd23cd14c89d7f2470718e8d220a4c9594142a768db4c143452efd93607917b230c28e9bb647ec537d
+  data.tar.gz: f5c1da6eea2d10742eebb2ae95993026f74ee6968ac630caaa2f38face0c26b03e401d6204752b14e816af8c408d8052843e77071bc6b68f37200bd3607099f6

data/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
 

data/lib/secretariat/attachment.rb

@@ -0,0 +1,83 @@
+=begin
+Copyright Jan Krutisch
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+=end
+
+
+require 'mime/types'
+
+module Secretariat
+  Attachment = Struct.new('Attachment',
+    :filename,
+    :type_code,
+    :base64,
+
+    keyword_init: true
+  ) do
+    include Versioner
+
+    def errors
+      @errors
+    end
+
+    def valid?
+      @errors = []
+
+      @errors << "the attribute filename needs to be present" if filename.nil? || filename == ''
+      @errors << "the attribute type_code needs to be present" if type_code.nil? || type_code == ''
+      @errors << "the attribute base64 needs to be present" if base64.nil? || base64 == ''
+
+      if type_code.to_i != 916
+        @errors << "we only support type_code 916"
+        return false
+      end
+
+      if mime_code.nil?
+        @errors << "cannot determine content type for filename: #{filename}"
+        return false
+      end
+      
+      if !ALLOWED_MIME_TYPES.include?(mime_code)
+        @errors << "the mime_code '#{mime_code}' is not allowed"
+        return false
+      end
+
+      return true
+    end
+
+    def mime_code
+      type_for = MIME::Types.type_for(filename).first
+      return if type_for.nil?
+
+      type_for.content_type
+    end
+
+    def to_xml(xml, attachment_index, version: 2, validate: true)
+      if validate && !valid?
+        pp errors
+        raise ValidationError.new("Attachment #{attachment_index} is invalid", errors)
+      end
+
+      xml['ram'].AdditionalReferencedDocument do
+        xml['ram'].IssuerAssignedID filename
+        xml['ram'].TypeCode type_code
+        xml['ram'].Name filename
+        xml['ram'].AttachmentBinaryObject(mimeCode: mime_code, filename: filename) do
+          xml.text(base64)
+        end
+      end
+    end
+  end
+end

data/lib/secretariat/constants.rb

@@ -15,6 +15,14 @@ limitations under the License.
 =end
 
 module Secretariat
+  ALLOWED_MIME_TYPES = [
+    "application/pdf",
+    "application/vnd.oasis.opendocument.spreadsheet",
+    "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    "image/jpeg",
+    "image/png",
+    "text/csv"
+  ]
 
   TAX_CATEGORY_CODES = {
    :STANDARDRATE => "S",
@@ -45,15 +53,21 @@ module Secretariat
    :DEBITADVICE => "31",
    :CREDITCARD => "48",
    :DEBIT => "49",
-   :COMPENSATION => "97",
+   :COMPENSATION => "97"
   }
 
   TAX_EXEMPTION_REASONS = {
     :REVERSECHARGE => 'Reverse Charge',
     :INTRACOMMUNITY => 'Intra-community transaction',
-    :EXPORT => 'Export outside the EU'
+    :EXPORT => 'Export outside the EU',
+    :TAXEXEMPT => 'VAT exempt',
+    :UNTAXEDSERVICE => 'Not subject to VAT'
   }
 
+  # 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 NONE UNKNOWN].freeze
+
   UNIT_CODES = {
     :PIECE => "C62",
     :DAY => "DAY",

data/lib/secretariat/invoice.rb

@@ -28,6 +28,7 @@ module Secretariat
     :line_items,
     :currency_code,
     :payment_type,
+    :payment_reference,
     :payment_text,
     :payment_terms_text,
     :payment_due_date,
@@ -40,7 +41,8 @@ module Secretariat
     :grand_total_amount,
     :due_amount,
     :paid_amount,
-
+    :tax_calculation_method,
+    :attachments,
     keyword_init: true
   ) do
 
@@ -54,21 +56,43 @@ module Secretariat
       tax_reason || TAX_EXEMPTION_REASONS[tax_category]
     end
 
-    def tax_category_code(version: 2)
+    def tax_category_code(tax, version: 2)
       if version == 1
-        return TAX_CATEGORY_CODES_1[tax_category] || 'S'
+        return TAX_CATEGORY_CODES_1[tax.tax_category || tax_category] || 'S'
       end
-      TAX_CATEGORY_CODES[tax_category] || 'S'
+      TAX_CATEGORY_CODES[tax.tax_category || tax_category] || 'S'
     end
 
     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)) 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)
+          tax
+        end
+      else
+        taxes.values
       end
-      taxes.values
     end
 
     def payment_code
@@ -89,12 +113,14 @@ module Secretariat
         @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, :down)
-        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)
@@ -104,7 +130,7 @@ module Secretariat
         return false
       end
       line_item_sum = line_items.inject(BigDecimal(0)) do |m, item|
-        m + BigDecimal(item.charge_amount)
+        m + BigDecimal(item.quantity.negative? ? -item.charge_amount : item.charge_amount)
       end
       if line_item_sum != basis
         @errors << "Line items do not add up to basis amount #{line_item_sum} / #{basis}"
@@ -169,7 +195,7 @@ module Secretariat
                 xml.text(issue_date.strftime("%Y%m%d"))
               end
             end
-            
+
           end
           transaction = by_version(version, 'SpecifiedSupplyChainTradeTransaction', 'SupplyChainTradeTransaction')
           xml['rsm'].send(transaction) do
@@ -192,6 +218,13 @@ module Secretariat
               xml['ram'].BuyerTradeParty do
                 buyer.to_xml(xml, version: version)
               end
+              if version == 2
+                if Array(attachments).size > 0
+                  attachments.each_with_index do |attachment, index|
+                    attachment.to_xml(xml, index, version: version, validate: validate)
+                  end
+                end
+              end
             end
 
             delivery = by_version(version, 'ApplicableSupplyChainTradeDelivery', 'ApplicableHeaderTradeDelivery')
@@ -212,6 +245,9 @@ module Secretariat
             end
             trade_settlement = by_version(version, 'ApplicableSupplyChainTradeSettlement', 'ApplicableHeaderTradeSettlement')
             xml['ram'].send(trade_settlement) do
+              if payment_reference && payment_reference != ''
+                xml['ram'].PaymentReference payment_reference
+              end
               xml['ram'].InvoiceCurrencyCode currency_code
               xml['ram'].SpecifiedTradeSettlementPaymentMeans do
                 xml['ram'].TypeCode payment_code
@@ -230,10 +266,11 @@ module Secretariat
                     xml['ram'].ExemptionReason tax_reason_text
                   end
                   Helpers.currency_element(xml, 'ram', 'BasisAmount', tax.base_amount, currency_code, add_currency: version == 1)
-                  xml['ram'].CategoryCode tax_category_code(version: version)
-
-                  percent = by_version(version, 'ApplicablePercent', 'RateApplicablePercent')
-                  xml['ram'].send(percent, Helpers.format(tax.tax_percent))
+                  xml['ram'].CategoryCode tax_category_code(tax, version: version)
+                  # 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
@@ -271,7 +308,7 @@ module Secretariat
             end
             if version == 1
               line_items.each_with_index do |item, i|
-                item.to_xml(xml, i + 1, version: version) # one indexed
+                item.to_xml(xml, i + 1, version: version, validate: validate) # one indexed
               end
             end
           end

data/lib/secretariat/line_item.rb

@@ -14,8 +14,6 @@ See the License for the specific language governing permissions and
 limitations under the License.
 =end
 
-
-
 require 'bigdecimal'
 module Secretariat
 
@@ -49,7 +47,7 @@ module Secretariat
       gross_price = BigDecimal(gross_amount)
       charge_price = BigDecimal(charge_amount)
       tax = BigDecimal(tax_amount)
-      unit_price = net_price * BigDecimal(quantity)
+      unit_price = net_price * BigDecimal(quantity.abs)
 
       if charge_price != unit_price
         @errors << "charge price and gross price times quantity deviate: #{charge_price} / #{unit_price}"
@@ -63,11 +61,15 @@ module Secretariat
           return false
         end
       end
-
-      calculated_tax = charge_price * BigDecimal(tax_percent) / BigDecimal(100)
-      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
@@ -83,9 +85,31 @@ module Secretariat
       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
+      
+      if net_price&.negative?
+        # Zugferd doesn't allow negative amounts at the item level.
+        # Instead, a negative quantity is used.
+        self.quantity = -quantity
+        self.gross_amount = gross_price&.abs
+        self.net_amount = net_price&.abs
+        self.charge_amount = charge_price&.abs
+      end
+
       if validate && !valid?
-        pp errors
         raise ValidationError.new("LineItem #{line_item_index} is invalid", errors)
       end
 
@@ -152,14 +176,14 @@ module Secretariat
           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
-            Helpers.currency_element(xml, 'ram', 'LineTotalAmount', charge_amount, currency_code, add_currency: version == 1)
+            Helpers.currency_element(xml, 'ram', 'LineTotalAmount', (quantity.negative? ? -charge_amount  : charge_amount), currency_code, add_currency: version == 1)
           end
         end
 

data/lib/secretariat/tax.rb

@@ -20,6 +20,7 @@ module Secretariat
   Tax = Struct.new('Tax',
     :tax_percent,
     :tax_amount,
+    :tax_category,
     :base_amount,
     keyword_init: true
   ) do
@@ -29,5 +30,10 @@ module Secretariat
       self.tax_amount = 0
       self.base_amount = 0
     end
+
+    def untaxable?
+      tax_category == :UNTAXEDSERVICE
+    end
+
   end
 end

data/lib/secretariat/trade_party.rb

@@ -16,10 +16,15 @@ limitations under the License.
 
 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 @@ module Secretariat
             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

data/lib/secretariat/version.rb

@@ -15,5 +15,5 @@ limitations under the License.
 =end
 
 module Secretariat
-  VERSION = '3.2.0'
+  VERSION = '3.4.0'
 end

data/lib/secretariat.rb

@@ -24,3 +24,4 @@ require_relative 'secretariat/trade_party'
 require_relative 'secretariat/line_item'
 require_relative 'secretariat/validator'
 require_relative 'secretariat/tax'
+require_relative 'secretariat/attachment'

metadata

@@ -1,11 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: secretariat
 version: !ruby/object:Gem::Version
-  version: 3.2.0
+  version: 3.4.0
 platform: ruby
 authors:
 - Jan Krutisch
-autorequire:
 bindir: bin
 cert_chain: []
 date: 2024-11-06 00:00:00.000000000 Z
@@ -38,6 +37,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: mime-types
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.6.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.6.0
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -66,6 +79,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
 description: a tool to help generate and validate ZUGFeRD invoice xml files
 email: jan@krutisch.de
 executables: []
@@ -75,6 +102,7 @@ files:
 - README.md
 - bin/schxslt-cli.jar
 - lib/secretariat.rb
+- lib/secretariat/attachment.rb
 - lib/secretariat/constants.rb
 - lib/secretariat/helpers.rb
 - lib/secretariat/invoice.rb
@@ -100,7 +128,6 @@ homepage: https://github.com/halfbyte/ruby-secretariat
 licenses:
 - Apache-2.0
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -116,8 +143,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements:
 - To run the validator, Java must be installed
-rubygems_version: 3.5.16
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: A ZUGFeRD xml generator
 test_files: []