secretariat 3.1.0 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 78a5b530fb987800431c180f91436cd9d538ed364f478aa17ddee805e85fc2f3
-  data.tar.gz: c4d569c8923b971e91eb5d1862f1e8484ddaf402cb62b6e405c4bee24ba2518f
+  metadata.gz: 4aede1e2eafc1189446e824cb5977b9c3844f71fa4c505214aa4d9b9f79e1101
+  data.tar.gz: 533c4f81ae8b50977df60f6c2bc31565cbbfd93066c52d8cf1961215971319fd
 SHA512:
-  metadata.gz: 7dbdd370a0790c03b4f2fdbbefa16c3653e5554236e97b25eb7ff778ec1253a57e1323166ada9e8010fd5b47266ceee0bfc5e3c4e0f4d31a98f8ffd2d417f5d1
-  data.tar.gz: 61c934e0e8994226b61ad2780695c610d86000265cb0e95478d994f3740143f5849c3662be0fe2e8754cc5ef02aff1176f2e7753a5036437cb087a39d833fb56
+  metadata.gz: a3358bd3eec524b4e76fc8f32945dca7cb665d683a256e69350fa31c340db2a75f77f3f64883978da387a52edd9beb4810ffe362d67341c81abe28579a979e1f
+  data.tar.gz: 5f347f7253bc8f814a0e1524c968506679d7bb1108c9a4cf03d9716830829ae393e5cde2df2b9d83210a237b075354863ef06af10df2e3d984a699a9c1d758c3

data/README.md

@@ -2,14 +2,18 @@
 
 See tests for examples.
 
-# Some words of caution
+## Some words of caution
 
 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).
 
-# LICENSE
+## Contributors
+
+See [CONTRIBUTORS.md](CONTRIBUTORS.md).
+
+## LICENSE
 
 See [LICENSE](LICENSE).
 

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

@@ -1,5 +1,5 @@
 =begin
-Copyright Jan Krutisch
+Copyright Jan Krutisch and contributors (see CONTRIBUTORS.md)
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -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 UNKNOWN].freeze
+
   UNIT_CODES = {
     :PIECE => "C62",
     :DAY => "DAY",

data/lib/secretariat/helpers.rb

@@ -1,3 +1,18 @@
+=begin
+Copyright Jan Krutisch and contributors (see CONTRIBUTORS.md)
+
+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
 module Secretariat
   module Helpers
     def self.format(something, round: nil, digits:2)

data/lib/secretariat/invoice.rb

@@ -1,5 +1,5 @@
 =begin
-Copyright Jan Krutisch
+Copyright Jan Krutisch and contributors (see CONTRIBUTORS.md)
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -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,11 +56,28 @@ 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.tax_category || tax_category] || 'S'
+    end
+
+    def taxes
+      taxes = {}
+      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
+      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
-      TAX_CATEGORY_CODES[tax_category] || 'S'
     end
 
     def payment_code
@@ -69,12 +88,24 @@ module Secretariat
       @errors = []
       tax = BigDecimal(tax_amount)
       basis = BigDecimal(basis_amount)
-      calc_tax = basis * BigDecimal(tax_percent) / BigDecimal(100)
-      calc_tax = calc_tax.round(2, :down)
-      if tax != calc_tax
-        @errors << "Tax amount and calculated tax amount deviate: #{tax} / #{calc_tax}"
+      summed_tax_amount = taxes.sum(&:tax_amount)
+      if tax != summed_tax_amount
+        @errors << "Tax amount and summed tax amounts deviate: #{tax_amount} / #{summed_tax_amount}"
+        return false
+      end
+      summed_tax_base_amount = taxes.sum(&:base_amount)
+      if basis != summed_tax_base_amount
+        @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
+        end
+      end
       grand_total = BigDecimal(grand_total_amount)
       calc_grand_total = basis + tax
       if grand_total != calc_grand_total
@@ -82,7 +113,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}"
@@ -147,7 +178,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
@@ -170,6 +201,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')
@@ -190,6 +228,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
@@ -200,18 +241,19 @@ module Secretariat
                   end
                 end
               end
-              xml['ram'].ApplicableTradeTax do
+              taxes.each do |tax|
+                xml['ram'].ApplicableTradeTax do
+                  Helpers.currency_element(xml, 'ram', 'CalculatedAmount', tax.tax_amount, currency_code, add_currency: version == 1)
+                  xml['ram'].TypeCode 'VAT'
+                  if tax_reason_text && tax_reason_text != ''
+                    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(tax, version: version)
 
-                Helpers.currency_element(xml, 'ram', 'CalculatedAmount', tax_amount, currency_code, add_currency: version == 1)
-                xml['ram'].TypeCode 'VAT'
-                if tax_reason_text && tax_reason_text != ''
-                  xml['ram'].ExemptionReason tax_reason_text
+                  percent = by_version(version, 'ApplicablePercent', 'RateApplicablePercent')
+                  xml['ram'].send(percent, Helpers.format(tax.tax_percent))
                 end
-                Helpers.currency_element(xml, 'ram', 'BasisAmount', basis_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_percent))
               end
               if version == 2 && service_period_start && service_period_end
                 xml['ram'].BillingSpecifiedPeriod do
@@ -248,7 +290,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

@@ -1,5 +1,5 @@
 =begin
-Copyright Jan Krutisch
+Copyright Jan Krutisch and contributors (see CONTRIBUTORS.md)
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -12,7 +12,6 @@ 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
 
 
@@ -50,7 +49,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}"
@@ -66,6 +65,8 @@ module Secretariat
       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
@@ -85,8 +86,24 @@ module Secretariat
     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)
+
+      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
 
@@ -160,7 +177,7 @@ module Secretariat
           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

@@ -0,0 +1,34 @@
+=begin
+Copyright Jan Krutisch and contributors (see CONTRIBUTORS.md)
+
+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 'bigdecimal'
+
+module Secretariat
+  Tax = Struct.new('Tax',
+    :tax_percent,
+    :tax_amount,
+    :tax_category,
+    :base_amount,
+    keyword_init: true
+  ) do
+
+    def initialize(*)
+      super
+      self.tax_amount = 0
+      self.base_amount = 0
+    end
+  end
+end

data/lib/secretariat/trade_party.rb

@@ -1,5 +1,5 @@
 =begin
-Copyright Jan Krutisch
+Copyright Jan Krutisch and contributors (see CONTRIBUTORS.md)
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

data/lib/secretariat/validation_error.rb

@@ -1,5 +1,5 @@
 =begin
-Copyright Jan Krutisch
+Copyright Jan Krutisch and contributors (see CONTRIBUTORS.md)
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

data/lib/secretariat/validator.rb

@@ -1,5 +1,5 @@
 =begin
-Copyright Jan Krutisch
+Copyright Jan Krutisch and contributors (see CONTRIBUTORS.md)
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -25,17 +25,17 @@ module Secretariat
   class Validator
     SCHEMATRON = [
       '../../schemas/zugferd_1/ZUGFeRD1p0.sch',
-      '../../schemas/factur-x_1.0.0.7/Factur-X_1.0.07_EN16931.sch'
+      '../../schemas/factur-x_1/Factur-X_1.07.2_EN16931.sch'
     ]
 
     SCHEMA = [
       '../../schemas/zugferd_1/ZUGFeRD1p0.xsd',
-      '../../schemas/factur-x_1.0.0.7/Factur-X_1.0.07_EN16931.xsd'
+      '../../schemas/factur-x_1/Factur-X_1.07.2_EN16931.xsd'
     ]
 
     SCHEMA_DIR = [
       '../../schemas/zugferd_1',
-      '../../schemas/factur-x_1.0.0.7/'
+      '../../schemas/factur-x_1/'
     ]
 
     attr_accessor :doc, :version

data/lib/secretariat/version.rb

@@ -1,5 +1,5 @@
 =begin
-Copyright Jan Krutisch
+Copyright Jan Krutisch and contributors (see CONTRIBUTORS.md)
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -15,5 +15,5 @@ limitations under the License.
 =end
 
 module Secretariat
-  VERSION = '3.1.0'
+  VERSION = '3.3.0'
 end

data/lib/secretariat/versioner.rb

@@ -1,3 +1,18 @@
+=begin
+Copyright Jan Krutisch and contributors (see CONTRIBUTORS.md)
+
+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
 module Secretariat
   module Versioner
     def by_version(version, v1, v2)

data/lib/secretariat.rb

@@ -1,5 +1,5 @@
 =begin
-Copyright Jan Krutisch
+Copyright Jan Krutisch and contributors (see CONTRIBUTORS.md)
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -23,3 +23,5 @@ require_relative 'secretariat/invoice'
 require_relative 'secretariat/trade_party'
 require_relative 'secretariat/line_item'
 require_relative 'secretariat/validator'
+require_relative 'secretariat/tax'
+require_relative 'secretariat/attachment'