en16931 0.1.0

data/lib/en16931/pdf/renderer.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+module EN16931
+  module PDF
+    # The reference layout: an A4 letter with every § 14 UStG item in its
+    # place, dressed by a Branding (logo, accent, typeface, texts, GiroCode).
+    # Applications with their own design draw their own Prawn document and
+    # call A3.attach; this one is the default and the test bed.
+    class Renderer
+      FONT = "DejaVuSans"
+      BRAND_FONT = "Brand"
+      # The recipient block starts 45 mm below the page top (DIN 5008 window), unless the letterhead runs deeper.
+      ADDRESS_TOP = 45 * 72 / 25.4
+      GIRO_CODE_SIZE = 68
+      LABELS = {
+        de: { invoice: "Rechnung", credit_note: "Gutschrift", corrected: "Rechnungskorrektur", self_billed: "Gutschrift (Abrechnung durch den Leistungsempfänger)",
+              partial: "Teilrechnung", prepayment: "Anzahlungsrechnung",
+              number: "Rechnungsnummer", date: "Rechnungsdatum", due: "Fällig am", delivery: "Leistungsdatum", period: "Leistungszeitraum",
+              reference: "Ihre Referenz", preceding: "Zur Rechnung", pos: "Pos.", description: "Beschreibung", qty: "Menge", unit_price: "Einzelpreis",
+              net: "Netto", sum_net: "Summe netto", vat: "Umsatzsteuer", allowance: "Nachlass", charge: "Zuschlag", prepaid: "Bereits gezahlt",
+              gross: "Gesamtbetrag", payable: "Zahlbetrag", payment: "Zahlung", iban: "IBAN", bic: "BIC", holder: "Kontoinhaber",
+              reference_line: "Verwendungszweck", vat_id: "USt-IdNr.", tax_number: "Steuernummer", contact: "Kontakt",
+              giro_code: "GiroCode", units: { "C62" => "Stk.", "HUR" => "Std.", "DAY" => "Tage", "MON" => "Monate", "LS" => "pauschal", "E48" => "Leistung" } },
+        en: { invoice: "Invoice", credit_note: "Credit note", corrected: "Corrected invoice", self_billed: "Self-billed invoice",
+              partial: "Partial invoice", prepayment: "Prepayment invoice",
+              number: "Invoice number", date: "Invoice date", due: "Due date", delivery: "Delivery date", period: "Service period",
+              reference: "Your reference", preceding: "Refers to invoice", pos: "No.", description: "Description", qty: "Quantity", unit_price: "Unit price",
+              net: "Net", sum_net: "Total net", vat: "VAT", allowance: "Discount", charge: "Charge", prepaid: "Prepaid",
+              gross: "Total", payable: "Amount due", payment: "Payment", iban: "IBAN", bic: "BIC", holder: "Account holder",
+              reference_line: "Payment reference", vat_id: "VAT id", tax_number: "Tax number", contact: "Contact",
+              giro_code: "Scan to pay", units: { "C62" => "pcs", "HUR" => "h", "DAY" => "days", "MON" => "months", "LS" => "lump sum", "E48" => "service" } }
+      }.freeze
+
+      attr_reader :invoice, :locale, :branding
+
+      def self.title(invoice, locale) = "#{LABELS.fetch(locale)[invoice.type]} #{invoice.number}"
+
+      def initialize(invoice, locale: :de, branding: Branding.new)
+        @invoice = invoice
+        @locale = LABELS.key?(locale) ? locale : :de
+        @branding = branding
+        @accent = branding.accent
+      end
+
+      def t(key) = LABELS.fetch(locale).fetch(key)
+
+      # @return [Prawn::Document]
+      def document
+        @document ||= Prawn::Document.new(page_size: "A4", margin: [56, 50, 56, 50], compress: true, info: {}).tap do |pdf|
+          pdf.font_families.update(FONT => { normal: EN16931.font_path("DejaVuSans.ttf"), bold: EN16931.font_path("DejaVuSans-Bold.ttf") })
+          pdf.font_families.update(BRAND_FONT => branding.font) if branding.font
+          pdf.font(branding.font ? BRAND_FONT : FONT, size: 9.5)
+          draw(pdf)
+        end
+      end
+
+      private
+
+      def draw(pdf)
+        letterhead(pdf)
+        addresses(pdf)
+        meta(pdf)
+        intro(pdf)
+        lines_table(pdf)
+        totals_block(pdf)
+        notes(pdf)
+        payment_block(pdf)
+        closing(pdf)
+        footer(pdf)
+      end
+
+      # The seller's name, and the logo beside it when there is one. The
+      # logo keeps its aspect ratio and the name moves to the other side.
+      def letterhead(pdf)
+        top = pdf.cursor
+        name_align = :left
+        if (size = branding.logo_size)
+          width, height = size
+          x = branding.logo_position == :left ? pdf.bounds.left : pdf.bounds.right - width
+          pdf.image(StringIO.new(branding.logo), at: [x, top], width: width, height: height)
+          name_align = :right if branding.logo_position == :left
+        end
+        pdf.text invoice.seller.name, size: 14, style: :bold, align: name_align
+        pdf.move_cursor_to [pdf.cursor, top - (size ? size[1] : 0)].min
+        pdf.move_down 16
+      end
+
+      # Return address in one small line, then the recipient: a letter that
+      # fits a window envelope.
+      def addresses(pdf)
+        seller = invoice.seller
+        pdf.move_cursor_to [pdf.cursor, pdf.bounds.top - ADDRESS_TOP + 56].min
+        sender = [seller.name, seller.street, seller.address_line_2, [seller.postal_code, seller.city].compact.join(" ")].compact.reject(&:empty?)
+        pdf.text sender.join(" · "), size: 7, color: "666666"
+        pdf.move_down 6
+        buyer = invoice.buyer
+        pdf.text buyer.name, style: :bold
+        buyer.address_lines.each { |line| pdf.text line }
+        pdf.text country_name(buyer.country) unless buyer.country == invoice.seller.country
+        pdf.move_down 28
+      end
+
+      def meta(pdf)
+        pdf.text Renderer.title(invoice, locale), size: 16, style: :bold, color: @accent
+        pdf.move_down 8
+        rows = [[t(:number), invoice.number], [t(:date), date(invoice.issue_date)]]
+        rows << [t(:due), date(invoice.due_date)] if invoice.due_date
+        rows << [t(:delivery), date(invoice.delivery_date)] if invoice.delivery_date
+        rows << [t(:period), "#{date(invoice.period.begin)} – #{date(invoice.period.end)}"] if invoice.period
+        rows << [t(:reference), invoice.buyer_reference] if invoice.buyer_reference
+        if invoice.preceding
+          rows << [t(:preceding),
+                   [invoice.preceding[:number], (date(invoice.preceding[:issue_date]) if invoice.preceding[:issue_date])].compact.join(", ")]
+        end
+        pdf.table(rows, cell_style: { borders: [], padding: [2, 0], size: 9.5 }, column_widths: [130, 250]) do
+          column(0).text_color = "666666"
+        end
+        pdf.move_down 18
+      end
+
+      def intro(pdf)
+        return unless branding.intro
+
+        pdf.text branding.intro, size: 9.5
+        pdf.move_down 12
+      end
+
+      def closing(pdf)
+        return unless branding.closing
+
+        pdf.move_down 18
+        pdf.text branding.closing, size: 9.5
+      end
+
+      def lines_table(pdf)
+        header = [t(:pos), t(:description), t(:qty), t(:unit_price), t(:net)]
+        rows = invoice.lines.each_with_index.map do |line, i|
+          [i + 1, [line.description, line.note, line.period && "#{date(line.period.begin)} – #{date(line.period.end)}"].compact.join("\n"),
+           "#{number(line.quantity, 0..2)} #{unit(line.unit)}", money(line.unit_price), money(line.net)]
+        end
+        pdf.table([header] + rows, width: pdf.bounds.width, column_widths: { 0 => 32, 2 => 80, 3 => 80, 4 => 80 },
+                                   cell_style: { borders: [:bottom], border_color: "DDDDDD", padding: [6, 4], size: 9.5 }) do
+          row(0).font_style = :bold
+          row(0).border_color = @accent
+          columns(2..4).align = :right
+          column(0).align = :right
+        end
+        pdf.move_down 10
+      end
+
+      def totals_block(pdf)
+        totals = invoice.totals
+        rows = []
+        rows << [t(:sum_net), money(totals.line_total)] unless totals.line_total == totals.net
+        invoice.allowances.each { |a| rows << ["#{t(:allowance)} #{a.reason}", "−#{money(a.amount)}"] }
+        invoice.charges.each { |c| rows << ["#{t(:charge)} #{c.reason}", money(c.amount)] }
+        rows << [t(:net), money(totals.net)]
+        totals.subtotals.each do |sub|
+          rows << ["#{t(:vat)} #{number(sub.tax.rate, 0..1)} %", money(sub.amount)] if sub.tax.taxed?
+        end
+        rows << [t(:gross), money(totals.gross)]
+        rows << [t(:prepaid), "−#{money(totals.prepaid)}"] if totals.prepaid.positive?
+        rows << [t(:payable), money(totals.payable)]
+        pdf.indent(pdf.bounds.width - 260) do
+          pdf.table(rows, column_widths: [160, 100], cell_style: { borders: [], padding: [3, 4], size: 9.5 }) do
+            column(1).align = :right
+            row(-1).font_style = :bold
+            row(-1).borders = [:top]
+            row(-1).border_color = @accent
+          end
+        end
+        pdf.move_down 14
+      end
+
+      # Exemption reasons are mandatory text on the invoice; invoice notes follow.
+      def notes(pdf)
+        texts = invoice.totals.subtotals.map { |s| s.tax.exemption_reason }.compact.uniq + invoice.notes
+        texts.each { |text| pdf.text text, size: 9 }
+        pdf.move_down 14 unless texts.empty?
+      end
+
+      def payment_block(pdf)
+        payment = invoice.payment
+        return if payment.nil?
+
+        code_bottom = giro_code(pdf)
+        pdf.text t(:payment), style: :bold
+        pdf.move_down 3
+        pdf.text payment.terms, size: 9 if payment.terms
+        rows = []
+        rows << [t(:holder), payment.holder] if payment.holder
+        rows << [t(:iban), payment.iban.scan(/.{1,4}/).join(" ")] if payment.iban
+        rows << [t(:bic), payment.bic] if payment.bic
+        rows << [t(:reference_line), payment.reference] if payment.reference
+        unless rows.empty?
+          pdf.table(rows, cell_style: { borders: [], padding: [2, 0], size: 9.5 }, column_widths: [130, 280]) do
+            column(0).text_color = "666666"
+          end
+        end
+        pdf.move_cursor_to [pdf.cursor, code_bottom].min if code_bottom
+      end
+
+      # The GiroCode floats at the right of the payment details and reports
+      # where it ends so the text below does not run into it.
+      def giro_code(pdf)
+        return nil unless branding.giro_code
+
+        payload = GiroCode.payload(invoice, remittance: Renderer.title(invoice, locale))
+        return nil unless payload
+
+        top = pdf.cursor
+        pdf.float do
+          pdf.bounding_box([pdf.bounds.right - GIRO_CODE_SIZE, top], width: GIRO_CODE_SIZE) do
+            GiroCode.draw(pdf, payload, size: GIRO_CODE_SIZE)
+            pdf.move_down 3
+            pdf.text t(:giro_code), size: 7, color: "666666", align: :center
+          end
+        end
+        top - GIRO_CODE_SIZE - 14
+      end
+
+      def footer(pdf)
+        seller = invoice.seller
+        ids = []
+        ids << "#{t(:vat_id)} #{seller.vat_id}" if seller.vat_id
+        ids << "#{t(:tax_number)} #{seller.tax_number}" if seller.tax_number
+        contact = [seller.contact_name, seller.phone, seller.email].compact.join(" · ")
+        pdf.repeat(:all) do
+          pdf.bounding_box([pdf.bounds.left, pdf.bounds.bottom + 26], width: pdf.bounds.width) do
+            pdf.stroke_color "DDDDDD"
+            pdf.stroke_horizontal_rule
+            pdf.move_down 6
+            pdf.text [seller.name, seller.legal_form, ids.join(" · "), ("#{t(:contact)}: #{contact}" unless contact.empty?)].compact.join("  ·  "), size: 7.5,
+                                                                                                                                                    color: "666666"
+          end
+        end
+      end
+
+      def money(amount)
+        "#{number(amount, 2..2)} #{currency_symbol}"
+      end
+
+      def currency_symbol
+        { "EUR" => "€", "USD" => "$", "GBP" => "£", "CHF" => "CHF" }.fetch(invoice.currency, invoice.currency)
+      end
+
+      def number(value, decimals)
+        text = format("%.#{decimals.max}f", value)
+        int, frac = text.split(".")
+        frac = frac&.sub(/0+\z/, "") if decimals.min < decimals.max
+        frac = nil if frac && frac.empty?
+        sep = locale == :de ? [".", ","] : [",", "."]
+        int = int.reverse.scan(/\d{1,3}/).join(sep[0]).reverse
+        [int, frac].compact.join(sep[1])
+      end
+
+      def date(d) = locale == :de ? d.strftime("%d.%m.%Y") : d.strftime("%Y-%m-%d")
+      def unit(code) = LABELS.fetch(locale)[:units].fetch(code, code)
+
+      def country_name(code)
+        { "DE" => "Deutschland", "AT" => "Österreich", "CH" => "Schweiz", "FR" => "Frankreich", "NL" => "Niederlande",
+          "US" => "USA", "GB" => "Vereinigtes Königreich", "IE" => "Irland", "LU" => "Luxemburg" }.fetch(code, code)
+      end
+    end
+  end
+end

data/lib/en16931/pdf/xmp.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module EN16931
+  module PDF
+    # The XMP packet a PDF/A-3b hybrid needs: PDF/A identification, the
+    # Dublin Core and PDF entries that mirror the Info dictionary, and the
+    # Factur-X/ZUGFeRD extension schema with the four document properties.
+    module XMP
+      FX_NS = "urn:factur-x:pdfa:CrossIndustryDocument:invoice:1p0#"
+
+      module_function
+
+      def build(title:, author:, created_at:, producer:, creator_tool:, filename:, conformance:, document_type: "INVOICE")
+        stamp = created_at.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
+        <<~XMP
+          <?xpacket begin="" id="W5M0MpCehiHzreSzNTczkc9d"?>
+          <x:xmpmeta xmlns:x="adobe:ns:meta/">
+            <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
+              <rdf:Description rdf:about="" xmlns:pdfaid="http://www.aiim.org/pdfa/ns/id/">
+                <pdfaid:part>3</pdfaid:part>
+                <pdfaid:conformance>B</pdfaid:conformance>
+              </rdf:Description>
+              <rdf:Description rdf:about="" xmlns:dc="http://purl.org/dc/elements/1.1/">
+                <dc:title><rdf:Alt><rdf:li xml:lang="x-default">#{escape(title)}</rdf:li></rdf:Alt></dc:title>
+                <dc:creator><rdf:Seq><rdf:li>#{escape(author)}</rdf:li></rdf:Seq></dc:creator>
+              </rdf:Description>
+              <rdf:Description rdf:about="" xmlns:xmp="http://ns.adobe.com/xap/1.0/">
+                <xmp:CreatorTool>#{escape(creator_tool)}</xmp:CreatorTool>
+                <xmp:CreateDate>#{stamp}</xmp:CreateDate>
+                <xmp:ModifyDate>#{stamp}</xmp:ModifyDate>
+              </rdf:Description>
+              <rdf:Description rdf:about="" xmlns:pdf="http://ns.adobe.com/pdf/1.3/">
+                <pdf:Producer>#{escape(producer)}</pdf:Producer>
+              </rdf:Description>
+              <rdf:Description rdf:about=""
+                  xmlns:pdfaExtension="http://www.aiim.org/pdfa/ns/extension/"
+                  xmlns:pdfaSchema="http://www.aiim.org/pdfa/ns/schema#"
+                  xmlns:pdfaProperty="http://www.aiim.org/pdfa/ns/property#">
+                <pdfaExtension:schemas>
+                  <rdf:Bag>
+                    <rdf:li rdf:parseType="Resource">
+                      <pdfaSchema:schema>Factur-X PDFA Extension Schema</pdfaSchema:schema>
+                      <pdfaSchema:namespaceURI>#{FX_NS}</pdfaSchema:namespaceURI>
+                      <pdfaSchema:prefix>fx</pdfaSchema:prefix>
+                      <pdfaSchema:property>
+                        <rdf:Seq>
+                          #{property("DocumentFileName", "name of the embedded XML invoice file")}
+                          #{property("DocumentType", "INVOICE")}
+                          #{property("Version", "The actual version of the Factur-X XML schema")}
+                          #{property("ConformanceLevel", "The conformance level of the embedded Factur-X data")}
+                        </rdf:Seq>
+                      </pdfaSchema:property>
+                    </rdf:li>
+                  </rdf:Bag>
+                </pdfaExtension:schemas>
+              </rdf:Description>
+              <rdf:Description rdf:about="" xmlns:fx="#{FX_NS}">
+                <fx:DocumentType>#{document_type}</fx:DocumentType>
+                <fx:DocumentFileName>#{filename}</fx:DocumentFileName>
+                <fx:Version>1.0</fx:Version>
+                <fx:ConformanceLevel>#{conformance}</fx:ConformanceLevel>
+              </rdf:Description>
+            </rdf:RDF>
+          </x:xmpmeta>
+          <?xpacket end="w"?>
+        XMP
+      end
+
+      def property(name, description)
+        <<~PROP.strip
+          <rdf:li rdf:parseType="Resource">
+            <pdfaProperty:name>#{name}</pdfaProperty:name>
+            <pdfaProperty:valueType>Text</pdfaProperty:valueType>
+            <pdfaProperty:category>external</pdfaProperty:category>
+            <pdfaProperty:description>#{description}</pdfaProperty:description>
+          </rdf:li>
+        PROP
+      end
+
+      def escape(text)
+        text.to_s.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;")
+      end
+    end
+  end
+end

data/lib/en16931/pdf.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "prawn"
+require "stringio"
+require "prawn/table"
+require_relative "pdf/xmp"
+require_relative "pdf/giro_code"
+require_relative "pdf/a3"
+require_relative "pdf/renderer"
+
+module EN16931
+  # The hybrid: a PDF/A-3b with the invoice XML embedded (ZUGFeRD 2.x /
+  # Factur-X). `render` draws the reference layout; `A3.attach` turns any
+  # Prawn document into the hybrid.
+  module PDF
+    module_function
+
+    # @param branding [Branding] logo, colour, typeface, texts, GiroCode; the plain layout by default
+    # @return [String] PDF bytes
+    def render(invoice, profile: :xrechnung, locale: :de, created_at: Time.now, branding: Branding.new)
+      xml = XML.cii(invoice, profile:)
+      doc = Renderer.new(invoice, locale:, branding:).document
+      A3.attach(doc, xml, profile:, title: Renderer.title(invoice, locale), author: invoice.seller.name, created_at:)
+      doc.render
+    end
+  end
+end

data/lib/en16931/tax.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module EN16931
+  # A VAT treatment (BG-23 / BT-151): the category code, the rate, and for
+  # exempt categories the reason text (BT-120) and code (BT-121).
+  #
+  # Categories per UNTDID 5305 as used by EN 16931:
+  #   S  standard rate          Z  zero rated            E  exempt
+  #   AE reverse charge         K  intra-community       G  export outside the EU
+  #   O  not subject to VAT     L/M Canary Islands / Ceuta-Melilla (unused here)
+  Tax = Data.define(:category, :rate, :exemption_reason, :exemption_code) do
+    def initialize(category:, rate: 0, exemption_reason: nil, exemption_code: nil)
+      super(category: category.to_s, rate: BigDecimal(rate.to_s), exemption_reason:, exemption_code:)
+    end
+
+    def taxed? = category == "S"
+    def exempt? = !taxed? && category != "Z"
+
+    # Category O forbids a seller VAT identifier on the invoice (BR-O-2);
+    # the seller is identified by the tax number instead.
+    def forbids_vat_identifiers? = category == "O"
+
+    # Lines, allowances and charges in category O carry no rate (BR-O-05 to
+    # BR-O-07); every other exempt category carries an explicit 0.
+    def rate_for_xml = category == "O" ? nil : rate
+
+    def self.standard(rate) = new(category: "S", rate: rate)
+    def self.zero_rated = new(category: "Z")
+    def self.exempt(reason:, code: nil) = new(category: "E", exemption_reason: reason, exemption_code: code)
+    def self.reverse_charge(reason:, code: "VATEX-EU-AE") = new(category: "AE", exemption_reason: reason, exemption_code: code)
+    def self.intra_community(reason:, code: "VATEX-EU-IC") = new(category: "K", exemption_reason: reason, exemption_code: code)
+    def self.export(reason:, code: "VATEX-EU-G") = new(category: "G", exemption_reason: reason, exemption_code: code)
+    def self.not_subject(reason:, code: "VATEX-EU-O") = new(category: "O", exemption_reason: reason, exemption_code: code)
+  end
+end

data/lib/en16931/totals.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module EN16931
+  # Document totals (BG-22) and the VAT breakdown (BG-23), computed the way
+  # EN 16931 checks them: line nets summed, VAT rounded per category.
+  class Totals
+    Subtotal = Data.define(:tax, :taxable, :amount)
+
+    attr_reader :line_total, :allowance_total, :charge_total, :net, :vat, :gross, :prepaid, :payable, :subtotals
+
+    def self.compute(invoice) = new(invoice)
+
+    def initialize(invoice)
+      @line_total = invoice.lines.sum(&:net)
+      @allowance_total = invoice.allowances.sum(&:amount)
+      @charge_total = invoice.charges.sum(&:amount)
+      @net = @line_total - @allowance_total + @charge_total
+      @subtotals = breakdown(invoice)
+      @vat = @subtotals.sum(&:amount)
+      @gross = @net + @vat
+      @prepaid = invoice.prepaid
+      @payable = @gross - @prepaid
+    end
+
+    private
+
+    # One subtotal per distinct tax treatment; amount = taxable × rate, rounded.
+    def breakdown(invoice)
+      bases = Hash.new(BigDecimal("0"))
+      invoice.lines.each { |line| bases[invoice.tax_for(line)] += line.net }
+      invoice.allowances.each { |a| bases[a.tax || invoice.tax] -= a.amount }
+      invoice.charges.each { |c| bases[c.tax || invoice.tax] += c.amount }
+      bases.map do |tax, taxable|
+        Subtotal.new(tax: tax, taxable: taxable, amount: (taxable * tax.rate / 100).round(2))
+      end
+    end
+  end
+end

data/lib/en16931/validation/kosit.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "open3"
+require "tmpdir"
+require "fileutils"
+require "nokogiri"
+require "net/http"
+require "uri"
+
+module EN16931
+  module Validation
+    # The KoSIT validator with the XRechnung configuration: XML Schema and
+    # the EN 16931 + XRechnung Schematron rules for UBL and CII. Needs Java 11+.
+    #
+    #   kosit = EN16931::Validation::KoSIT.new            # tmp/kosit by default
+    #   kosit.install!                                    # downloads jar and configuration once
+    #   report = kosit.validate(xml)                      # => Report
+    class KoSIT
+      VALIDATOR_VERSION = "1.6.3"
+      CONFIGURATION = "2026-08-31"
+      XRECHNUNG = "3.0.2"
+      VALIDATOR_URL = "https://repo1.maven.org/maven2/org/kosit/validator/#{VALIDATOR_VERSION}/validator-#{VALIDATOR_VERSION}-standalone.jar".freeze
+      CONFIGURATION_URL = "https://github.com/itplr-kosit/validator-configuration-xrechnung/releases/download/v#{CONFIGURATION}/xrechnung-#{XRECHNUNG}-validator-configuration-#{CONFIGURATION}.zip".freeze
+      REPORT_NS = { "rep" => "http://www.xoev.de/de/validator/varl/1", "s" => "http://www.xoev.de/de/validator/framework/1/scenarios" }.freeze
+
+      attr_reader :dir
+
+      def initialize(dir: ENV.fetch("EN16931_KOSIT_DIR", "tmp/kosit"), java: ENV.fetch("JAVA", "java"))
+        @dir = File.expand_path(dir)
+        @java = java
+      end
+
+      def jar = File.join(dir, "validator-#{VALIDATOR_VERSION}-standalone.jar")
+      def scenarios = File.join(dir, "config", "scenarios.xml")
+      def installed? = File.exist?(jar) && File.exist?(scenarios)
+
+      def self.available?(java: "java")
+        _, status = Open3.capture2e(java, "-version")
+        status.success?
+      rescue Errno::ENOENT
+        false
+      end
+
+      def install!
+        FileUtils.mkdir_p(dir)
+        download(VALIDATOR_URL, jar) unless File.exist?(jar)
+        unless File.exist?(scenarios)
+          zip = File.join(dir, "configuration.zip")
+          download(CONFIGURATION_URL, zip)
+          FileUtils.mkdir_p(File.join(dir, "config"))
+          system("unzip", "-q", "-o", zip, "-d", File.join(dir, "config"), exception: true)
+        end
+        self
+      end
+
+      # @param xml [String]
+      # @return [Report]
+      def validate(xml)
+        install! unless installed?
+        Dir.mktmpdir("en16931") do |tmp|
+          input = File.join(tmp, "invoice.xml")
+          File.write(input, xml)
+          out, status = Open3.capture2e(@java, "-jar", jar, "-s", scenarios, "-r", File.join(dir, "config"), "-o", tmp, input)
+          report_path = File.join(tmp, "invoice-report.xml")
+          raise Error, "KoSIT validator produced no report (exit #{status.exitstatus}):\n#{out}" unless File.exist?(report_path)
+
+          parse(File.read(report_path), out)
+        end
+      end
+
+      private
+
+      def parse(report_xml, console)
+        doc = Nokogiri::XML(report_xml)
+        accepted = doc.at_xpath("//rep:assessment/rep:accept", REPORT_NS)
+        messages = doc.xpath("//rep:message", REPORT_NS).map do |m|
+          level = m["level"] == "error" ? :error : :warning
+          Message.new(level: level, code: m["code"] || m["id"], text: m.text.strip)
+        end
+        Report.new(tool: "KoSIT #{VALIDATOR_VERSION} / XRechnung #{XRECHNUNG} (#{CONFIGURATION})", valid: !accepted.nil?, messages: messages,
+                   raw: "#{console}\n#{report_xml}")
+      end
+
+      def download(url, target)
+        uri = URI(url)
+        10.times do
+          response = Net::HTTP.get_response(uri)
+          case response
+          when Net::HTTPRedirection then uri = URI(response["location"])
+          when Net::HTTPSuccess
+            File.binwrite(target, response.body)
+            return
+          else raise Error, "download of #{url} failed: #{response.code}"
+          end
+        end
+        raise Error, "too many redirects for #{url}"
+      end
+    end
+  end
+end

data/lib/en16931/validation/report.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module EN16931
+  module Validation
+    Message = Data.define(:level, :code, :text)
+
+    # The outcome of one validator run.
+    Report = Data.define(:tool, :valid, :messages, :raw) do
+      def valid? = valid
+      def errors = messages.select { |m| m.level == :error }
+      def warnings = messages.select { |m| m.level == :warning }
+
+      def to_s
+        lines = ["#{tool}: #{valid? ? "valid" : "INVALID"}"]
+        messages.each { |m| lines << "  [#{m.level}] #{m.code}: #{m.text}" }
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/en16931/validation/vera_pdf.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "open3"
+require "tmpdir"
+require "nokogiri"
+
+module EN16931
+  module Validation
+    # veraPDF, the reference PDF/A validator: the `verapdf` command when it is
+    # installed, else the official Docker image.
+    class VeraPDF
+      IMAGE = "ghcr.io/verapdf/cli:latest"
+
+      def initialize(command: ENV.fetch("VERAPDF", nil), docker: ENV.fetch("DOCKER", "docker"))
+        @command = command || (system("which", "verapdf", out: File::NULL) ? "verapdf" : nil)
+        @docker = docker
+      end
+
+      def self.available?
+        new.available?
+      end
+
+      def available?
+        return true if @command
+
+        _, status = Open3.capture2e(@docker, "image", "inspect", IMAGE)
+        status.success? || Open3.capture2e(@docker, "pull", IMAGE).last.success?
+      rescue Errno::ENOENT
+        false
+      end
+
+      # @param pdf [String] PDF bytes
+      # @return [Report]
+      def validate(pdf, flavour: "3b")
+        Dir.mktmpdir("en16931") do |tmp|
+          path = File.join(tmp, "invoice.pdf")
+          File.binwrite(path, pdf)
+          # The container runs as another user: mktmpdir's 0700 would hide the file.
+          File.chmod(0o755, tmp)
+          File.chmod(0o644, path)
+          out, = if @command
+                   Open3.capture2e(@command, "-f", flavour, "--format", "xml", path)
+                 else
+                   Open3.capture2e(@docker, "run", "--rm", "-v", "#{tmp}:/data", IMAGE, "-f", flavour, "--format", "xml", "/data/invoice.pdf")
+                 end
+          parse(out)
+        end
+      end
+
+      private
+
+      def parse(out)
+        xml = out[/<\?xml.*\z/m] || out
+        doc = Nokogiri::XML(xml)
+        doc.remove_namespaces!
+        result = doc.at_xpath("//validationReport") || doc.at_xpath("//validationResult")
+        compliant = result && result["isCompliant"] == "true"
+        messages = doc.xpath("//rule[@status='failed']").map do |rule|
+          Message.new(level: :error, code: "#{rule["specification"]} #{rule["clause"]} test #{rule["testNumber"]}",
+                      text: rule.at_xpath("./description")&.text.to_s.strip)
+        end
+        Report.new(tool: "veraPDF", valid: compliant, messages: messages, raw: out)
+      end
+    end
+  end
+end

data/lib/en16931/validation.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "validation/report"
+require_relative "validation/kosit"
+require_relative "validation/vera_pdf"
+
+module EN16931
+  # Wrappers around the official validators, meant for CI and for proving a
+  # layout once: KoSIT (the German XRechnung validator, Java) for the XML and
+  # veraPDF for the PDF/A-3b container. Neither is needed at run time.
+  module Validation
+  end
+end

data/lib/en16931/version.rb

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