factur-x-builder 0.1.0

data/lib/factur_x/schemas/Factur-X_EN16931.xsd

@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<xs:schema xmlns:rsm="urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100"
+    xmlns:xs="http://www.w3.org/2001/XMLSchema"
+    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"
+    targetNamespace="urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100"
+    elementFormDefault="qualified">
+  <xs:import namespace="urn:un:unece:uncefact:data:standard:QualifiedDataType:100" schemaLocation="Factur-X_1.09_EN16931_urn_un_unece_uncefact_data_standard_QualifiedDataType_100.xsd"/>
+  <xs:import namespace="urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100" schemaLocation="Factur-X_1.09_EN16931_urn_un_unece_uncefact_data_standard_ReusableAggregateBusinessInformationEntity_100.xsd"/>
+  <xs:import namespace="urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100" schemaLocation="Factur-X_1.09_EN16931_urn_un_unece_uncefact_data_standard_UnqualifiedDataType_100.xsd"/>
+  <xs:element name="CrossIndustryInvoice" type="rsm:CrossIndustryInvoiceType"/>
+  <xs:complexType name="CrossIndustryInvoiceType">
+    <xs:sequence>
+      <xs:element name="ExchangedDocumentContext" type="ram:ExchangedDocumentContextType"/>
+      <xs:element name="ExchangedDocument" type="ram:ExchangedDocumentType"/>
+      <xs:element name="SupplyChainTradeTransaction" type="ram:SupplyChainTradeTransactionType"/>
+    </xs:sequence>
+  </xs:complexType>
+</xs:schema>

data/lib/factur_x/tax_breakdown.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "codes"
+require_relative "formatting"
+
+module FacturX
+  # One VAT category / rate pair of the invoice (BG-23).
+  class TaxBreakdown
+    attr_reader :category, :rate, :basis_amount, :calculated_amount,
+                :exemption_reason, :exemption_reason_code
+
+    def initialize(basis_amount:, calculated_amount:,
+                   category: Codes::VatCategory::STANDARD, rate: nil,
+                   exemption_reason: nil, exemption_reason_code: nil)
+      @category = category
+      @rate = rate
+      @basis_amount = basis_amount
+      @calculated_amount = calculated_amount
+      @exemption_reason = exemption_reason
+      @exemption_reason_code = exemption_reason_code
+    end
+
+    def rate_decimal
+      Formatting.decimal(rate || 0)
+    end
+
+    def basis_amount_decimal
+      Formatting.decimal(basis_amount)
+    end
+
+    def calculated_amount_decimal
+      Formatting.decimal(calculated_amount)
+    end
+
+    def tax_key
+      [category, rate_decimal]
+    end
+  end
+end

data/lib/factur_x/totals.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "formatting"
+
+module FacturX
+  # The document level totals (BT-106 to BT-115). The gem never derives
+  # these; the invoicing domain supplies them and they are checked for
+  # coherence against the lines and the VAT breakdowns.
+  class Totals
+    attr_reader :line_total, :allowance_total, :charge_total, :tax_basis_total,
+                :tax_total, :rounding_amount, :grand_total, :prepaid, :due_payable
+
+    def initialize(line_total:, tax_basis_total:, grand_total:, due_payable:,
+                   tax_total: nil, allowance_total: nil, charge_total: nil,
+                   rounding_amount: nil, prepaid: nil)
+      @line_total = line_total
+      @allowance_total = allowance_total
+      @charge_total = charge_total
+      @tax_basis_total = tax_basis_total
+      @tax_total = tax_total
+      @rounding_amount = rounding_amount
+      @grand_total = grand_total
+      @prepaid = prepaid
+      @due_payable = due_payable
+    end
+
+    %i[line_total allowance_total charge_total tax_basis_total tax_total
+       rounding_amount grand_total prepaid due_payable].each do |field|
+      define_method("#{field}_decimal") do
+        value = public_send(field)
+        Formatting.decimal(value.nil? ? 0 : value)
+      end
+    end
+  end
+end

data/lib/factur_x/validation/rules.rb

@@ -0,0 +1,349 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+require_relative "../codes"
+require_relative "../errors"
+require_relative "../formatting"
+
+module FacturX
+  module Validation
+    # Business rules checked in Ruby so the invoicing domain gets fast,
+    # readable errors without shelling out to the official schematron.
+    # The rule identifiers refer to EN 16931; the schematron remains the
+    # authority and the test suite checks these rules agree with it.
+    class Rules
+      CURRENCY_PATTERN = /\A[A-Z]{3}\z/.freeze
+      COUNTRY_PATTERN = /\A[A-Z]{2}\z/.freeze
+      IBAN_PATTERN = /\A[A-Z]{2}[0-9]{2}[A-Z0-9]{10,30}\z/.freeze
+      SIRET_PATTERN = /\A[0-9]{14}\z/.freeze
+      SIREN_PATTERN = /\A[0-9]{9}\z/.freeze
+      VAT_NUMBER_PATTERN = /\A[A-Z]{2}[A-Z0-9]{2,13}\z/.freeze
+
+      ROUNDING_TOLERANCE = BigDecimal("0.01")
+
+      PROFILES = %i[en16931 fr_ctc].freeze
+
+      # BR-FR-05: every invoice must carry these three statements.
+      MANDATORY_FRENCH_NOTES = {
+        Codes::NoteSubject::PAYMENT_TERMS => "recovery costs",
+        Codes::NoteSubject::PAYMENT_PENALTIES => "late payment penalties",
+        Codes::NoteSubject::DISCOUNT_TERMS => "early payment discount"
+      }.freeze
+
+      def initialize(invoice, profile: :fr_ctc)
+        raise Error, "unknown profile #{profile.inspect}" unless PROFILES.include?(profile)
+
+        @invoice = invoice
+        @profile = profile
+        @violations = []
+      end
+
+      def violations
+        @violations = []
+        check_document
+        check_parties
+        check_lines
+        check_tax_breakdowns
+        check_payment
+        check_totals
+        check_french_requirements if french?
+        @violations
+      end
+
+      def valid?
+        violations.empty?
+      end
+
+      def validate!
+        found = violations
+        raise ValidationError, found unless found.empty?
+
+        invoice
+      end
+
+      private
+
+      attr_reader :invoice, :profile
+
+      def french?
+        profile == :fr_ctc
+      end
+
+      def add(message)
+        @violations << message
+      end
+
+      # Rules the French e-invoicing reform adds on top of EN 16931.
+      def check_french_requirements
+        if blank?(invoice.business_process)
+          add("an invoicing mode is required by the French e-invoicing reform (BT-23, " \
+              "BR-FR-08), expected one of #{Codes::BUSINESS_PROCESSES.join(", ")}")
+        end
+
+        declared = invoice.notes.map(&:subject_code)
+        MANDATORY_FRENCH_NOTES.each do |code, description|
+          next if declared.include?(code)
+
+          add("the mandatory statement about #{description} is missing from the invoice " \
+              "notes (BT-22 with subject code #{code}, BR-FR-05) - " \
+              "Note.french_legal_mentions provides the three of them")
+        end
+      end
+
+      def check_document
+        add("invoice number is required (BT-1)") if blank?(invoice.number)
+        add("issue date is required (BT-2)") if invoice.issued_on.nil?
+
+        unless Codes::DOCUMENT_TYPES.include?(invoice.type_code)
+          add("document type #{invoice.type_code.inspect} is not supported (BT-3), " \
+              "expected one of #{Codes::DOCUMENT_TYPES.join(", ")}")
+        end
+
+        unless invoice.currency.to_s.match?(CURRENCY_PATTERN)
+          add("currency #{invoice.currency.inspect} is not a 3-letter ISO 4217 code (BT-5)")
+        end
+
+        return unless invoice.business_process && !Codes::BUSINESS_PROCESSES.include?(invoice.business_process)
+
+        add("business process #{invoice.business_process.inspect} is not a Factur-X " \
+            "process identifier (BT-23)")
+      end
+
+      def check_parties
+        check_party(invoice.seller, "seller")
+        check_party(invoice.buyer, "buyer")
+
+        if invoice.seller && seller_identifier_missing?
+          add("seller must carry a VAT number, a tax registration or a legal registration " \
+              "identifier (BR-CO-9 / BR-FR-09)")
+        end
+
+        check_french_identifiers(invoice.seller, "seller")
+        check_french_identifiers(invoice.buyer, "buyer")
+      end
+
+      def check_party(party, role)
+        if party.nil?
+          add("#{role} is required (#{role == "seller" ? "BG-4" : "BG-7"})")
+          return
+        end
+
+        add("#{role} name is required") if blank?(party.name)
+
+        if party.address.nil?
+          add("#{role} postal address is required")
+          return
+        end
+
+        country = party.address.country_code
+        return if country.to_s.match?(COUNTRY_PATTERN)
+
+        add("#{role} country code #{country.inspect} is not a 2-letter ISO 3166 code")
+      end
+
+      def seller_identifier_missing?
+        seller = invoice.seller
+        [seller.vat_number, seller.tax_id, seller.legal_id, seller.global_id].all? { |v| blank?(v) }
+      end
+
+      def check_french_identifiers(party, role)
+        return if party.nil?
+
+        if party.siret && !party.siret.to_s.match?(SIRET_PATTERN)
+          add("#{role} SIRET #{party.siret.inspect} must be 14 digits")
+        end
+
+        if party.siren && !party.siren.to_s.match?(SIREN_PATTERN)
+          add("#{role} SIREN #{party.siren.inspect} must be 9 digits")
+        end
+
+        return unless party.vat_number && !party.vat_number.to_s.match?(VAT_NUMBER_PATTERN)
+
+        add("#{role} VAT number #{party.vat_number.inspect} is not a valid EU VAT identifier")
+      end
+
+      def check_lines
+        if invoice.lines.empty?
+          add("an invoice must carry at least one line (BR-16)")
+          return
+        end
+
+        invoice.lines.each do |line|
+          label = "line #{line.number}"
+          add("#{label}: name is required (BT-153)") if blank?(line.name)
+          add("#{label}: unit code is required (BT-130)") if blank?(line.unit_code)
+          check_vat_category(line.vat_category, line.vat_rate, label)
+        end
+      end
+
+      def check_vat_category(category, rate, label)
+        unless Codes::VatCategory::ALL.include?(category)
+          add("#{label}: VAT category #{category.inspect} is not an EN 16931 category code")
+          return
+        end
+
+        decimal_rate = rate.nil? ? nil : Formatting.decimal(rate)
+
+        if category == Codes::VatCategory::STANDARD
+          if decimal_rate.nil? || decimal_rate.zero?
+            add("#{label}: standard rated items need a VAT rate above zero (BR-S-05)")
+          end
+        elsif Codes::VatCategory::ZERO_RATE_ONLY.include?(category) &&
+              !decimal_rate.nil? && !decimal_rate.zero?
+          add("#{label}: VAT category #{category} requires a zero rate, got #{decimal_rate.to_s("F")}")
+        end
+      end
+
+      def check_tax_breakdowns
+        if invoice.tax_breakdowns.empty?
+          add("at least one VAT breakdown is required (BR-CO-18)")
+          return
+        end
+
+        invoice.tax_breakdowns.each do |breakdown|
+          label = "VAT breakdown #{breakdown.category}/#{breakdown.rate_decimal.to_s("F")}"
+          check_vat_category(breakdown.category, breakdown.rate, label)
+          check_exemption_reason(breakdown, label)
+          check_breakdown_arithmetic(breakdown, label)
+        end
+
+        check_breakdown_coverage
+      end
+
+      def check_exemption_reason(breakdown, label)
+        return unless Codes::VatCategory::REQUIRING_EXEMPTION_REASON.include?(breakdown.category)
+        return if !blank?(breakdown.exemption_reason) || !blank?(breakdown.exemption_reason_code)
+
+        add("#{label}: an exemption reason is required for category #{breakdown.category} " \
+            "(BR-E-10 / BR-AE-10 / BR-IC-10 / BR-G-10)")
+      end
+
+      def check_breakdown_arithmetic(breakdown, label)
+        expected = (breakdown.basis_amount_decimal * breakdown.rate_decimal / 100).round(2)
+        actual = breakdown.calculated_amount_decimal.round(2)
+        return if (expected - actual).abs <= ROUNDING_TOLERANCE
+
+        add("#{label}: VAT amount #{actual.to_s("F")} does not match " \
+            "#{breakdown.basis_amount_decimal.to_s("F")} x #{breakdown.rate_decimal.to_s("F")}% " \
+            "= #{expected.to_s("F")} (BR-CO-17)")
+      end
+
+      def check_breakdown_coverage
+        declared = invoice.tax_breakdowns.map(&:tax_key)
+        expected_basis = basis_by_tax_key
+
+        (expected_basis.keys - declared).each do |category, rate|
+          add("no VAT breakdown declared for category #{category} at #{rate.to_s("F")}% " \
+              "although lines use it (BR-CO-18)")
+        end
+
+        invoice.tax_breakdowns.each do |breakdown|
+          expected = expected_basis[breakdown.tax_key]
+          if expected.nil?
+            add("VAT breakdown #{breakdown.category}/#{breakdown.rate_decimal.to_s("F")} " \
+                "matches no invoice line")
+            next
+          end
+
+          actual = breakdown.basis_amount_decimal.round(2)
+          next if actual == expected.round(2)
+
+          add("VAT breakdown #{breakdown.category}/#{breakdown.rate_decimal.to_s("F")}: taxable " \
+              "base #{actual.to_s("F")} does not match the sum of its lines " \
+              "#{expected.round(2).to_s("F")} (BR-S-08)")
+        end
+      end
+
+      def basis_by_tax_key
+        totals = Hash.new { |hash, key| hash[key] = BigDecimal(0) }
+
+        invoice.lines.each { |line| totals[line.tax_key] += line.net_amount_decimal }
+
+        invoice.allowances.each do |allowance|
+          totals[tax_key_of(allowance)] -= allowance.amount_decimal
+        end
+        invoice.charges.each do |charge|
+          totals[tax_key_of(charge)] += charge.amount_decimal
+        end
+
+        totals
+      end
+
+      def tax_key_of(item)
+        [item.vat_category, Formatting.decimal(item.vat_rate || 0)]
+      end
+
+      def check_payment
+        invoice.payment_means.each do |means|
+          if blank?(means.type_code)
+            add("payment means type code is required (BT-81)")
+            next
+          end
+
+          if Codes::PaymentMeansType::REQUIRING_CREDITOR_ACCOUNT.include?(means.type_code) &&
+             !means.creditor_account?
+            add("payment means #{means.type_code} (credit transfer) requires a creditor " \
+                "account identifier (BR-61)")
+          end
+
+          if means.iban && !means.iban.to_s.delete(" ").match?(IBAN_PATTERN)
+            add("payment IBAN #{means.iban.inspect} is not a well-formed IBAN")
+          end
+        end
+      end
+
+      def check_totals
+        totals = invoice.totals
+        if totals.nil?
+          add("invoice totals are required (BG-22)")
+          return
+        end
+
+        lines_sum = invoice.lines.reduce(BigDecimal(0)) { |sum, line| sum + line.net_amount_decimal }
+        compare(totals.line_total_decimal, lines_sum,
+                "sum of invoice line net amounts (BT-106)", "the invoice lines", "BR-CO-10")
+
+        allowances_sum = sum_of(invoice.allowances)
+        charges_sum = sum_of(invoice.charges)
+        compare(totals.allowance_total_decimal, allowances_sum,
+                "allowances total (BT-107)", "the document allowances", "BR-CO-11")
+        compare(totals.charge_total_decimal, charges_sum,
+                "charges total (BT-108)", "the document charges", "BR-CO-12")
+
+        compare(totals.tax_basis_total_decimal,
+                totals.line_total_decimal - allowances_sum + charges_sum,
+                "total without VAT (BT-109)", "lines minus allowances plus charges", "BR-CO-13")
+
+        vat_sum = invoice.tax_breakdowns.reduce(BigDecimal(0)) do |sum, breakdown|
+          sum + breakdown.calculated_amount_decimal
+        end
+        compare(totals.tax_total_decimal, vat_sum,
+                "total VAT amount (BT-110)", "the VAT breakdowns", "BR-CO-14")
+
+        compare(totals.grand_total_decimal,
+                totals.tax_basis_total_decimal + totals.tax_total_decimal,
+                "total with VAT (BT-112)", "total without VAT plus VAT", "BR-CO-15")
+
+        compare(totals.due_payable_decimal,
+                totals.grand_total_decimal - totals.prepaid_decimal + totals.rounding_amount_decimal,
+                "amount due for payment (BT-115)", "total with VAT minus prepaid", "BR-CO-16")
+      end
+
+      def sum_of(items)
+        items.reduce(BigDecimal(0)) { |sum, item| sum + item.amount_decimal }
+      end
+
+      def compare(actual, expected, subject, source, rule)
+        return if actual.round(2) == expected.round(2)
+
+        add("#{subject} is #{actual.round(2).to_s("F")} but #{source} add up to " \
+            "#{expected.round(2).to_s("F")} (#{rule})")
+      end
+
+      def blank?(value)
+        value.nil? || value.to_s.strip.empty?
+      end
+    end
+  end
+end

data/lib/factur_x/validation/schema.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+require_relative "../errors"
+
+module FacturX
+  module Validation
+    # Structural validation against the official Factur-X 1.0.9 EN 16931 XSD.
+    module Schema
+      ROOT = File.expand_path("../schemas/Factur-X_EN16931.xsd", __dir__)
+
+      class << self
+        def validate(xml)
+          document = xml.is_a?(Nokogiri::XML::Document) ? xml : Nokogiri::XML(xml)
+          compiled.validate(document).map(&:message)
+        end
+
+        def valid?(xml)
+          validate(xml).empty?
+        end
+
+        def validate!(xml)
+          violations = validate(xml)
+          raise SchemaError, violations unless violations.empty?
+
+          xml
+        end
+
+        # Compiling the schema costs far more than validating against it, so the
+        # imports are resolved once and the result kept for the process lifetime.
+        def compiled
+          @compiled ||= Nokogiri::XML::Schema.from_document(
+            Nokogiri::XML(File.read(ROOT), ROOT)
+          )
+        end
+      end
+    end
+  end
+end

data/lib/factur_x/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module FacturX
+  VERSION = "0.1.0"
+end

data/lib/factur_x.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "factur_x/version"
+require_relative "factur_x/errors"
+require_relative "factur_x/codes"
+require_relative "factur_x/formatting"
+require_relative "factur_x/address"
+require_relative "factur_x/contact"
+require_relative "factur_x/party"
+require_relative "factur_x/note"
+require_relative "factur_x/line"
+require_relative "factur_x/tax_breakdown"
+require_relative "factur_x/totals"
+require_relative "factur_x/payment"
+require_relative "factur_x/allowance_charge"
+require_relative "factur_x/invoice"
+require_relative "factur_x/document"
+require_relative "factur_x/validation/schema"
+require_relative "factur_x/validation/rules"
+
+# Generates the factur-x.xml attachment of a Factur-X PDF/A-3 invoice,
+# in the EN 16931 profile.
+module FacturX
+  class << self
+    # @param invoice [Invoice]
+    # @param profile [Symbol] :fr_ctc adds the rules of the French e-invoicing
+    #   reform on top of EN 16931; use :en16931 for invoices issued outside France
+    # @param validate [Boolean] check the business rules first
+    # @param validate_schema [Boolean] check the result against the Factur-X XSD
+    # @return [String] the factur-x.xml document
+    def build(invoice, profile: :fr_ctc, validate: true, validate_schema: true)
+      Validation::Rules.new(invoice, profile: profile).validate! if validate
+
+      xml = Document.new(invoice).to_xml
+      Validation::Schema.validate!(xml) if validate_schema
+      xml
+    end
+
+    # Collects every business rule violation instead of raising on the first.
+    # @return [Array<String>]
+    def violations(invoice, profile: :fr_ctc)
+      Validation::Rules.new(invoice, profile: profile).violations
+    end
+
+    def valid?(invoice, profile: :fr_ctc)
+      violations(invoice, profile: profile).empty?
+    end
+  end
+end

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: factur-x-builder
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Hotentic
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-08-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+description: Generates the EN 16931 factur-x.xml attachment of a Factur-X invoice
+  from invoicing domain objects, with French e-invoicing identifiers (SIRET, SIREN,
+  routing address) supported out of the box.
+email:
+- contact@hotentic.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- factur-x-builder.gemspec
+- lib/factur-x-builder.rb
+- lib/factur_x.rb
+- lib/factur_x/address.rb
+- lib/factur_x/allowance_charge.rb
+- lib/factur_x/codes.rb
+- lib/factur_x/contact.rb
+- lib/factur_x/document.rb
+- lib/factur_x/errors.rb
+- lib/factur_x/formatting.rb
+- lib/factur_x/invoice.rb
+- lib/factur_x/line.rb
+- lib/factur_x/note.rb
+- lib/factur_x/party.rb
+- lib/factur_x/payment.rb
+- lib/factur_x/schemas/Factur-X_1.09_EN16931_QualifiedDataType_100.xsd
+- lib/factur_x/schemas/Factur-X_1.09_EN16931_ReusableAggregateBusinessInformationEntity_100.xsd
+- lib/factur_x/schemas/Factur-X_1.09_EN16931_UnqualifiedDataType_100.xsd
+- lib/factur_x/schemas/Factur-X_EN16931.xsd
+- lib/factur_x/tax_breakdown.rb
+- lib/factur_x/totals.rb
+- lib/factur_x/validation/rules.rb
+- lib/factur_x/validation/schema.rb
+- lib/factur_x/version.rb
+homepage: https://hotentic.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://hotentic.com
+  source_code_uri: https://github.com/hotentic/factur-x-builder
+  changelog_uri: https://github.com/hotentic/factur-x-builder/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key:
+specification_version: 4
+summary: A simple tool to build a factur-x.xml XML file using required input fields.
+test_files: []