secretariat 3.6.0 → 3.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24767d1bf53e67440e5b012f83b19e45119e937fde0085d8197ff21dcf0c65e0
-  data.tar.gz: c0cc0b22c3f8fa4612e08a6bab5af89f0fefd30a06c899976264305991d08846
+  metadata.gz: f6d311cbeb3472a1af82827bb21d95e1f789fb21fe486995e1be364213761e44
+  data.tar.gz: e52061bd2915e2ef348c33c714a1f6ae74ee5b2ab3961c5adce7ea0ceac1a804
 SHA512:
-  metadata.gz: acaff7a169b01482c53491609cd0b91add3d528b74e84659369d6283463eae3787020d6a91153775778decf393353f2c8a88935e046eb8a3ab1bb151fd5dd31b
-  data.tar.gz: c213647657402309c566461b15d11dc1a1cc5d72e8d158ab79fc0f51b2bde4eb6245c86e68cd976bc707f372f9d8ce803ef076453a7cfd222ae95f60e7257fac
+  metadata.gz: 7ebfa196f6d6c1710bbdb6768526321e9ca1a729d9d4ff8117914ab7d84bf1b919eea3c212cc3dfcc4574aa2f9272c415ec319cf941912ffccd2ddfef03f08bd
+  data.tar.gz: 6cb203137f2af48c89635b4bea7860b0aafb02feaebbecf649f8aabf0c43ac56afa3a3932439fa0d516f790d96dae80c800f46a31eac556afbbdc421a6ff7215

data/lib/secretariat/constants.rb

@@ -53,6 +53,10 @@ module Secretariat
    :DEBITADVICE => "31",
    :CREDITCARD => "48",
    :DEBIT => "49",
+   :CREDITTRANSFER => "54",
+   :DIRECTDEBIT => "55",
+   :SEPACREDITTRANSFER => "58",
+   :SEPADIRECTDEBIT => "59",
    :COMPENSATION => "97"
   }
 
@@ -69,6 +73,7 @@ module Secretariat
   TAX_CALCULATION_METHODS = %i[HORIZONTAL VERTICAL NONE UNKNOWN].freeze
 
   UNIT_CODES = {
+    :YEAR => "ANN",
     :PIECE => "C62",
     :DAY => "DAY",
     :HECTARE => "HAR",

data/lib/secretariat/invoice.rb

@@ -17,13 +17,16 @@ limitations under the License.
 require 'bigdecimal'
 
 module Secretariat
+  using ObjectExtensions
+  
   Invoice = Struct.new("Invoice",
     :id,
     :issue_date,
     :service_period_start,
     :service_period_end,
-    :seller,
-    :buyer,
+    :seller, # TradeParty
+    :buyer, # TradeParty
+    :ship_to, # TradeParty or nil (buyer) or false (no ShipTo)
     :buyer_reference,
     :line_items,
     :currency_code,
@@ -33,6 +36,8 @@ module Secretariat
     :payment_terms_text,
     :payment_due_date,
     :payment_iban,
+    :payment_bic,
+    :payment_payee_account_name,
     :tax_category,
     :tax_percent,
     :tax_amount,
@@ -44,6 +49,9 @@ module Secretariat
     :tax_calculation_method,
     :notes,
     :attachments,
+    :direct_debit_mandate_reference_id, # BT-89
+    :direct_debit_creditor_id, # BT-90
+    :direct_debit_iban, # BT-91
     keyword_init: true
   ) do
 
@@ -53,8 +61,16 @@ module Secretariat
       @errors
     end
 
-    def tax_reason_text
-      tax_reason || TAX_EXEMPTION_REASONS[tax_category]
+    def tax_reason_text(tax)
+      tax_reason || TAX_EXEMPTION_REASONS[tax.tax_category || tax_category]
+    end
+
+    # ship_to: nil => use buyer (backwards compatibility)
+    # ship_to: false => ignore
+    def ship_to_or_buyer
+      return buyer if ship_to.nil?
+
+      ship_to
     end
 
     def tax_category_code(tax, version: 2)
@@ -78,11 +94,11 @@ module Secretariat
       line_items.each do |line_item|
         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
+          taxes['0'].base_amount += BigDecimal(line_item.net_amount) * line_item.billed_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
+          taxes[line_item.tax_percent].base_amount += BigDecimal(line_item.net_amount) * line_item.billed_quantity
         end
       end
 
@@ -136,7 +152,7 @@ module Secretariat
         return false
       end
       line_item_sum = line_items.inject(BigDecimal(0)) do |m, item|
-        m + BigDecimal(item.quantity.negative? ? -item.charge_amount : item.charge_amount)
+        m + BigDecimal(item.billed_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}"
@@ -241,9 +257,9 @@ module Secretariat
             delivery = by_version(version, 'ApplicableSupplyChainTradeDelivery', 'ApplicableHeaderTradeDelivery')
 
             xml['ram'].send(delivery) do
-              if version == 2
+              if version == 2 && ship_to_or_buyer
                 xml['ram'].ShipToTradeParty do
-                  buyer.to_xml(xml, exclude_tax: true, version: version)
+                  ship_to_or_buyer.to_xml(xml, exclude_tax: true, version: version)
                 end
               end
               xml['ram'].ActualDeliverySupplyChainEvent do
@@ -256,16 +272,30 @@ module Secretariat
             end
             trade_settlement = by_version(version, 'ApplicableSupplyChainTradeSettlement', 'ApplicableHeaderTradeSettlement')
             xml['ram'].send(trade_settlement) do
-              if payment_reference && payment_reference != ''
+              if direct_debit_creditor_id
+                xml['ram'].CreditorReferenceID direct_debit_creditor_id # BT-90
+              end
+              if payment_reference.present?
                 xml['ram'].PaymentReference payment_reference
               end
               xml['ram'].InvoiceCurrencyCode currency_code
               xml['ram'].SpecifiedTradeSettlementPaymentMeans do
                 xml['ram'].TypeCode payment_code
                 xml['ram'].Information payment_text
-                if payment_iban
+                if payment_iban || payment_payee_account_name
                   xml['ram'].PayeePartyCreditorFinancialAccount do
-                    xml['ram'].IBANID payment_iban
+                    xml['ram'].IBANID payment_iban if payment_iban
+                    xml['ram'].AccountName payment_payee_account_name if payment_payee_account_name
+                  end
+                end
+                if payment_bic
+                  xml['ram'].PayeeSpecifiedCreditorFinancialInstitution do
+                    xml['ram'].BICID payment_bic
+                  end
+                end
+                if direct_debit_iban
+                  xml['ram'].PayerPartyDebtorFinancialAccount do
+                    xml['ram'].IBANID direct_debit_iban
                   end
                 end
               end
@@ -273,8 +303,8 @@ module Secretariat
                 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
+                  if tax_reason_text(tax).present?
+                    xml['ram'].ExemptionReason tax_reason_text(tax)
                   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)
@@ -301,6 +331,9 @@ module Secretariat
                     Helpers.date_element(xml, payment_due_date)
                   end
                 end
+                if direct_debit_mandate_reference_id
+                  xml['ram'].DirectDebitMandateID direct_debit_mandate_reference_id
+                end
               end
 
               monetary_summation = by_version(version, 'SpecifiedTradeSettlementMonetarySummation', 'SpecifiedTradeSettlementHeaderMonetarySummation')

data/lib/secretariat/line_item.rb

@@ -20,7 +20,7 @@ module Secretariat
 
   LineItem = Struct.new('LineItem',
     :name,
-    :quantity,
+    :billed_quantity,
     :unit,
     :gross_amount,
     :net_amount,
@@ -32,11 +32,38 @@ module Secretariat
     :charge_amount,
     :origin_country_code,
     :currency_code,
+    :service_period_start, # if start present start & end are required
+    :service_period_end, # end has to be on or after start (secretariat does not validate this)
+    :basis_quantity,
     keyword_init: true
   ) do
 
     include Versioner
 
+    def initialize(**kwargs)
+      if kwargs.key?(:quantity) && !kwargs.key?(:billed_quantity)
+        kwargs[:billed_quantity] = kwargs.delete(:quantity)
+      end
+      super(**kwargs)
+    end
+
+    def quantity
+      warn_once_quantity
+      billed_quantity
+    end
+
+    def quantity=(val)
+      warn_once_quantity
+      self.billed_quantity = val
+    end
+
+    def warn_once_quantity
+      unless @__warned_quantity
+        Kernel.warn("[secretariat] LineItem#quantity is deprecated; use #billed_quantity")
+        @__warned_quantity = true
+      end
+    end
+
     def errors
       @errors
     end
@@ -47,7 +74,7 @@ module Secretariat
       gross_price = BigDecimal(gross_amount)
       charge_price = BigDecimal(charge_amount)
       tax = BigDecimal(tax_amount)
-      unit_price = net_price * BigDecimal(quantity.abs)
+      unit_price = net_price * BigDecimal(billed_quantity.abs)
 
       if charge_price != unit_price
         @errors << "charge price and gross price times quantity deviate: #{charge_price} / #{unit_price}"
@@ -65,7 +92,7 @@ module Secretariat
         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?
+        calculated_tax = -calculated_tax if billed_quantity.negative?
         if calculated_tax != tax
           @errors << "Tax and calculated tax deviate: #{tax} / #{calculated_tax}"
           return false
@@ -78,6 +105,13 @@ module Secretariat
       UNIT_CODES[unit] || 'C62'
     end
 
+    # If not provided, BasisQuantity should be 1.0 (price per 1 unit)
+    def effective_basis_quantity
+      q = basis_quantity.nil? ? BigDecimal("1.0") : BigDecimal(basis_quantity.to_s)
+      raise ArgumentError, "basis_quantity must be > 0" if q <= 0
+      q
+    end
+
     def tax_category_code(version: 2)
       if version == 1
         return TAX_CATEGORY_CODES_1[tax_category] || 'S'
@@ -103,7 +137,7 @@ module Secretariat
       if net_price&.negative?
         # Zugferd doesn't allow negative amounts at the item level.
         # Instead, a negative quantity is used.
-        self.quantity = -quantity
+        self.billed_quantity = -billed_quantity
         self.gross_amount = gross_price&.abs
         self.net_amount = net_price&.abs
         self.charge_amount = charge_price&.abs
@@ -132,7 +166,7 @@ module Secretariat
             Helpers.currency_element(xml, 'ram', 'ChargeAmount', gross_amount, currency_code, add_currency: version == 1, digits: 4)
             if version == 2 && discount_amount
               xml['ram'].BasisQuantity(unitCode: unit_code) do
-                xml.text(Helpers.format(quantity, digits: 4))
+                xml.text(Helpers.format(effective_basis_quantity, digits: 4))
               end
               xml['ram'].AppliedTradeAllowanceCharge do
                 xml['ram'].ChargeIndicator do
@@ -156,7 +190,7 @@ module Secretariat
             Helpers.currency_element(xml, 'ram', 'ChargeAmount', net_amount, currency_code, add_currency: version == 1, digits: 4)
             if version == 2
               xml['ram'].BasisQuantity(unitCode: unit_code) do
-                xml.text(Helpers.format(quantity, digits: 4))
+                xml.text(Helpers.format(effective_basis_quantity, digits: 4))
               end
             end
           end
@@ -166,7 +200,7 @@ module Secretariat
 
         xml['ram'].send(delivery) do
           xml['ram'].BilledQuantity(unitCode: unit_code) do
-            xml.text(Helpers.format(quantity, digits: 4))
+            xml.text(Helpers.format(billed_quantity, digits: 4))
           end
         end
 
@@ -181,9 +215,25 @@ module Secretariat
               xml['ram'].send(percent,Helpers.format(tax_percent))            
             end
           end
+
+          if version == 2 && self.service_period_start && self.service_period_end
+            xml['ram'].BillingSpecifiedPeriod do
+              xml['ram'].StartDateTime do
+                xml['udt'].DateTimeString(format: '102') do
+                  xml.text(service_period_start.strftime("%Y%m%d"))
+                end
+              end
+              xml['ram'].EndDateTime do
+                xml['udt'].DateTimeString(format: '102') do
+                  xml.text(service_period_end.strftime("%Y%m%d"))
+                end
+              end
+            end
+          end
+
           monetary_summation = by_version(version, 'SpecifiedTradeSettlementMonetarySummation', 'SpecifiedTradeSettlementLineMonetarySummation')
           xml['ram'].send(monetary_summation) do
-            Helpers.currency_element(xml, 'ram', 'LineTotalAmount', (quantity.negative? ? -charge_amount  : charge_amount), currency_code, add_currency: version == 1)
+            Helpers.currency_element(xml, 'ram', 'LineTotalAmount', (billed_quantity.negative? ? -charge_amount  : charge_amount), currency_code, add_currency: version == 1)
           end
         end
 

data/lib/secretariat/object_extensions.rb

@@ -0,0 +1,14 @@
+module Secretariat
+  module ObjectExtensions
+    refine Object do
+      # Copied from activesupport/lib/active_support/core_ext/object/blank.rb, line 18
+      def blank?
+        respond_to?(:empty?) ? !!empty? : !self
+      end
+
+      def present?
+        !blank?
+      end
+    end
+  end
+end

data/lib/secretariat/trade_party.rb

@@ -15,33 +15,45 @@ limitations under the License.
 =end
 
 module Secretariat
+  using ObjectExtensions
+  
   TradeParty = Struct.new('TradeParty',
+    :id,
     :name, :street1, :street2, :city, :postal_code, :country_id, :vat_id, :global_id, :global_id_scheme_id, :tax_id,
+    :person_name,
     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 != ''
+      if id && !exclude_tax
+        xml['ram'].ID id # BT-46
+      end
+      if global_id.present? && global_id_scheme_id.present?
         xml['ram'].GlobalID(schemeID: global_id_scheme_id) do
           xml.text(global_id)
         end
       end
       xml['ram'].Name name
+      if person_name
+        xml['ram'].DefinedTradeContact do
+          xml['ram'].PersonName person_name
+        end
+      end
       xml['ram'].PostalTradeAddress do
         xml['ram'].PostcodeCode postal_code
         xml['ram'].LineOne street1
-        if street2 && street2 != ''
+        if street2.present?
           xml['ram'].LineTwo street2
         end
         xml['ram'].CityName city
         xml['ram'].CountryID country_id
       end
-      if !exclude_tax && vat_id && vat_id != ''
+      if !exclude_tax && vat_id.present?
         xml['ram'].SpecifiedTaxRegistration do
           xml['ram'].ID(schemeID: 'VA') do
             xml.text(vat_id)
           end
         end
-      elsif tax_id && tax_id != ''
+      elsif tax_id.present?
         xml['ram'].SpecifiedTaxRegistration do
           xml['ram'].ID(schemeID: 'FC') do
             xml.text(tax_id)
@@ -51,3 +63,5 @@ module Secretariat
     end
   end
 end
+
+# assert_match(%r{<ram:DefinedTradeContact>\s*<ram:PersonName>Max Mustermann</ram:PersonName>\s*</ram:DefinedTradeContact>}, xml)

data/lib/secretariat/version.rb

@@ -15,5 +15,5 @@ limitations under the License.
 =end
 
 module Secretariat
-  VERSION = '3.6.0'
+  VERSION = "3.8.0"
 end

data/lib/secretariat.rb

@@ -15,6 +15,7 @@ limitations under the License.
 =end
 
 require_relative 'secretariat/version'
+require_relative 'secretariat/object_extensions'
 require_relative 'secretariat/constants'
 require_relative 'secretariat/helpers'
 require_relative 'secretariat/versioner'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: secretariat
 version: !ruby/object:Gem::Version
-  version: 3.6.0
+  version: 3.8.0
 platform: ruby
 authors:
 - Jan Krutisch
@@ -107,6 +107,7 @@ files:
 - lib/secretariat/helpers.rb
 - lib/secretariat/invoice.rb
 - lib/secretariat/line_item.rb
+- lib/secretariat/object_extensions.rb
 - lib/secretariat/tax.rb
 - lib/secretariat/trade_party.rb
 - lib/secretariat/validation_error.rb