facturx 0.1.0 → 1.0.0

data/lib/facturx/writer/stages/trade_agreement.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative 'trade_agreement/parties'
+require_relative 'trade_agreement/references'
+
+module Facturx
+  class Writer
+    module Stages
+      class TradeAgreement < Stage
+        include TradeAgreementSupport::Parties
+        include TradeAgreementSupport::References
+
+        SELLER_ADDRESS = {
+          postcode: 'BT-38', line_one: 'BT-35', line_two: 'BT-36', line_three: 'BT-162', city: 'BT-37',
+          country_code: 'BT-40', country_subdivision: 'BT-39'
+        }.freeze
+        BUYER_ADDRESS = {
+          postcode: 'BT-53', line_one: 'BT-50', line_two: 'BT-51', line_three: 'BT-163', city: 'BT-52',
+          country_code: 'BT-55', country_subdivision: 'BT-54'
+        }.freeze
+        REPRESENTATIVE_ADDRESS = {
+          postcode: 'BT-67', line_one: 'BT-64', line_two: 'BT-65', line_three: 'BT-164', city: 'BT-66',
+          country_code: 'BT-69', country_subdivision: 'BT-68'
+        }.freeze
+        SELLER_CONTACT = { name: 'BT-41', telephone: 'BT-42', email: 'BT-43' }.freeze
+        BUYER_CONTACT = { name: 'BT-56', telephone: 'BT-57', email: 'BT-58' }.freeze
+
+        term_ids(*%w[
+                   BT-10 BT-29 BT-29-1 BT-27 BT-33 BT-30 BT-30-1 BT-28 BT-41 BT-42 BT-43 BT-38 BT-35 BT-36
+                   BT-162 BT-37 BT-40 BT-39 BT-34 BT-34-1 BT-31 BT-32 BT-46 BT-46-1 BT-44 BT-47 BT-47-1 BT-45
+                   BT-56 BT-57 BT-58 BT-53 BT-50 BT-51 BT-163 BT-52 BT-55 BT-54 BT-49 BT-49-1 BT-48 BT-62 BT-67
+                   BT-64 BT-65 BT-164 BT-66 BT-69 BT-68 BT-63 BT-14 BT-13 BT-12 BT-17 BT-18 BT-18-1 BT-122 BT-124
+                   BT-123 BT-125 BT-125-1 BT-125-2 BT-11
+                 ])
+
+        def call
+          agreement = context.element(context.transaction, 'ram:ApplicableHeaderTradeAgreement')
+          emit('BT-10', document.buyer_reference, element: 'ram:BuyerReference', parent: agreement)
+          write_parties(agreement)
+          write_references(agreement)
+        end
+      end
+    end
+  end
+end

data/lib/facturx/writer/stages/trade_delivery.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Writer
+    module Stages
+      class TradeDelivery < Stage
+        ADDRESS_IDS = {
+          postcode: 'BT-78', line_one: 'BT-75', line_two: 'BT-76', line_three: 'BT-165', city: 'BT-77',
+          country_code: 'BT-80', country_subdivision: 'BT-79'
+        }.freeze
+
+        term_ids(*%w[BT-71 BT-71-1 BT-70 BT-78 BT-75 BT-76 BT-165 BT-77 BT-80 BT-79 BT-72 BT-16 BT-15])
+
+        def call
+          value = document.delivery
+          node = context.element(context.transaction, 'ram:ApplicableHeaderTradeDelivery')
+          delivery(node, value) if delivery_accepted?(value)
+          references(node)
+        end
+
+        private
+
+        def delivery_accepted?(value)
+          group = Terms.group('BG-13-00')
+          tracker.observe_group?(group, count: value ? 1 : 0, path: group.xpath)
+        end
+
+        def references(parent)
+          emit_document_reference(parent, 'BT-16', document.despatch_advice_reference,
+                                  'ram:DespatchAdviceReferencedDocument')
+          emit_document_reference(parent, 'BT-15', document.receiving_advice_reference,
+                                  'ram:ReceivingAdviceReferencedDocument')
+        end
+
+        def delivery(parent, value)
+          ship_to(parent, value)
+          delivery_date(parent, value.date)
+        end
+
+        def delivery_date(parent, value)
+          unless value
+            observe?('BT-72', nil)
+            return
+          end
+
+          container(parent, 'ram:ActualDeliverySupplyChainEvent') do |event|
+            emit_date(event, 'BT-72', value, wrapper: 'ram:OccurrenceDateTime')
+          end
+        end
+
+        def ship_to(parent, delivery)
+          party = delivery.party
+          location = delivery.location_identifier
+          present = party || location
+          within_group('BG-13', present, element: 'ram:ShipToTradeParty', parent:,
+                                         represented_attributes: %i[name address]) do |node,|
+            delivery_identifier(node, location)
+            emit('BT-70', party&.name, element: 'ram:Name', parent: node)
+            emit_address(node, party&.address, 'BG-15', ADDRESS_IDS)
+          end
+        end
+
+        def delivery_identifier(parent, value)
+          if value&.scheme_id
+            node = if observe?('BT-71', value.value)
+                     technical(parent, 'ram:GlobalID', format_identifier_value('BT-71', value.value))
+                   end
+            emit_attribute('BT-71-1', value.scheme_id, node:, attribute: 'schemeID', group_present: !node.nil?)
+          else
+            emit('BT-71', value&.value, element: 'ram:ID', parent:)
+            observe?('BT-71-1', nil, group_present: false)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/facturx/writer/stages/trade_lines/agreement.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Writer
+    module Stages
+      class TradeLines
+        class Agreement < Stage
+          PRICES = {
+            gross: { ids: %w[BT-148 BT-149-1 BT-150-1], element: 'ram:GrossPriceProductTradePrice' },
+            net: { ids: %w[BT-146 BT-149 BT-150], element: 'ram:NetPriceProductTradePrice' }
+          }.freeze
+
+          def initialize(context, quantity:)
+            super(context)
+            @quantity = quantity
+          end
+
+          def call(parent:, line:)
+            within_group('BG-29', line, element: 'ram:SpecifiedLineTradeAgreement', parent:) do |node, item|
+              buyer_order_reference(node, item.buyer_order_reference)
+              price(node, item.gross_price, kind: :gross)
+              price(node, item.net_price, kind: :net)
+            end
+          end
+
+          private
+
+          def buyer_order_reference(parent, value)
+            return observe?('BT-132', nil) unless value
+
+            report_unrepresentable_reference_attributes('BT-132', value, represented_attributes: [:line_id])
+
+            container(parent, 'ram:BuyerOrderReferencedDocument') do |node|
+              emit('BT-132', value.line_id, element: 'ram:LineID', parent: node)
+            end
+          end
+
+          def price(parent, value, kind:)
+            config = PRICES.fetch(kind)
+            return observe_missing_price(config, kind:) unless value
+            return unrepresentable(config.fetch(:ids).first, 'Price requires an amount') unless value.amount
+
+            represented_attributes = %i[amount basis_quantity]
+            represented_attributes << :discount if kind == :gross
+            report_unrepresentable_attributes('BG-29', value, represented_attributes:)
+
+            container(parent, config.fetch(:element)) do |node|
+              emit_price(node, value, config.fetch(:ids))
+              gross_discount(node, value.discount) if kind == :gross
+            end
+          end
+
+          def emit_price(parent, value, ids)
+            emit(ids[0], value.amount, element: 'ram:ChargeAmount', parent:)
+            @quantity.call(parent:, value: value.basis_quantity, amount_id: ids[1], unit_id: ids[2],
+                           element: 'ram:BasisQuantity')
+          end
+
+          def observe_missing_price(config, kind:)
+            config.fetch(:ids).each { |id| observe?(id, nil) }
+            return unless kind == :gross
+
+            observe?('BT-147-01', nil)
+            observe?('BT-147', nil)
+          end
+
+          def gross_discount(parent, value)
+            return observe_missing_discount? unless value
+            return unless observe?('BT-147-01', false) && observe?('BT-147-02', false)
+
+            emit_discount(parent, value)
+          end
+
+          def observe_missing_discount?
+            observe?('BT-147-01', nil)
+            observe?('BT-147-02', nil, group_present: false)
+            observe?('BT-147', nil)
+          end
+
+          def emit_discount(parent, value)
+            container(parent, 'ram:AppliedTradeAllowanceCharge') do |node|
+              container(node, 'ram:ChargeIndicator') do |indicator|
+                technical(indicator, 'udt:Indicator', format_identifier_value('BT-147-02', false))
+              end
+              emit('BT-147', value, element: 'ram:ActualAmount', parent: node)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/facturx/writer/stages/trade_lines/product.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Writer
+    module Stages
+      class TradeLines
+        class Product < Stage
+          def call(parent:, value:)
+            within_group('BG-31', value, element: 'ram:SpecifiedTradeProduct', parent:,
+                                         represented_attributes: %i[attributes classifications]) do |node, item|
+              identifiers(node, item)
+              emit('BT-153', item.name, element: 'ram:Name', parent: node)
+              emit('BT-154', item.description, element: 'ram:Description', parent: node)
+              attributes(node, item.attributes)
+              classifications(node, item.classifications)
+              origin_country(node, item.origin_country_code)
+            end
+          end
+
+          private
+
+          def identifiers(parent, item)
+            emit_compound_identifier(parent, item.global_identifier, value_id: 'BT-157', scheme_id: 'BT-157-1',
+                                                                     element: 'ram:GlobalID')
+            emit_identifier_value('BT-155', item.seller_identifier, 'ram:SellerAssignedID', parent)
+            emit_identifier_value('BT-156', item.buyer_identifier, 'ram:BuyerAssignedID', parent)
+          end
+
+          def attributes(parent, values)
+            each_group('BG-32', values, element: 'ram:ApplicableProductCharacteristic', parent:) do |node, item|
+              emit('BT-160', item.name, element: 'ram:Description', parent: node)
+              emit('BT-161', item.value, element: 'ram:Value', parent: node)
+            end
+          end
+
+          def classifications(parent, values)
+            emit_unrepresentable_classifications(parent, values)
+            emit_representable_classifications(parent, values)
+          end
+
+          def emit_unrepresentable_classifications(parent, values)
+            Array(values).reject { |item| classification_code?(item) }.each do |item|
+              classification(parent, item)
+            end
+          end
+
+          def emit_representable_classifications(parent, values)
+            items = Array(values).select { |item| classification_code?(item) }
+            return unless observe?('BT-158', items.map(&:code))
+
+            items.each { |item| classification(parent, item) }
+          end
+
+          def classification_code?(item)
+            !item.code.to_s.strip.empty?
+          end
+
+          def classification(parent, item)
+            container(parent, 'ram:DesignatedProductClassification') do |node|
+              code = technical(node, 'ram:ClassCode', format_identifier_value('BT-158', item.code))
+              emit_attribute('BT-158-1', item.list_id, node: code, attribute: 'listID', group_present: !code.nil?)
+              emit_attribute('BT-158-2', item.list_version_id, node: code, attribute: 'listVersionID',
+                                                               group_present: !code.nil?)
+            end
+          end
+
+          def origin_country(parent, value)
+            return observe?('BT-159', nil) unless value
+
+            container(parent, 'ram:OriginTradeCountry') do |node|
+              emit('BT-159', value, element: 'ram:ID', parent: node)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/facturx/writer/stages/trade_lines/quantity.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Writer
+    module Stages
+      class TradeLines
+        class Quantity < Stage
+          def call(parent:, value:, amount_id:, unit_id:, element:)
+            node = emit(amount_id, value&.value, element:, parent:).first
+            emit_attribute(unit_id, value&.unit_code, node:, attribute: 'unitCode',
+                                                      group_present: !node.nil?)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/facturx/writer/stages/trade_lines/settlement.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Writer
+    module Stages
+      class TradeLines
+        class Settlement < Stage
+          ADJUSTMENT_IDS = {
+            'BG-27' => %w[BT-138 BT-137 BT-136 BT-140 BT-139],
+            'BG-28' => %w[BT-143 BT-142 BT-141 BT-145 BT-144]
+          }.freeze
+
+          def call(parent:, line:)
+            node = context.element(parent, 'ram:SpecifiedLineTradeSettlement')
+            line_tax(node, line.tax)
+            period(node, line.period)
+            adjustment_groups(node, line.allowances, 'BG-27', false)
+            adjustment_groups(node, line.charges, 'BG-28', true)
+            monetary_sum(node, line.net_amount)
+            line_invoiced_object(node, line.invoiced_object_identifier)
+            accounting_reference(node, 'BT-133', line.buyer_accounting_reference)
+          end
+
+          private
+
+          def line_tax(parent, value)
+            within_group('BG-30', value, element: 'ram:ApplicableTradeTax', parent:,
+                                         represented_attributes: [:type_code]) do |node, item|
+              technical(node, 'ram:TypeCode', item.type_code, default: 'VAT')
+              emit('BT-151', item.category_code, element: 'ram:CategoryCode', parent: node)
+              emit('BT-152', item.rate, element: 'ram:RateApplicablePercent', parent: node)
+            end
+          end
+
+          def period(parent, value)
+            within_group('BG-26', value, element: 'ram:BillingSpecifiedPeriod', parent:) do |node, item|
+              emit_date(node, 'BT-134', item.start_date, wrapper: 'ram:StartDateTime')
+              emit_date(node, 'BT-135', item.end_date, wrapper: 'ram:EndDateTime')
+            end
+          end
+
+          def adjustment_groups(parent, values, group_id, indicator)
+            ids = ADJUSTMENT_IDS.fetch(group_id)
+            each_group(group_id, values, element: 'ram:SpecifiedTradeAllowanceCharge', parent:,
+                                         represented_attributes: [:indicator]) do |node, item|
+              report_unrepresentable_attributes(group_id, item.tax) if item.tax
+              adjustment_indicator(node, group_id, indicator)
+              emit_adjustment_fields(node, item, ids)
+            end
+          end
+
+          def emit_adjustment_fields(parent, item, ids)
+            emit(ids[0], item.percentage, element: 'ram:CalculationPercent', parent:)
+            emit(ids[1], item.base_amount, element: 'ram:BasisAmount', parent:)
+            emit(ids[2], item.amount, element: 'ram:ActualAmount', parent:)
+            emit(ids[3], item.reason_code, element: 'ram:ReasonCode', parent:)
+            emit(ids[4], item.reason, element: 'ram:Reason', parent:)
+          end
+
+          def adjustment_indicator(parent, group_id, value)
+            within_group("#{group_id}-0", value, element: 'ram:ChargeIndicator', parent:) do |node, indicator|
+              within_group("#{group_id}-1", indicator, element: 'udt:Indicator', parent: node) do |leaf, raw|
+                leaf.content = raw ? 'true' : 'false'
+              end
+            end
+          end
+
+          def monetary_sum(parent, value)
+            container(parent, 'ram:SpecifiedTradeSettlementLineMonetarySummation') do |node|
+              emit('BT-131', value, element: 'ram:LineTotalAmount', parent: node)
+            end
+          end
+
+          def line_invoiced_object(parent, value)
+            emit_invoiced_object(parent, value, 'BT-128', 'BT-128-1')
+          end
+
+          def accounting_reference(parent, id, value)
+            return observe?(id, nil) unless value
+
+            container(parent, 'ram:ReceivableSpecifiedTradeAccountingAccount') do |node|
+              emit(id, value, element: 'ram:ID', parent: node)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/facturx/writer/stages/trade_lines.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Writer
+    module Stages
+      class TradeLines < Stage
+        REPRESENTED_ATTRIBUTES = %i[
+          product gross_price net_price tax period allowances charges buyer_order_reference
+        ].freeze
+
+        term_ids(*%w[
+                   BT-126 BT-127 BT-157 BT-157-1 BT-155 BT-156 BT-153 BT-154 BT-160 BT-161 BT-158 BT-158-1
+                   BT-158-2 BT-159 BT-132 BT-148 BT-149-1 BT-150-1 BT-147-01 BT-147-02 BT-147 BT-146 BT-149
+                   BT-150 BT-129 BT-130 BT-151 BT-152 BT-134 BT-135 BT-138 BT-137 BT-136 BT-140 BT-139 BT-143
+                   BT-142 BT-141 BT-145 BT-144 BT-131 BT-128 BT-128-1 BT-133
+                 ])
+
+        def initialize(context)
+          super
+          quantity = Quantity.new(context)
+          @product = Product.new(context)
+          @agreement = Agreement.new(context, quantity:)
+          @settlement = Settlement.new(context)
+          @quantity = quantity
+        end
+
+        def call
+          each_group('BG-25', document.lines, element: 'ram:IncludedSupplyChainTradeLineItem',
+                                              parent: context.transaction,
+                                              represented_attributes: REPRESENTED_ATTRIBUTES) do |node, line|
+            line_document(node, line)
+            @product.call(parent: node, value: line.product)
+            @agreement.call(parent: node, line:)
+            delivery(node, line)
+            @settlement.call(parent: node, line:)
+          end
+        end
+
+        private
+
+        def line_document(parent, line)
+          container(parent, 'ram:AssociatedDocumentLineDocument') do |node|
+            emit('BT-126', line.id, element: 'ram:LineID', parent: node)
+            if line.note
+              container(node, 'ram:IncludedNote') do |note|
+                emit('BT-127', line.note, element: 'ram:Content', parent: note)
+              end
+            else
+              observe?('BT-127', nil)
+            end
+          end
+        end
+
+        def delivery(parent, line)
+          node = context.element(parent, 'ram:SpecifiedLineTradeDelivery')
+          @quantity.call(parent: node, value: line.quantity, amount_id: 'BT-129', unit_id: 'BT-130',
+                         element: 'ram:BilledQuantity')
+        end
+      end
+    end
+  end
+end
+
+require_relative 'trade_lines/quantity'
+require_relative 'trade_lines/product'
+require_relative 'trade_lines/agreement'
+require_relative 'trade_lines/settlement'

data/lib/facturx/writer/stages/trade_settlement/parties.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Writer
+    module Stages
+      module TradeSettlementParties
+        private
+
+        def payee(parent)
+          within_group('BG-10', document.payee, element: 'ram:PayeeTradeParty', parent:) do |node, party|
+            emit_party_identifiers(node, party.identifiers, 'BT-60', 'BT-60-1')
+            emit('BT-59', party.name, element: 'ram:Name', parent: node)
+            payee_legal_organization(node, party)
+          end
+        end
+
+        def payee_legal_organization(parent, party)
+          legal = party.legal_registration
+          return missing_payee_registration? unless legal
+
+          container(parent, 'ram:SpecifiedLegalOrganization') do |node|
+            emit_compound_identifier(node, legal, value_id: 'BT-61', scheme_id: 'BT-61-1', element: 'ram:ID')
+          end
+        end
+
+        def missing_payee_registration?
+          observe?('BT-61', nil)
+          observe?('BT-61-1', nil, group_present: false)
+        end
+      end
+    end
+  end
+end

data/lib/facturx/writer/stages/trade_settlement/payment.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Facturx
+  class Writer
+    module Stages
+      module TradeSettlementPayment
+        private
+
+        def payment_means(parent, payment)
+          value = payment if payment_means_present?(payment)
+          within_group('BG-16', value, element: 'ram:SpecifiedTradeSettlementPaymentMeans', parent:,
+                                       represented_attributes: %i[
+                                         remittance_information payment_card direct_debit credit_transfers
+                                       ]) do |node, item|
+            emit_payment_means(parent, node, item)
+          end
+        end
+
+        def emit_payment_means(parent, node, payment)
+          transfers = payment.credit_transfers
+          nodes = [node, *additional_payment_means(parent, transfers)]
+          means_code, means_text = payment_descriptions(node, payment)
+          duplicate_payment_terms(nodes.drop(1), means_code, means_text)
+          payment_card(node, payment.payment_card)
+          debtor_account(node, payment.direct_debit)
+          credit_transfers(nodes, transfers)
+        end
+
+        def payment_descriptions(parent, payment)
+          code = emit('BT-81', payment.means_code, element: 'ram:TypeCode', parent:).first&.text
+          text = emit('BT-82', payment.means_text, element: 'ram:Information', parent:).first&.text
+          [code, text]
+        end
+
+        def additional_payment_means(parent, transfers)
+          Array.new([Array(transfers).size - 1, 0].max) do
+            context.element(parent, 'ram:SpecifiedTradeSettlementPaymentMeans')
+          end
+        end
+
+        def duplicate_payment_terms(nodes, means_code, means_text)
+          nodes.each do |node|
+            technical(node, 'ram:TypeCode', means_code)
+            technical(node, 'ram:Information', means_text)
+          end
+        end
+
+        def payment_means_present?(payment)
+          return false unless payment
+
+          [payment.means_code, payment.means_text, payment.payment_card,
+           payment.direct_debit&.debtor_account_identifier, *payment.credit_transfers].any?
+        end
+
+        def payment_card(parent, value)
+          within_group('BG-18', value, element: 'ram:ApplicableTradeSettlementFinancialCard', parent:) do |node, card|
+            emit('BT-87', card.primary_account_number, element: 'ram:ID', parent: node)
+            emit('BT-88', card.holder_name, element: 'ram:CardholderName', parent: node)
+          end
+        end
+
+        def debtor_account(parent, value)
+          identifier = value&.debtor_account_identifier
+          return observe?('BT-91', nil) unless identifier
+
+          container(parent, 'ram:PayerPartyDebtorFinancialAccount') do |node|
+            emit_identifier_value('BT-91', identifier, 'ram:IBANID', node)
+          end
+        end
+
+        def credit_transfers(parents, values)
+          transfers = Array(values)
+          group = Terms.group('BG-17')
+          return unless tracker.observe_group?(group, count: transfers.size, path: group.xpath)
+
+          transfers.zip(parents).each { |item, parent| emit_credit_transfer(parent, item) }
+        end
+
+        def emit_credit_transfer(parent, transfer)
+          container(parent, 'ram:PayeePartyCreditorFinancialAccount') do |node|
+            emit_identifier_value('BT-84', transfer.account_identifier, 'ram:IBANID', node)
+            emit('BT-85', transfer.account_name, element: 'ram:AccountName', parent: node)
+          end
+          emit_provider(parent, transfer.provider_identifier)
+        end
+
+        def emit_provider(parent, identifier)
+          return observe?('BT-86', nil) unless identifier
+
+          container(parent, 'ram:PayeeSpecifiedCreditorFinancialInstitution') do |node|
+            emit_identifier_value('BT-86', identifier, 'ram:BICID', node)
+          end
+        end
+      end
+    end
+  end
+end