factur-x-builder 0.1.0

data/lib/factur_x/document.rb

@@ -0,0 +1,400 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+require_relative "codes"
+require_relative "formatting"
+
+module FacturX
+  # Serialises an Invoice to Cross Industry Invoice XML.
+  #
+  # Every complex type in the CII schema is an xs:sequence, so the order in
+  # which the emit_* methods write their children is significant and mirrors
+  # the XSD. Ordering mistakes surface as schema violations in the test suite.
+  class Document
+    RSM = "urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100"
+    RAM = "urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100"
+    QDT = "urn:un:unece:uncefact:data:standard:QualifiedDataType:100"
+    UDT = "urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100"
+    XSI = "http://www.w3.org/2001/XMLSchema-instance"
+
+    NAMESPACES = {
+      "xmlns:rsm" => RSM,
+      "xmlns:qdt" => QDT,
+      "xmlns:ram" => RAM,
+      "xmlns:udt" => UDT,
+      "xmlns:xsi" => XSI
+    }.freeze
+
+    def initialize(invoice)
+      @invoice = invoice
+    end
+
+    def to_xml(indent: 2)
+      to_document.to_xml(indent: indent, encoding: "UTF-8")
+    end
+
+    def to_document
+      @to_document ||= build
+    end
+
+    private
+
+    attr_reader :invoice
+
+    def build
+      Nokogiri::XML::Builder.new(encoding: "UTF-8") do |xml|
+        xml.CrossIndustryInvoice(NAMESPACES) do
+          xml.parent.namespace = xml.parent.namespace_definitions.find { |ns| ns.prefix == "rsm" }
+          emit_document_context(xml)
+          emit_exchanged_document(xml)
+          emit_trade_transaction(xml)
+        end
+      end.doc
+    end
+
+    def emit_document_context(xml)
+      xml["rsm"].ExchangedDocumentContext do
+        if invoice.business_process
+          xml["ram"].BusinessProcessSpecifiedDocumentContextParameter do
+            text(xml, :ID, invoice.business_process)
+          end
+        end
+        xml["ram"].GuidelineSpecifiedDocumentContextParameter do
+          text(xml, :ID, Codes::EN16931_GUIDELINE)
+        end
+      end
+    end
+
+    def emit_exchanged_document(xml)
+      xml["rsm"].ExchangedDocument do
+        text(xml, :ID, invoice.number)
+        text(xml, :TypeCode, invoice.type_code)
+        date(xml, :IssueDateTime, invoice.issued_on)
+        invoice.notes.each { |note| emit_note(xml, note) }
+      end
+    end
+
+    def emit_note(xml, note)
+      xml["ram"].IncludedNote do
+        text(xml, :Content, note.content)
+        text(xml, :SubjectCode, note.subject_code)
+      end
+    end
+
+    def emit_trade_transaction(xml)
+      xml["rsm"].SupplyChainTradeTransaction do
+        invoice.lines.each { |line| emit_line(xml, line) }
+        emit_header_agreement(xml)
+        emit_header_delivery(xml)
+        emit_header_settlement(xml)
+      end
+    end
+
+    def emit_line(xml, line)
+      xml["ram"].IncludedSupplyChainTradeLineItem do
+        xml["ram"].AssociatedDocumentLineDocument do
+          text(xml, :LineID, line.number)
+          xml["ram"].IncludedNote { text(xml, :Content, line.note) } if line.note
+        end
+        emit_line_product(xml, line)
+        emit_line_agreement(xml, line)
+        xml["ram"].SpecifiedLineTradeDelivery do
+          text(xml, :BilledQuantity, Formatting.quantity(line.quantity), unitCode: line.unit_code)
+        end
+        emit_line_settlement(xml, line)
+      end
+    end
+
+    def emit_line_product(xml, line)
+      xml["ram"].SpecifiedTradeProduct do
+        text(xml, :GlobalID, line.global_id, scheme_attribute(line.global_id_scheme))
+        text(xml, :SellerAssignedID, line.seller_item_id)
+        text(xml, :BuyerAssignedID, line.buyer_item_id)
+        text(xml, :Name, line.name)
+        text(xml, :Description, line.description)
+        xml["ram"].OriginTradeCountry { text(xml, :ID, line.origin_country) } if line.origin_country
+      end
+    end
+
+    def emit_line_agreement(xml, line)
+      xml["ram"].SpecifiedLineTradeAgreement do
+        xml["ram"].BuyerOrderReferencedDocument { text(xml, :LineID, line.order_line_id) } if line.order_line_id
+        if line.gross_price?
+          xml["ram"].GrossPriceProductTradePrice do
+            text(xml, :ChargeAmount, Formatting.unit_price(line.gross_unit_price))
+            emit_unit_discount(xml, line) if line.unit_discount
+          end
+        end
+        xml["ram"].NetPriceProductTradePrice do
+          text(xml, :ChargeAmount, Formatting.unit_price(line.unit_price))
+        end
+      end
+    end
+
+    def emit_unit_discount(xml, line)
+      xml["ram"].AppliedTradeAllowanceCharge do
+        xml["ram"].ChargeIndicator { boolean(xml, :Indicator, false) }
+        text(xml, :ActualAmount, Formatting.unit_price(line.unit_discount))
+      end
+    end
+
+    def emit_line_settlement(xml, line)
+      xml["ram"].SpecifiedLineTradeSettlement do
+        xml["ram"].ApplicableTradeTax do
+          text(xml, :TypeCode, Codes::VAT_TYPE)
+          text(xml, :CategoryCode, line.vat_category)
+          text(xml, :RateApplicablePercent, Formatting.percentage(line.vat_rate_decimal))
+        end
+        emit_period(xml, line.period_start, line.period_end)
+        xml["ram"].SpecifiedTradeSettlementLineMonetarySummation do
+          text(xml, :LineTotalAmount, Formatting.amount(line.net_amount))
+        end
+        if line.accounting_reference
+          xml["ram"].ReceivableSpecifiedTradeAccountingAccount do
+            text(xml, :ID, line.accounting_reference)
+          end
+        end
+      end
+    end
+
+    def emit_header_agreement(xml)
+      xml["ram"].ApplicableHeaderTradeAgreement do
+        text(xml, :BuyerReference, invoice.buyer_reference)
+        emit_party(xml, :SellerTradeParty, invoice.seller)
+        emit_party(xml, :BuyerTradeParty, invoice.buyer)
+        emit_party(xml, :SellerTaxRepresentativeTradeParty, invoice.tax_representative)
+        emit_referenced_document(xml, :SellerOrderReferencedDocument, invoice.sales_order_reference)
+        emit_referenced_document(xml, :BuyerOrderReferencedDocument, invoice.purchase_order_reference)
+        emit_referenced_document(xml, :ContractReferencedDocument, invoice.contract_reference)
+        emit_project(xml)
+      end
+    end
+
+    def emit_project(xml)
+      return unless invoice.project_reference
+
+      xml["ram"].SpecifiedProcuringProject do
+        text(xml, :ID, invoice.project_reference)
+        text(xml, :Name, invoice.project_name || invoice.project_reference)
+      end
+    end
+
+    def emit_header_delivery(xml)
+      xml["ram"].ApplicableHeaderTradeDelivery do
+        emit_party(xml, :ShipToTradeParty, invoice.ship_to)
+        if invoice.delivered_on
+          xml["ram"].ActualDeliverySupplyChainEvent do
+            date(xml, :OccurrenceDateTime, invoice.delivered_on)
+          end
+        end
+        emit_referenced_document(xml, :DespatchAdviceReferencedDocument,
+                                 invoice.despatch_advice_reference)
+        emit_referenced_document(xml, :ReceivingAdviceReferencedDocument,
+                                 invoice.receiving_advice_reference)
+      end
+    end
+
+    def emit_header_settlement(xml)
+      xml["ram"].ApplicableHeaderTradeSettlement do
+        text(xml, :CreditorReferenceID, invoice.creditor_reference)
+        text(xml, :PaymentReference, invoice.payment_reference)
+        text(xml, :InvoiceCurrencyCode, invoice.currency)
+        emit_party(xml, :PayeeTradeParty, invoice.payee)
+        invoice.payment_means.each { |means| emit_payment_means(xml, means) }
+        invoice.tax_breakdowns.each { |breakdown| emit_tax_breakdown(xml, breakdown) }
+        emit_period(xml, invoice.billing_period_start, invoice.billing_period_end)
+        (invoice.allowances + invoice.charges).each { |item| emit_allowance_charge(xml, item) }
+        emit_payment_terms(xml)
+        emit_totals(xml)
+        invoice.preceding_invoices.each { |reference| emit_preceding_invoice(xml, reference) }
+      end
+    end
+
+    def emit_payment_means(xml, means)
+      xml["ram"].SpecifiedTradeSettlementPaymentMeans do
+        text(xml, :TypeCode, means.type_code)
+        text(xml, :Information, means.information)
+        if means.card?
+          xml["ram"].ApplicableTradeSettlementFinancialCard do
+            text(xml, :ID, means.card_id)
+            text(xml, :CardholderName, means.cardholder_name)
+          end
+        end
+        xml["ram"].PayerPartyDebtorFinancialAccount { text(xml, :IBANID, means.debtor_iban) } if means.debtor_iban
+        if means.creditor_account?
+          xml["ram"].PayeePartyCreditorFinancialAccount do
+            text(xml, :IBANID, means.iban)
+            text(xml, :AccountName, means.account_name)
+            text(xml, :ProprietaryID, means.account_id)
+          end
+        end
+        xml["ram"].PayeeSpecifiedCreditorFinancialInstitution { text(xml, :BICID, means.bic) } if means.bic
+      end
+    end
+
+    def emit_tax_breakdown(xml, breakdown)
+      xml["ram"].ApplicableTradeTax do
+        text(xml, :CalculatedAmount, Formatting.amount(breakdown.calculated_amount))
+        text(xml, :TypeCode, Codes::VAT_TYPE)
+        text(xml, :ExemptionReason, breakdown.exemption_reason)
+        text(xml, :BasisAmount, Formatting.amount(breakdown.basis_amount))
+        text(xml, :CategoryCode, breakdown.category)
+        text(xml, :ExemptionReasonCode, breakdown.exemption_reason_code)
+        text(xml, :RateApplicablePercent, Formatting.percentage(breakdown.rate_decimal))
+      end
+    end
+
+    def emit_allowance_charge(xml, item)
+      xml["ram"].SpecifiedTradeAllowanceCharge do
+        xml["ram"].ChargeIndicator { boolean(xml, :Indicator, item.charge?) }
+        text(xml, :CalculationPercent, Formatting.percentage(item.percentage)) if item.percentage
+        text(xml, :BasisAmount, Formatting.amount(item.basis_amount)) if item.basis_amount
+        text(xml, :ActualAmount, Formatting.amount(item.amount))
+        text(xml, :ReasonCode, item.reason_code)
+        text(xml, :Reason, item.reason)
+        xml["ram"].CategoryTradeTax do
+          text(xml, :TypeCode, Codes::VAT_TYPE)
+          text(xml, :CategoryCode, item.vat_category)
+          text(xml, :RateApplicablePercent, Formatting.percentage(item.vat_rate || 0))
+        end
+      end
+    end
+
+    def emit_payment_terms(xml)
+      terms = invoice.payment_terms
+      return if terms.nil? || terms.empty?
+
+      xml["ram"].SpecifiedTradePaymentTerms do
+        text(xml, :Description, terms.description)
+        date(xml, :DueDateDateTime, terms.due_on)
+        text(xml, :DirectDebitMandateID, terms.mandate_reference)
+      end
+    end
+
+    def emit_totals(xml)
+      totals = invoice.totals
+      xml["ram"].SpecifiedTradeSettlementHeaderMonetarySummation do
+        text(xml, :LineTotalAmount, Formatting.amount(totals.line_total))
+        text(xml, :ChargeTotalAmount, optional_amount(totals.charge_total))
+        text(xml, :AllowanceTotalAmount, optional_amount(totals.allowance_total))
+        text(xml, :TaxBasisTotalAmount, Formatting.amount(totals.tax_basis_total))
+        text(xml, :TaxTotalAmount, Formatting.amount(totals.tax_total_decimal),
+             currencyID: invoice.currency)
+        text(xml, :RoundingAmount, optional_amount(totals.rounding_amount))
+        text(xml, :GrandTotalAmount, Formatting.amount(totals.grand_total))
+        text(xml, :TotalPrepaidAmount, optional_amount(totals.prepaid))
+        text(xml, :DuePayableAmount, Formatting.amount(totals.due_payable))
+      end
+    end
+
+    def emit_preceding_invoice(xml, reference)
+      xml["ram"].InvoiceReferencedDocument do
+        text(xml, :IssuerAssignedID, reference.number)
+        next unless reference.issued_on
+
+        xml["ram"].FormattedIssueDateTime do
+          xml["qdt"].DateTimeString(Formatting.date(reference.issued_on),
+                                    format: Formatting::CII_DATE_FORMAT_CODE)
+        end
+      end
+    end
+
+    def emit_party(xml, element_name, party)
+      return if party.nil?
+
+      xml["ram"].send(element_name) do
+        text(xml, :GlobalID, party.global_id, scheme_attribute(party.global_id_scheme))
+        text(xml, :Name, party.name)
+        emit_legal_organization(xml, party)
+        emit_contact(xml, party)
+        emit_address(xml, party.address)
+        if party.routing_id
+          xml["ram"].URIUniversalCommunication do
+            text(xml, :URIID, party.routing_id, scheme_attribute(party.routing_id_scheme))
+          end
+        end
+        party.tax_registrations.each do |value, scheme|
+          xml["ram"].SpecifiedTaxRegistration { text(xml, :ID, value, schemeID: scheme) }
+        end
+      end
+    end
+
+    def emit_legal_organization(xml, party)
+      return unless party.legal_id || party.trading_name
+
+      xml["ram"].SpecifiedLegalOrganization do
+        text(xml, :ID, party.legal_id, scheme_attribute(party.legal_id_scheme))
+        text(xml, :TradingBusinessName, party.trading_name)
+      end
+    end
+
+    def emit_contact(xml, party)
+      return unless party.contact?
+
+      contact = party.contact
+      xml["ram"].DefinedTradeContact do
+        text(xml, :PersonName, contact.person_name)
+        text(xml, :DepartmentName, contact.department_name)
+        xml["ram"].TelephoneUniversalCommunication { text(xml, :CompleteNumber, contact.phone) } if contact.phone
+        xml["ram"].EmailURIUniversalCommunication { text(xml, :URIID, contact.email) } if contact.email
+      end
+    end
+
+    def emit_address(xml, address)
+      return if address.nil?
+
+      xml["ram"].PostalTradeAddress do
+        text(xml, :PostcodeCode, address.postcode)
+        text(xml, :LineOne, address.line_one)
+        text(xml, :LineTwo, address.line_two)
+        text(xml, :LineThree, address.line_three)
+        text(xml, :CityName, address.city)
+        text(xml, :CountryID, address.country_code)
+        text(xml, :CountrySubDivisionName, address.country_subdivision)
+      end
+    end
+
+    def emit_referenced_document(xml, element_name, reference)
+      return if reference.nil?
+
+      xml["ram"].send(element_name) { text(xml, :IssuerAssignedID, reference) }
+    end
+
+    def emit_period(xml, starts_on, ends_on)
+      return if starts_on.nil? && ends_on.nil?
+
+      xml["ram"].BillingSpecifiedPeriod do
+        date(xml, :StartDateTime, starts_on)
+        date(xml, :EndDateTime, ends_on)
+      end
+    end
+
+    def text(xml, name, value, attributes = {})
+      return if value.nil?
+
+      xml["ram"].send(name, value.to_s, attributes)
+    end
+
+    def boolean(xml, name, value)
+      xml["udt"].send(name, value.to_s)
+    end
+
+    def date(xml, name, value)
+      return if value.nil?
+
+      xml["ram"].send(name) do
+        xml["udt"].DateTimeString(Formatting.date(value),
+                                  format: Formatting::CII_DATE_FORMAT_CODE)
+      end
+    end
+
+    def optional_amount(value)
+      value.nil? ? nil : Formatting.amount(value)
+    end
+
+    def scheme_attribute(scheme)
+      scheme.nil? ? {} : { schemeID: scheme }
+    end
+  end
+end

data/lib/factur_x/errors.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module FacturX
+  class Error < StandardError; end
+
+  # Raised when the invoice breaks an EN 16931 (or French) business rule.
+  class ValidationError < Error
+    attr_reader :violations
+
+    def initialize(violations)
+      @violations = Array(violations)
+      super(build_message)
+    end
+
+    private
+
+    def build_message
+      return "invoice is not valid" if violations.empty?
+
+      "invoice is not valid:\n#{bulleted(violations)}"
+    end
+
+    def bulleted(items)
+      items.map { |item| "  - #{item}" }.join("\n")
+    end
+  end
+
+  # Raised when the generated document does not conform to the Factur-X XSD.
+  # This signals a bug in the gem rather than bad input.
+  class SchemaError < Error
+    attr_reader :violations
+
+    def initialize(violations)
+      @violations = Array(violations)
+      details = @violations.map { |violation| "  - #{violation}" }.join("\n")
+      super("generated XML does not conform to the Factur-X EN 16931 schema:\n#{details}")
+    end
+  end
+end

data/lib/factur_x/formatting.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "bigdecimal/util"
+
+module FacturX
+  module Formatting
+    AMOUNT_SCALE = 2
+    PERCENTAGE_SCALE = 2
+    UNIT_PRICE_SCALE = 4
+    QUANTITY_SCALE = 4
+
+    CII_DATE_FORMAT = "%Y%m%d"
+    CII_DATE_FORMAT_CODE = "102"
+
+    module_function
+
+    def amount(value)
+      fixed(value, AMOUNT_SCALE)
+    end
+
+    def percentage(value)
+      fixed(value, PERCENTAGE_SCALE)
+    end
+
+    def unit_price(value)
+      trimmed(value, UNIT_PRICE_SCALE, AMOUNT_SCALE)
+    end
+
+    def quantity(value)
+      trimmed(value, QUANTITY_SCALE, 0)
+    end
+
+    def date(value)
+      to_date(value).strftime(CII_DATE_FORMAT)
+    end
+
+    def decimal(value)
+      case value
+      when BigDecimal then value
+      when Integer then BigDecimal(value)
+      when Float then BigDecimal(value.to_s)
+      when String then parse_string(value)
+      when nil then raise Error, "expected a number, got nil"
+      else coerce(value)
+      end
+    end
+
+    def fixed(value, scale)
+      integer, fraction = decimal(value).round(scale).to_s("F").split(".")
+      "#{integer}.#{fraction.ljust(scale, "0")}"
+    end
+
+    # Renders with `scale` decimals at most, dropping trailing zeros but never
+    # falling below `minimum_scale` (BT-146 allows 4 decimals, BT-129 allows none).
+    def trimmed(value, scale, minimum_scale)
+      rounded = decimal(value).round(scale)
+      integer, fraction = rounded.to_s("F").split(".")
+      fraction = fraction.sub(/0+\z/, "").ljust(minimum_scale, "0")
+      fraction.empty? ? integer : "#{integer}.#{fraction}"
+    end
+
+    def parse_string(value)
+      BigDecimal(value)
+    rescue ArgumentError
+      raise Error, "#{value.inspect} is not a valid number"
+    end
+
+    def coerce(value)
+      return value.to_d if value.respond_to?(:to_d)
+
+      raise Error, "cannot convert #{value.class} to a number"
+    end
+
+    def to_date(value)
+      return value if value.respond_to?(:strftime)
+      return Date.parse(value) if value.is_a?(String)
+
+      raise Error, "cannot convert #{value.class} to a date"
+    end
+
+    private_class_method :parse_string, :coerce, :to_date
+  end
+end

data/lib/factur_x/invoice.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "codes"
+
+module FacturX
+  class Invoice
+    attr_reader :number, :type_code, :issued_on, :currency, :business_process,
+                :notes, :buyer_reference, :seller, :buyer, :payee,
+                :tax_representative, :ship_to, :delivered_on,
+                :payment_reference, :creditor_reference, :payment_means, :payment_terms,
+                :lines, :allowances, :charges, :tax_breakdowns, :totals,
+                :purchase_order_reference, :sales_order_reference, :contract_reference,
+                :project_reference, :project_name, :despatch_advice_reference,
+                :receiving_advice_reference, :preceding_invoices,
+                :billing_period_start, :billing_period_end
+
+    def initialize(number:, issued_on:, seller:, buyer:, lines:, tax_breakdowns:, totals:,
+                   type_code: Codes::COMMERCIAL_INVOICE, currency: "EUR",
+                   business_process: nil, notes: [], buyer_reference: nil,
+                   payee: nil, tax_representative: nil, ship_to: nil, delivered_on: nil,
+                   payment_reference: nil, creditor_reference: nil,
+                   payment_means: [], payment_terms: nil,
+                   allowances: [], charges: [],
+                   purchase_order_reference: nil, sales_order_reference: nil,
+                   contract_reference: nil, project_reference: nil, project_name: nil,
+                   despatch_advice_reference: nil, receiving_advice_reference: nil,
+                   preceding_invoices: [],
+                   billing_period_start: nil, billing_period_end: nil)
+      @number = number
+      @type_code = type_code
+      @issued_on = issued_on
+      @currency = currency
+      @business_process = business_process
+      @notes = Array(notes)
+      @buyer_reference = buyer_reference
+      @seller = seller
+      @buyer = buyer
+      @payee = payee
+      @tax_representative = tax_representative
+      @ship_to = ship_to
+      @delivered_on = delivered_on
+      @payment_reference = payment_reference
+      @creditor_reference = creditor_reference
+      @payment_means = Array(payment_means)
+      @payment_terms = payment_terms
+      @lines = number_lines(Array(lines))
+      @allowances = Array(allowances)
+      @charges = Array(charges)
+      @tax_breakdowns = Array(tax_breakdowns)
+      @totals = totals
+      @purchase_order_reference = purchase_order_reference
+      @sales_order_reference = sales_order_reference
+      @contract_reference = contract_reference
+      @project_reference = project_reference
+      @project_name = project_name
+      @despatch_advice_reference = despatch_advice_reference
+      @receiving_advice_reference = receiving_advice_reference
+      @preceding_invoices = Array(preceding_invoices)
+      @billing_period_start = billing_period_start
+      @billing_period_end = billing_period_end
+    end
+
+    def credit_note?
+      type_code == Codes::CREDIT_NOTE
+    end
+
+    def billing_period?
+      !billing_period_start.nil? || !billing_period_end.nil?
+    end
+
+    def to_xml(**options)
+      FacturX.build(self, **options)
+    end
+
+    private
+
+    def number_lines(lines)
+      lines.each_with_index.map { |line, index| line.with_number(index + 1) }
+    end
+  end
+end

data/lib/factur_x/line.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative "codes"
+require_relative "formatting"
+
+module FacturX
+  class Line
+    attr_reader :number, :name, :description, :seller_item_id, :buyer_item_id,
+                :global_id, :global_id_scheme, :unit_price, :gross_unit_price,
+                :unit_discount, :quantity, :unit_code, :vat_category, :vat_rate,
+                :net_amount, :note, :origin_country, :period_start, :period_end,
+                :order_line_id, :accounting_reference
+
+    def initialize(name:, unit_price:, quantity:, net_amount:,
+                   number: nil, description: nil, seller_item_id: nil, buyer_item_id: nil,
+                   global_id: nil, global_id_scheme: nil, gross_unit_price: nil,
+                   unit_discount: nil, unit_code: Codes::PIECE_UNIT,
+                   vat_category: Codes::VatCategory::STANDARD, vat_rate: nil,
+                   note: nil, origin_country: nil, period_start: nil, period_end: nil,
+                   order_line_id: nil, accounting_reference: nil)
+      @number = number
+      @name = name
+      @description = description
+      @seller_item_id = seller_item_id
+      @buyer_item_id = buyer_item_id
+      @global_id = global_id
+      @global_id_scheme = global_id_scheme
+      @unit_price = unit_price
+      @gross_unit_price = gross_unit_price
+      @unit_discount = unit_discount
+      @quantity = quantity
+      @unit_code = unit_code
+      @vat_category = vat_category
+      @vat_rate = vat_rate
+      @net_amount = net_amount
+      @note = note
+      @origin_country = origin_country
+      @period_start = period_start
+      @period_end = period_end
+      @order_line_id = order_line_id
+      @accounting_reference = accounting_reference
+    end
+
+    def net_amount_decimal
+      Formatting.decimal(net_amount)
+    end
+
+    def vat_rate_decimal
+      Formatting.decimal(vat_rate || 0)
+    end
+
+    # Groups lines into VAT breakdowns: BR-S-08 and friends require one
+    # breakdown per (category, rate) pair.
+    def tax_key
+      [vat_category, vat_rate_decimal]
+    end
+
+    def gross_price?
+      !gross_unit_price.nil?
+    end
+
+    def with_number(value)
+      return self if number
+
+      self.class.new(**to_h, number: value)
+    end
+
+    def to_h
+      {
+        number: number, name: name, description: description,
+        seller_item_id: seller_item_id, buyer_item_id: buyer_item_id,
+        global_id: global_id, global_id_scheme: global_id_scheme,
+        unit_price: unit_price, gross_unit_price: gross_unit_price,
+        unit_discount: unit_discount, quantity: quantity, unit_code: unit_code,
+        vat_category: vat_category, vat_rate: vat_rate, net_amount: net_amount,
+        note: note, origin_country: origin_country,
+        period_start: period_start, period_end: period_end,
+        order_line_id: order_line_id, accounting_reference: accounting_reference
+      }
+    end
+  end
+end