einvoicing 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01ba6a9d7f94ac75ba98a3c64141ae25293b27323e8f8c8b55c147bd8ae5ff4c
-  data.tar.gz: 9e929b17b7f00a01b23186b9e8ebded133bb5e3a7fc60da9f6cbbb271cab2074
+  metadata.gz: e57cfd36d8de0852320a7b72d1fe1ced81ff64eb024199b31733be06859ee509
+  data.tar.gz: 03a602eb77133a12a8493939b8292749f91fd9c2c834c4777108b8f4d0793d9d
 SHA512:
-  metadata.gz: 4c70ee9bfa6505caa0d17993a166bdf9220bd435649893ca349cb0e3efc2d8948db40fb691293f833a3ad0eb0318a9924eadd53415872c47b552a99e30d2153d
-  data.tar.gz: 4adc977fe39f03b2aa1395ca0ade81ff3d942425f1e580994b48b212c5dba458e305d1fb78776f5d36138c73d30239aa3e8e82b268db1f2fac4193633838f15f
+  metadata.gz: fca0526e61db40a9125f9a5060c75db8f5bcefa69b158b55ce58d2c824ccbc2868594aa77946308919b8aea7922f364f3d0d9890fe63b77f21ecac673619ecd1
+  data.tar.gz: c57a78e842ca6beac1f0b98dfa52659e436eb2b03929c7938bdf9e615b009d28a24018c55ed28023853591054657e124099330c4c99d8f078b4b4885fe6cbc1c

data/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-03-13
+
+### Added
+- `Einvoicing.xml(invoice, format: :cii | :ubl)` — top-level XML generation
+- `Einvoicing.embed(pdf, invoice_or_xml)` — top-level Factur-X embedding
+- `Einvoicing.validate(invoice, market: :fr)` — top-level validation
+- `Einvoicing.process(invoice, format:, market:, pdf:)` — full pipeline, never raises
+- `Einvoicing::FR::SiretLookup.find(siren)` — SIRET lookup via French government API (no auth, stdlib only)
+- `Einvoicing::FR::SiretLookup.enrich!(party)` — auto-fills SIRET on a Party from its SIREN
+- `Einvoicing::Validators::Peppol.validate_ubl(xml)` — Peppol BIS 3.0 Schematron validation (requires Java + Saxon-HE 12)
+- `Einvoicing::Errors::JavaNotFound`, `Einvoicing::Errors::ValidationError`
+- `lib/einvoicing/fr.rb` — FR submodule entrypoint
+
 ## [0.3.0] - 2026-03-13
 
 ### Added

data/lib/einvoicing/errors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Einvoicing
+  module Errors
+    # Raised when Java is not found in PATH and is required for validation.
+    JavaNotFound = Class.new(StandardError)
+
+    # Raised when an external validator (e.g. Saxon) fails unexpectedly.
+    ValidationError = Class.new(StandardError)
+  end
+end

data/lib/einvoicing/fr/siret_lookup.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module Einvoicing
+  module FR
+    module SiretLookup
+      API_URL = "https://recherche-entreprises.api.gouv.fr/search"
+
+      # Find SIRET for a given SIREN using the French government Sirene API.
+      # Returns { siret:, name:, address: } or nil on any error.
+      def self.find(siren)
+        return nil unless siren.to_s.match?(/\A\d{9}\z/)
+
+        uri = URI(API_URL)
+        uri.query = URI.encode_www_form(q: siren.to_s, mtq: "true")
+
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: true,
+                                   open_timeout: 5, read_timeout: 10) do |http|
+          http.get(uri.request_uri)
+        end
+
+        return nil unless response.code == "200"
+
+        data = JSON.parse(response.body)
+        result = data["results"]&.first
+        return nil unless result
+
+        siege = result["siege"] || {}
+        siret = siege["siret"]
+        return nil if siret.nil? || siret.empty?
+
+        { siret: siret, name: result["nom_complet"], address: siege["adresse"] }
+      rescue StandardError
+        nil
+      end
+
+      # Enrich a Party object by fetching and setting its SIRET from the API.
+      # Only calls the API if party.siren is present and party.siret is blank.
+      # Returns the party.
+      def self.enrich!(party)
+        return party if party.siren.to_s.strip.empty?
+        return party if party.respond_to?(:siret) && !party.siret.to_s.strip.empty?
+
+        result = find(party.siren.to_s.gsub(/\s/, ""))
+        return party unless result&.dig(:siret)
+
+        party.with(siret: result[:siret])
+      end
+    end
+  end
+end

data/lib/einvoicing/fr.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative "fr/siret_lookup"
+
+module Einvoicing
+  module FR
+    # France-specific features for the einvoicing gem.
+    # Market: France (FR) — Factur-X, PPF/PDP mandate (Sept 2026)
+    #
+    # Usage:
+    #   Einvoicing::FR::SiretLookup.find("898208145")
+    #   Einvoicing::FR::SiretLookup.enrich!(party)
+  end
+end

data/lib/einvoicing/party.rb

@@ -25,5 +25,18 @@ module Einvoicing
     def siren_number
       siren || (siret && siret[0, 9])
     end
+
+    # Look up SIRET via the Sirene API and return a new Party with siret filled in.
+    # No-op (returns self) if siren is blank or siret is already set.
+    #
+    # @return [Party] self or new Party with siret populated
+    def fetch_siret!
+      return self unless siren_number && siret.nil?
+
+      result = SiretLookup.find(siren_number)
+      return self unless result
+
+      with(siret: result[:siret])
+    end
   end
 end

data/lib/einvoicing/siret_lookup.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module Einvoicing
+  # Looks up SIRET and company name from a SIREN number using the free French
+  # government API (no authentication required).
+  module SiretLookup
+    API_URL = "https://recherche-entreprises.api.gouv.fr/search"
+    SIREN_RE = /\A\d{9}\z/
+
+    # Find company info for a given SIREN number.
+    #
+    # @param siren [String, nil] 9-digit SIREN number
+    # @return [Hash, nil] { siret:, name:, address: } or nil on any error
+    def self.find(siren)
+      return nil unless siren.to_s.match?(SIREN_RE)
+
+      uri = URI(API_URL)
+      uri.query = URI.encode_www_form(q: siren, mtq: "true")
+
+      response = fetch(uri)
+      return nil if response.nil?
+
+      parse(response)
+    rescue StandardError
+      nil
+    end
+
+    def self.fetch(uri)
+      Net::HTTP.start(uri.host, uri.port,
+                      use_ssl: uri.scheme == "https",
+                      open_timeout: 5,
+                      read_timeout: 10) do |http|
+        res = http.get("#{uri.path}?#{uri.query}")
+        return nil unless res.is_a?(Net::HTTPSuccess)
+
+        res.body
+      end
+    rescue StandardError
+      nil
+    end
+    private_class_method :fetch
+
+    def self.parse(body)
+      data = JSON.parse(body)
+      result = Array(data["results"]).first
+      return nil unless result
+
+      siege = result["siege"] || {}
+      siret = siege["siret"]
+      return nil if siret.nil? || siret.empty?
+
+      { siret: siret, name: result["nom_complet"], address: siege["adresse"] }
+    rescue JSON::ParserError
+      nil
+    end
+    private_class_method :parse
+  end
+end

data/lib/einvoicing/validators/peppol.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "open3"
+require "tempfile"
+require "net/http"
+require "uri"
+
+module Einvoicing
+  module Validators
+    # Validates UBL 2.1 invoices against Peppol BIS Billing 3.0 Schematron rules
+    # using Saxon-HE via the system Java runtime.
+    #
+    # Requirements:
+    #   - Java in PATH
+    #   - Saxon-HE 12 CLI jar (auto-downloaded to /tmp/saxon-he.jar on first use)
+    #   - Peppol XSLT (bundled at lib/einvoicing/data/; auto-downloaded on first use)
+    #
+    # @example
+    #   errors = Einvoicing::Validators::Peppol.validate_ubl(xml_string)
+    #   errors #=> [] when valid, or [{ field:, error:, message: }] when invalid
+    module Peppol
+      XSLT_URL  = "https://github.com/OpenPEPPOL/peppol-bis-invoice-3/releases/download/3.0.21/PEPPOL-EN16931-UBL.xslt"
+      SAXON_URL = "https://repo1.maven.org/maven2/net/sf/saxon/Saxon-HE/12.5/Saxon-HE-12.5.jar"
+      SAXON_JAR = "/tmp/saxon-he.jar"
+      XSLT_PATH = File.expand_path("../data/PEPPOL-EN16931-UBL.xslt", __dir__)
+
+      # Validate a UBL 2.1 XML string against Peppol BIS 3.0 rules.
+      #
+      # @param xml_string [String] UBL 2.1 invoice XML
+      # @return [Array<Hash>] errors — empty array means valid
+      # @raise [Einvoicing::Errors::JavaNotFound] if java is not in PATH
+      # @raise [Einvoicing::Errors::ValidationError] if Saxon fails unexpectedly
+      def self.validate_ubl(xml_string)
+        ensure_java!
+        ensure_saxon!
+        ensure_xslt!
+
+        svrl = run_saxon(xml_string)
+        parse_svrl(svrl)
+      end
+
+      def self.java_available?
+        _, _, status = Open3.capture3("java -version")
+        status.success?
+      end
+
+      def self.ensure_java!
+        raise Einvoicing::Errors::JavaNotFound, "java not found in PATH" unless java_available?
+      end
+      private_class_method :ensure_java!
+
+      def self.ensure_saxon!
+        return if File.exist?(SAXON_JAR)
+
+        download(SAXON_URL, SAXON_JAR)
+        return if File.exist?(SAXON_JAR)
+
+        raise Einvoicing::Errors::ValidationError,
+              "Saxon JAR not available. Download from #{SAXON_URL} and place at #{SAXON_JAR}"
+      end
+      private_class_method :ensure_saxon!
+
+      def self.ensure_xslt!
+        return if File.exist?(XSLT_PATH) && File.size(XSLT_PATH) > 100
+
+        download(XSLT_URL, XSLT_PATH)
+        return if File.exist?(XSLT_PATH) && File.size(XSLT_PATH) > 100
+
+        raise Einvoicing::Errors::ValidationError,
+              "Peppol XSLT not available at #{XSLT_PATH}. Download from #{XSLT_URL}"
+      end
+      private_class_method :ensure_xslt!
+
+      def self.download(url, dest)
+        uri = URI(url)
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                        open_timeout: 30, read_timeout: 120) do |http|
+          res = http.get(uri.request_uri)
+          return unless res.is_a?(Net::HTTPSuccess)
+
+          File.binwrite(dest, res.body)
+        end
+      rescue StandardError
+        nil # caller checks if file exists
+      end
+      private_class_method :download
+
+      def self.run_saxon(xml_string)
+        input  = Tempfile.new(["peppol-input",  ".xml"])
+        output = Tempfile.new(["peppol-output", ".svrl"])
+
+        begin
+          input.write(xml_string)
+          input.close
+          output.close
+
+          cmd = ["java", "-jar", SAXON_JAR,
+                 "-s:#{input.path}",
+                 "-xsl:#{XSLT_PATH}",
+                 "-o:#{output.path}"]
+
+          _, stderr, status = Open3.capture3(*cmd)
+
+          unless status.success?
+            raise Einvoicing::Errors::ValidationError,
+                  "Saxon failed (exit #{status.exitstatus}): #{stderr.strip}"
+          end
+
+          File.read(output.path)
+        ensure
+          input.unlink
+          output.unlink
+        end
+      end
+      private_class_method :run_saxon
+
+      def self.parse_svrl(svrl_xml)
+        require "rexml/document"
+
+        doc    = REXML::Document.new(svrl_xml)
+        errors = []
+
+        REXML::XPath.each(doc, "//svrl:failed-assert",
+                          "svrl" => "http://purl.oclc.org/dsdl/svrl") do |node|
+          errors << {
+            field:   node.attributes["id"] || node.attributes["location"] || "",
+            error:   node.attributes["test"] || "",
+            message: node.text.to_s.strip
+          }
+        end
+
+        errors
+      end
+      private_class_method :parse_svrl
+    end
+  end
+end

data/lib/einvoicing/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Einvoicing
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/einvoicing.rb

@@ -5,8 +5,11 @@ require "bigdecimal"
 require "bigdecimal/util"
 
 require_relative "einvoicing/version"
+require_relative "einvoicing/errors"
 require_relative "einvoicing/tax"
 require_relative "einvoicing/party"
+require_relative "einvoicing/siret_lookup"
+require_relative "einvoicing/fr"
 require_relative "einvoicing/line_item"
 require_relative "einvoicing/invoice"
 require_relative "einvoicing/xml_builder"
@@ -16,6 +19,7 @@ require_relative "einvoicing/formats/facturx"
 require_relative "einvoicing/i18n"
 require_relative "einvoicing/validators/base"
 require_relative "einvoicing/validators/fr"
+require_relative "einvoicing/validators/peppol"
 require_relative "einvoicing/invoiceable"
 require_relative "einvoicing/rails/concern"
 require_relative "einvoicing/ppf"
@@ -47,4 +51,53 @@ end
 #   xml = Einvoicing::Formats::CII.generate(invoice)
 #   ubl = Einvoicing::Formats::UBL.generate(invoice)
 module Einvoicing
+  # ─── Top-level convenience API ────────────────────────────────────────────
+
+  # Generate XML from an invoice.
+  # @param invoice [Einvoicing::Invoice]
+  # @param format [Symbol] :cii (default, Factur-X) or :ubl (Peppol BIS 3.0)
+  # @return [String] XML document
+  def self.xml(invoice, format: :cii)
+    case format
+    when :cii then Formats::CII.generate(invoice)
+    when :ubl then Formats::UBL.generate(invoice)
+    else raise ArgumentError, "Unknown format: #{format.inspect}. Use :cii or :ubl"
+    end
+  end
+
+  # Embed a Factur-X CII XML into a PDF, returning a PDF/A-3 binary.
+  # @param pdf_data [String] raw PDF binary
+  # @param invoice_or_xml [Invoice, String] Invoice (CII generated internally) or raw XML string
+  # @return [String] Factur-X PDF/A-3 binary
+  def self.embed(pdf_data, invoice_or_xml)
+    xml_str = invoice_or_xml.is_a?(String) ? invoice_or_xml : xml(invoice_or_xml, format: :cii)
+    Formats::FacturX.embed(pdf_data, xml_str)
+  end
+
+  # Validate an invoice against a market's rules.
+  # @param invoice [Einvoicing::Invoice]
+  # @param market [Symbol] :fr (default)
+  # @return [Array<Hash>] array of { field:, error:, message: } — empty means valid
+  def self.validate(invoice, market: :fr)
+    case market
+    when :fr then Validators::FR.validate(invoice)
+    else raise ArgumentError, "Unknown market: #{market.inspect}. Use :fr"
+    end
+  end
+
+  # Full pipeline: validate → generate XML → optionally embed in PDF.
+  # Never raises — errors are returned in the result hash.
+  # @param invoice [Einvoicing::Invoice]
+  # @param format [Symbol] :cii or :ubl
+  # @param market [Symbol] :fr
+  # @param pdf [String, nil] optional raw PDF binary to embed into
+  # @return [Hash] { valid:, errors:, xml:, pdf: }
+  def self.process(invoice, format: :cii, market: :fr, pdf: nil)
+    errors  = validate(invoice, market: market)
+    xml_str = xml(invoice, format: format)
+    pdf_out = pdf ? embed(pdf, xml_str) : nil
+    { valid: errors.empty?, errors: errors, xml: xml_str, pdf: pdf_out }
+  rescue StandardError => e
+    { valid: false, errors: [{ field: :unknown, error: :exception, message: e.message }], xml: nil, pdf: nil }
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: einvoicing
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Nathan Le Ray
@@ -124,9 +124,12 @@ files:
 - config/locales/einvoicing.fr.yml
 - lib/einvoicing.rb
 - lib/einvoicing/data/srgb.icc
+- lib/einvoicing/errors.rb
 - lib/einvoicing/formats/cii.rb
 - lib/einvoicing/formats/facturx.rb
 - lib/einvoicing/formats/ubl.rb
+- lib/einvoicing/fr.rb
+- lib/einvoicing/fr/siret_lookup.rb
 - lib/einvoicing/i18n.rb
 - lib/einvoicing/invoice.rb
 - lib/einvoicing/invoiceable.rb
@@ -139,9 +142,11 @@ files:
 - lib/einvoicing/ppf/submitter.rb
 - lib/einvoicing/rails/concern.rb
 - lib/einvoicing/rails/engine.rb
+- lib/einvoicing/siret_lookup.rb
 - lib/einvoicing/tax.rb
 - lib/einvoicing/validators/base.rb
 - lib/einvoicing/validators/fr.rb
+- lib/einvoicing/validators/peppol.rb
 - lib/einvoicing/version.rb
 - lib/einvoicing/xml_builder.rb
 homepage: https://github.com/sxnlabs/einvoicing