secretariat 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ea7afc077807afc9c37b543936f44c92dd47efde7b88afd9cd0189962a725582
+  data.tar.gz: bf531f1c30ded4f468a0b7b4c8657dece3d9abb3f758b9d1fad167f0ddccdc4a
+SHA512:
+  metadata.gz: b00aa871cdbe0610476e5689756db15ec8f5d584c658548513d2e22c895e1f393e74b42f33b92c7ebb516bf08ebea2b64d240ab58235ef89b0a47a3fa4a9503d
+  data.tar.gz: d34cccd54819f93c2fdf6850a2ffee4306d42034ded2748961814c7159258aab5c06bda3251497ef85e0e417958ab4d044945c544c3e757e244c2df1d7d1a018

data/README.md

@@ -0,0 +1,22 @@
+# A ZUGFeRD xml generator and validator
+
+More info coming soon. See tests for examples.
+
+# 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.
+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.
+
+# LICENSE
+
+See [LICENSE](LICENSE).
+
+Additionally, this project contains material, such as the schema files, which,
+according to the ZUGFeRD documentation, are also licensed under the Apache
+License.
+
+Additionally, this project uses nokogiri and schematron-nokogiri, both
+licensed unter the MIT license.
+
+

data/lib/secretariat.rb

@@ -0,0 +1,23 @@
+=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_relative 'secretariat/version'
+require_relative 'secretariat/constants'
+require_relative 'secretariat/validation_error'
+require_relative 'secretariat/invoice'
+require_relative 'secretariat/trade_party'
+require_relative 'secretariat/line_item'
+require_relative 'secretariat/validator'

data/lib/secretariat/constants.rb

@@ -0,0 +1,56 @@
+=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
+
+module Secretariat
+
+  TAX_CATEGORY_CODES = {
+   :STANDARDRATE => "S",
+   :REVERSECHARGE => "AE",
+   :TAXEXEMPT => "E",
+   :ZEROTAXPRODUCTS => "Z",
+   :UNTAXEDSERVICE => "O",
+   :INTRACOMMUNITY => "K"
+  }
+
+  TAX_EXEMPTION_REASONS = {
+    :REVERSECHARGE => 'Reverse Charge',
+    :INTRACOMMUNITY => ''
+  }
+
+  UNIT_CODES = {
+    :PIECE => "C62",
+    :DAY => "DAY",
+    :HECTARE => "HAR",
+    :HOUR => "HUR",
+    :KILOGRAM => "KGM",
+    :KILOMETER => "KTM",
+    :KILOWATTHOUR => "KWH",
+    :FIXEDRATE => "LS",
+    :LITRE => "LTR",
+    :MINUTE => "MIN",
+    :SQUAREMILLIMETER => "MMK",
+    :MILLIMETER => "MMT",
+    :SQUAREMETER => "MTK",
+    :CUBICMETER => "MTQ",
+    :METER => "MTR",
+    :PRODUCTCOUNT => "NAR",
+    :PRODUCTPAIR => "NPR",
+    :PERCENT => "P1",
+    :SET => "SET",
+    :TON => "TNE",
+    :WEEK => "WEE"
+  }
+end

data/lib/secretariat/invoice.rb

@@ -0,0 +1,168 @@
+=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 'bigdecimal'
+
+module Secretariat
+  Invoice = Struct.new("Invoice",
+    :id,
+    :issue_date,
+    :seller,
+    :buyer,
+    :line_items,
+    :currency_code,
+    :payment_code,
+    :payment_text,
+    :tax_category,
+    :tax_percent,
+    :tax_amount,
+    :tax_reason,
+    :basis_amount,
+    :grand_total_amount,
+    :due_amount,
+    :paid_amount,
+
+    keyword_init: true
+  ) do
+
+    def errors
+      @errors
+    end
+
+    def tax_reason_text
+      tax_reason || TAX_EXEMPTION_REASONS[tax_category]
+    end
+
+    def tax_category_code
+      TAX_CATEGORY_CODES[tax_category] || 'S'
+    end
+
+    def valid?
+      tax = BigDecimal(tax_amount)
+      basis = BigDecimal(basis_amount)
+      calc_tax = basis * BigDecimal(tax_percent) / BigDecimal(100)
+      if tax != calc_tax
+        @errors << "Tax amount and calculated tax amount deviate"
+        return false
+      end
+      grand_total = BigDecimal(grand_total_amount)
+      calc_grand_total = basis + tax
+      if grand_total != calc_grand_total
+        @errors << "Grand total amount and calculated grand total amount deviate"
+        return false
+      end
+      line_item_sum = line_items.inject(BigDecimal(0)) do |m, item|
+        m + BigDecimal(item.charge_amount)
+      end
+      if line_item_sum != basis
+        @errors << "Line items do not add up to basis amount"
+        return false
+      end
+      return true
+    end
+
+
+    def to_xml()
+
+      unless valid?
+        raise ValidationError.new("Invoice is invalid", errors)
+      end
+
+      builder = Nokogiri::XML::Builder.new do |xml|
+        xml.CrossIndustryInvoice({
+          'xmlns:qdt' => 'urn:un:unece:uncefact:data:standard:QualifiedDataType:100',
+          'xmlns:ram' => 'urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100',
+          'xmlns:udt' => 'urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100',
+          'xmlns' => 'urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100',
+          'xmlns:xsi' => 'http://www.w3.org/2001/XMLSchema-instance'
+        }) do
+          xml.ExchangedDocumentContext do
+            xml['ram'].GuidelineSpecifiedDocumentContextParameter do
+              xml['ram'].ID 'urn:cen.eu:en16931:2017'
+            end
+          end
+
+          xml.ExchangedDocument do
+            xml['ram'].ID id
+            xml['ram'].TypeCode '380' # TODO: make configurable
+            xml['ram'].IssueDateTime do
+              xml['udt'].DateTimeString(format: '102') do
+                xml.text(issue_date.strftime("%Y%m%d"))
+              end
+            end
+          end
+          xml.SupplyChainTradeTransaction do
+            line_items.each_with_index do |item, i|
+              item.to_xml(xml, i + 1) # one indexed
+            end
+            xml['ram'].ApplicableHeaderTradeAgreement do
+              xml['ram'].SellerTradeParty do
+                seller.to_xml(xml)
+              end
+              xml['ram'].BuyerTradeParty do
+                buyer.to_xml(xml)
+              end
+            end
+            xml['ram'].ApplicableHeaderTradeDelivery do
+              xml['ram'].ShipToTradeParty do
+                buyer.to_xml(xml, exclude_tax: true)
+              end
+              xml['ram'].ActualDeliverySupplyChainEvent do
+                xml['ram'].OccurrenceDateTime do
+                  xml['udt'].DateTimeString(format: '102') do
+                    xml.text(issue_date.strftime("%Y%m%d"))
+                  end
+                end
+              end
+            end
+            xml['ram'].ApplicableHeaderTradeSettlement do
+              xml['ram'].InvoiceCurrencyCode currency_code
+              xml['ram'].SpecifiedTradeSettlementPaymentMeans do
+                xml['ram'].TypeCode payment_code
+                xml['ram'].Information payment_text
+              end
+              xml['ram'].ApplicableTradeTax do
+                xml['ram'].CalculatedAmount tax_amount
+                xml['ram'].TypeCode 'VAT'
+                if tax_reason_text && tax_reason_text != ''
+                  xml['ram'].ExemptionReason tax_reason
+                end
+                xml['ram'].BasisAmount basis_amount
+                xml['ram'].CategoryCode tax_category_code
+                xml['ram'].RateApplicablePercent tax_percent
+              end
+              xml['ram'].SpecifiedTradePaymentTerms do
+                xml['ram'].Description "Paid"
+              end
+              xml['ram'].SpecifiedTradeSettlementHeaderMonetarySummation do
+                xml['ram'].LineTotalAmount basis_amount
+                xml['ram'].TaxBasisTotalAmount basis_amount
+                xml['ram'].TaxTotalAmount(currencyID: currency_code) do
+                  xml.text(tax_amount)
+                end
+                xml['ram'].GrandTotalAmount grand_total_amount
+                xml['ram'].TotalPrepaidAmount paid_amount
+                xml['ram'].DuePayableAmount due_amount
+              end
+            end
+          end
+        end
+      end
+      builder.to_xml
+    end
+  end
+
+end

data/lib/secretariat/line_item.rb

@@ -0,0 +1,115 @@
+=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 'bigdecimal'
+module Secretariat
+
+
+  LineItem = Struct.new('LineItem',
+    :name,
+    :quantity,
+    :unit,
+    :unit_amount,
+    :charge_amount,
+    :tax_category,
+    :tax_percent,
+    :tax_amount,
+    :origin_country_code,
+    keyword_init: true
+  ) do
+
+    def errors
+      @errors
+    end
+
+    def valid?
+      unit_price = BigDecimal(unit_amount)
+      charge_price = BigDecimal(charge_amount)
+      tax = BigDecimal(tax_amount)
+
+      if charge_price != unit_price * BigDecimal(quantity)
+        @errors << "charge price and unit price times quantity deviate"
+        return false
+      end
+
+      calculated_tax = charge_price * BigDecimal(tax_percent) / BigDecimal(100)
+      if calculated_tax != tax
+        @errors << "Tax and calculated tax deviate"
+        return false
+      end
+      return true
+    end
+
+    def unit_code
+      UNIT_CODES[unit] || 'C62'
+    end
+
+    def tax_category_code
+      TAX_CATEGORY_CODES[tax_category] || 'S'
+    end
+
+    def to_xml(xml, line_item_index)
+      if !valid?
+        raise ValidationError.new("LineItem #{line_item_index} is invalid", errors)
+      end
+
+      xml['ram'].IncludedSupplyChainTradeLineItem do
+        xml['ram'].AssociatedDocumentLineDocument do
+          xml['ram'].LineID line_item_index
+        end
+        xml['ram'].SpecifiedTradeProduct do
+          xml['ram'].Name name
+          xml['ram'].OriginTradeCountry do
+            xml['ram'].ID origin_country_code
+          end
+        end
+        xml['ram'].SpecifiedLineTradeAgreement do
+          xml['ram'].GrossPriceProductTradePrice do
+            xml['ram'].ChargeAmount unit_amount
+            xml['ram'].BasisQuantity(unitCode: unit_code) do
+              xml.text(quantity)
+            end
+          end
+          xml['ram'].NetPriceProductTradePrice do
+            xml['ram'].ChargeAmount unit_amount
+            xml['ram'].BasisQuantity(unitCode: unit_code) do
+              xml.text(quantity)
+            end
+          end
+        end
+        xml['ram'].SpecifiedLineTradeDelivery do
+          xml['ram'].BilledQuantity(unitCode: unit_code) do
+            xml.text(quantity)
+          end
+        end
+        xml['ram'].SpecifiedLineTradeSettlement do
+          xml['ram'].ApplicableTradeTax do
+            xml['ram'].TypeCode 'VAT'
+            xml['ram'].CategoryCode tax_category_code
+            xml['ram'].RateApplicablePercent tax_percent
+
+          end
+          xml['ram'].SpecifiedTradeSettlementLineMonetarySummation do
+            xml['ram'].LineTotalAmount charge_amount
+          end
+        end
+      end
+    end
+  end
+end

data/lib/secretariat/trade_party.rb

@@ -0,0 +1,44 @@
+=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
+
+module Secretariat
+  TradeParty = Struct.new('TradeParty',
+    :name, :street1, :street2, :city, :postal_code, :country_id, :vat_id,
+    keyword_init: true,
+  ) do
+    def to_xml(xml, exclude_tax: false)
+      xml['ram'].Name name
+      xml['ram'].PostalTradeAddress do
+        xml['ram'].PostcodeCode postal_code
+        xml['ram'].LineOne street1
+        if street2 && street2 != ''
+          xml['ram'].LineTwo street2
+        end
+        xml['ram'].CityName city
+        xml['ram'].CountryID country_id
+      end
+      if !exclude_tax && vat_id && vat_id != ''
+        xml['ram'].SpecifiedTaxRegistration do
+          xml['ram'].ID(schemeID: 'VA') do
+            xml.text(vat_id)
+          end
+        end
+      end
+    end
+  end
+
+
+end

data/lib/secretariat/validation_error.rb

@@ -0,0 +1,25 @@
+=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
+
+module Secretariat
+  class ValidationError < StandardError
+    attr_reader :errors
+    def initialize(reason, errors = [])
+      super(reason)
+      @errors = errors
+    end
+  end
+end