secretariat 3.7.0 → 3.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7614825461a1901faaa9bd3e72fc6fdbde345acc68fdfff7c7649d5e9af56bd5
-  data.tar.gz: 73ec613205ee0a40046c521baec838c4f2eb1fcbd15f12fccd0ec35d21071811
+  metadata.gz: f6d311cbeb3472a1af82827bb21d95e1f789fb21fe486995e1be364213761e44
+  data.tar.gz: e52061bd2915e2ef348c33c714a1f6ae74ee5b2ab3961c5adce7ea0ceac1a804
 SHA512:
-  metadata.gz: 3ffff8d3135aae3aab1d2c71737b1bc80ce588748c3b3350218629673c1295126f9bcdbd17986c2da6f78a5f4bb51493df85bb32ec2bd3ebf16a7bd692200172
-  data.tar.gz: 84ae46ef3f826f9af23ff62c4e8484bc003cb8e665d3edbb5c55468d8782d445d35b82afc892679cd6effa4782ed4178471902287267896fb33770c6b708ea9a
+  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

@@ -24,8 +24,9 @@ module Secretariat
     :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,
@@ -48,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
 
@@ -57,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)
@@ -82,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
 
@@ -140,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}"
@@ -245,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
@@ -260,6 +272,9 @@ module Secretariat
             end
             trade_settlement = by_version(version, 'ApplicableSupplyChainTradeSettlement', 'ApplicableHeaderTradeSettlement')
             xml['ram'].send(trade_settlement) do
+              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
@@ -278,13 +293,18 @@ module Secretariat
                     xml['ram'].BICID payment_bic
                   end
                 end
+                if direct_debit_iban
+                  xml['ram'].PayerPartyDebtorFinancialAccount do
+                    xml['ram'].IBANID direct_debit_iban
+                  end
+                end
               end
               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.present?
-                    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)
@@ -311,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/trade_party.rb

@@ -18,16 +18,26 @@ 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 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
@@ -53,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.7.0"
+  VERSION = "3.8.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: secretariat
 version: !ruby/object:Gem::Version
-  version: 3.7.0
+  version: 3.8.0
 platform: ruby
 authors:
 - Jan Krutisch