einvoicing 0.2.0 → 0.3.0

data/lib/einvoicing/formats/facturx.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+module Einvoicing
+  module Formats
+    # Embeds a CII XML document into an existing PDF to produce a Factur-X
+    # PDF/A-3 file. Requires the `hexapdf` gem.
+    #
+    # The embedded file is named "factur-x.xml" and tagged as the primary
+    # associated file (AFRelationship: Data).  XMP metadata is updated to
+    # declare PDF/A-3b conformance and the Factur-X extension schema.
+    #
+    # @example
+    #   pdf_bytes = File.binread("invoice.pdf")
+    #   xml       = Einvoicing::Formats::CII.generate(invoice)
+    #   result    = Einvoicing::Formats::FacturX.embed(pdf_bytes, xml)
+    #   File.binwrite("invoice_facturx.pdf", result)
+    module FacturX
+      FILENAME         = "factur-x.xml"
+      CONFORMANCE      = "EN 16931"
+      PROFILE_URN      = "urn:factur-x.eu:1p0:en16931"
+      FX_NAMESPACE     = "urn:factur-x:pdfa:CrossIndustryDocument:invoice:1p0#"
+      FX_PREFIX        = "fx"
+      MIME_TYPE        = "text/xml"
+      DATA_DIR         = File.expand_path("../data", __dir__)
+
+      # Embed CII XML into a PDF binary and return the Factur-X PDF binary.
+      #
+      # @param pdf_data [String] binary PDF content
+      # @param xml_string [String] CII XML string (UTF-8)
+      # @param profile [String] Factur-X profile label (default: "EN 16931")
+      # @return [String] binary Factur-X PDF/A-3 content
+      def self.embed(pdf_data, xml_string, profile: CONFORMANCE)
+        unless pdf_data.to_s.b.start_with?("%PDF-")
+          raise ArgumentError, "pdf_data does not appear to be a valid PDF (missing %PDF- magic bytes)"
+        end
+
+        require "hexapdf"
+
+        io  = StringIO.new(pdf_data.dup.force_encoding("BINARY"))
+        doc = HexaPDF::Document.new(io: io)
+
+        xml_bytes = xml_string.encode("UTF-8").b
+
+        # 1. Embed the XML as an embedded file stream.
+        ef_stream = doc.add({
+          Type:    :EmbeddedFile,
+          Subtype: "text/xml",
+          Params:  { Size: xml_bytes.bytesize, CheckSum: md5(xml_bytes) }
+        })
+        ef_stream.set_filter(:FlateDecode)
+        ef_stream.stream = xml_bytes
+
+        filespec = doc.add({
+          Type: :Filespec,
+          F:    FILENAME,
+          UF:   FILENAME,
+          AFRelationship: :Data,
+          Desc: "Factur-X invoice",
+          EF:   { F: ef_stream, UF: ef_stream }
+        })
+
+        # 2. Register in the EmbeddedFiles name tree.
+        doc.catalog[:Names] ||= doc.add({})
+        names_dict = doc.catalog[:Names]
+        names_dict[:EmbeddedFiles] ||= doc.add({ Names: [] })
+        names_dict[:EmbeddedFiles][:Names] << FILENAME << filespec
+
+        # 3. Set AF array on the catalog.
+        doc.catalog[:AF] = [filespec]
+
+        # 4. Add OutputIntent (required for PDF/A-3 conformance).
+        add_output_intent(doc)
+
+        # 5. Update XMP metadata.
+        update_xmp(doc, profile)
+
+        # 6. Write back to binary string.
+        out = StringIO.new("".b)
+        doc.write(out)
+        result = out.string
+
+        # PDF/A-3 requires %PDF-1.x header (PDF 2.0 is not permitted).
+        # HexaPDF preserves the source version in the written header, so
+        # patch it here if the source was PDF 2.0.
+        result.sub!(/\A%PDF-2\.\d/, "%PDF-1.7")
+        result
+      end
+
+      private_class_method def self.update_xmp(doc, profile)
+        raw_xmp = build_xmp(profile)
+
+        # HexaPDF stores XMP in the document's metadata stream.
+        meta = doc.catalog[:Metadata]
+        if meta
+          meta.stream = raw_xmp
+        else
+          meta = doc.add({ Type: :Metadata, Subtype: :XML })
+          meta.stream = raw_xmp
+          doc.catalog[:Metadata] = meta
+        end
+      end
+
+      # rubocop:disable Metrics/MethodLength
+      private_class_method def self.build_xmp(profile)
+        <<~XMP
+          <?xpacket begin="\xEF\xBB\xBF" 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/"
+                xmlns:#{FX_PREFIX}="#{FX_NAMESPACE}">
+                <pdfaid:part>3</pdfaid:part>
+                <pdfaid:conformance>B</pdfaid:conformance>
+                <#{FX_PREFIX}:DocumentType>INVOICE</#{FX_PREFIX}:DocumentType>
+                <#{FX_PREFIX}:DocumentFileName>#{FILENAME}</#{FX_PREFIX}:DocumentFileName>
+                <#{FX_PREFIX}:Version>1.0</#{FX_PREFIX}:Version>
+                <#{FX_PREFIX}:ConformanceLevel>#{profile}</#{FX_PREFIX}:ConformanceLevel>
+              </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_NAMESPACE}</pdfaSchema:namespaceURI>
+                      <pdfaSchema:prefix>#{FX_PREFIX}</pdfaSchema:prefix>
+                      <pdfaSchema:property>
+                        <rdf:Seq>
+                          <rdf:li rdf:parseType="Resource">
+                            <pdfaProperty:name>DocumentFileName</pdfaProperty:name>
+                            <pdfaProperty:valueType>Text</pdfaProperty:valueType>
+                            <pdfaProperty:category>external</pdfaProperty:category>
+                            <pdfaProperty:description>The name of the embedded XML invoice file</pdfaProperty:description>
+                          </rdf:li>
+                          <rdf:li rdf:parseType="Resource">
+                            <pdfaProperty:name>DocumentType</pdfaProperty:name>
+                            <pdfaProperty:valueType>Text</pdfaProperty:valueType>
+                            <pdfaProperty:category>external</pdfaProperty:category>
+                            <pdfaProperty:description>The type of the hybrid document (INVOICE)</pdfaProperty:description>
+                          </rdf:li>
+                          <rdf:li rdf:parseType="Resource">
+                            <pdfaProperty:name>Version</pdfaProperty:name>
+                            <pdfaProperty:valueType>Text</pdfaProperty:valueType>
+                            <pdfaProperty:category>external</pdfaProperty:category>
+                            <pdfaProperty:description>The version of the Factur-X specification</pdfaProperty:description>
+                          </rdf:li>
+                          <rdf:li rdf:parseType="Resource">
+                            <pdfaProperty:name>ConformanceLevel</pdfaProperty:name>
+                            <pdfaProperty:valueType>Text</pdfaProperty:valueType>
+                            <pdfaProperty:category>external</pdfaProperty:category>
+                            <pdfaProperty:description>The conformance level of the embedded XML invoice</pdfaProperty:description>
+                          </rdf:li>
+                        </rdf:Seq>
+                      </pdfaSchema:property>
+                    </rdf:li>
+                  </rdf:Bag>
+                </pdfaExtension:schemas>
+              </rdf:Description>
+            </rdf:RDF>
+          </x:xmpmeta>
+          <?xpacket end="w"?>
+        XMP
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      private_class_method def self.add_output_intent(doc)
+        icc_path = File.join(DATA_DIR, "srgb.icc")
+        icc_data = File.binread(icc_path)
+
+        icc_stream = doc.add(
+          { Type: :ICCBased, N: 3, Alternate: :DeviceRGB },
+          stream: icc_data
+        )
+        icc_stream.set_filter(:FlateDecode)
+
+        output_intent = doc.add({
+          Type:                      :OutputIntent,
+          S:                         :GTS_PDFA1,
+          OutputConditionIdentifier: "sRGB IEC61966-2.1",
+          Info:                      "sRGB IEC61966-2.1",
+          DestOutputProfile:         icc_stream
+        })
+
+        doc.catalog[:OutputIntents] = [output_intent]
+      end
+
+      private_class_method def self.md5(bytes)
+        require "digest"
+        Digest::MD5.digest(bytes)
+      end
+    end
+  end
+end

data/lib/einvoicing/formats/ubl.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module Einvoicing
+  module Formats
+    # Generates UBL 2.1 XML compliant with EN 16931 / Peppol BIS Billing 3.0.
+    #
+    # @example
+    #   xml = Einvoicing::Formats::UBL.generate(invoice)
+    #   File.write("invoice.xml", xml)
+    module UBL
+      CUSTOMIZATION_ID = "urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0"
+      PROFILE_ID       = "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0"
+
+      UBL_NS             = "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
+      UBL_CREDIT_NOTE_NS = "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2"
+      CAC_NS             = "urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
+      CBC_NS             = "urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2"
+
+      def self.generate(invoice)
+        b = XMLBuilder.new
+        credit_note = invoice.document_type == :credit_note
+        root_ns = credit_note ? UBL_CREDIT_NOTE_NS : UBL_NS
+        root_tag = credit_note ? "CreditNote" : "Invoice"
+        b.tag(
+          root_tag,
+          "xmlns"     => root_ns,
+          "xmlns:cac" => CAC_NS,
+          "xmlns:cbc" => CBC_NS
+        ) do
+          header(b, invoice)
+          supplier_party(b, invoice.seller)
+          customer_party(b, invoice.buyer)
+          billing_reference(b, invoice) if credit_note && invoice.original_invoice_number
+          payment_means(b, invoice) if invoice.payment_means_code
+          tax_total(b, invoice)
+          monetary_total(b, invoice)
+          invoice.lines.each_with_index do |line, idx|
+            invoice_line(b, line, idx + 1, invoice.currency)
+          end
+        end
+        b.to_xml
+      end
+
+      # -- Private helpers ---------------------------------------------------
+
+      def self.header(b, invoice)
+        b.text("cbc:CustomizationID", CUSTOMIZATION_ID)
+        b.text("cbc:ProfileID",       PROFILE_ID)
+        b.text("cbc:ID",              invoice.invoice_number)
+        b.text("cbc:IssueDate",       format_date(invoice.issue_date))
+        b.text("cbc:DueDate",         format_date(invoice.due_date)) if invoice.due_date
+        b.text("cbc:InvoiceTypeCode", invoice.document_type == :credit_note ? "381" : "380")
+        b.text("cbc:Note",            invoice.note) if invoice.note
+        b.text("cbc:DocumentCurrencyCode", invoice.currency)
+        b.text("cbc:TaxCurrencyCode", invoice.tax_currency) if invoice.tax_currency
+        b.text("cbc:BuyerReference",  invoice.payment_reference || invoice.invoice_number)
+      end
+      private_class_method :header
+
+      def self.supplier_party(b, party)
+        b.tag("cac:AccountingSupplierParty") do
+          b.tag("cac:Party") do
+            party_name(b, party)
+            postal_address(b, party)
+            tax_scheme(b, party)
+            legal_entity(b, party)
+          end
+        end
+      end
+      private_class_method :supplier_party
+
+      def self.customer_party(b, party)
+        b.tag("cac:AccountingCustomerParty") do
+          b.tag("cac:Party") do
+            party_name(b, party)
+            postal_address(b, party)
+            tax_scheme(b, party)
+            legal_entity(b, party)
+          end
+        end
+      end
+      private_class_method :customer_party
+
+      def self.party_name(b, party)
+        b.tag("cac:PartyName") do
+          b.text("cbc:Name", party.name)
+        end
+      end
+      private_class_method :party_name
+
+      def self.postal_address(b, party)
+        b.tag("cac:PostalAddress") do
+          b.text("cbc:StreetName",  party.street)
+          b.text("cbc:CityName",    party.city)
+          b.text("cbc:PostalZone",  party.postal_code)
+          b.tag("cac:Country") do
+            b.text("cbc:IdentificationCode", party.country_code || "FR")
+          end
+        end
+      end
+      private_class_method :postal_address
+
+      def self.tax_scheme(b, party)
+        return unless party.vat_number
+
+        b.tag("cac:PartyTaxScheme") do
+          b.text("cbc:CompanyID", party.vat_number)
+          b.tag("cac:TaxScheme") { b.text("cbc:ID", "VAT") }
+        end
+      end
+      private_class_method :tax_scheme
+
+      def self.legal_entity(b, party)
+        b.tag("cac:PartyLegalEntity") do
+          b.text("cbc:RegistrationName", party.name)
+          b.text("cbc:CompanyID", party.siren_number, "schemeID" => "0002") if party.siren_number
+        end
+      end
+      private_class_method :legal_entity
+
+      def self.tax_total(b, invoice)
+        b.tag("cac:TaxTotal") do
+          b.text("cbc:TaxAmount", format_amount(invoice.tax_total),
+                 "currencyID" => invoice.currency)
+          invoice.tax_breakdown.each do |tax|
+            b.tag("cac:TaxSubtotal") do
+              b.text("cbc:TaxableAmount", format_amount(tax.taxable_amount),
+                     "currencyID" => invoice.currency)
+              b.text("cbc:TaxAmount", format_amount(tax.tax_amount),
+                     "currencyID" => invoice.currency)
+              b.tag("cac:TaxCategory") do
+                b.text("cbc:ID",      tax.category_code)
+                b.text("cbc:Percent", format_amount(tax.rate_percent))
+                b.tag("cac:TaxScheme") { b.text("cbc:ID", "VAT") }
+              end
+            end
+          end
+        end
+      end
+      private_class_method :tax_total
+
+      def self.monetary_total(b, invoice)
+        b.tag("cac:LegalMonetaryTotal") do
+          b.text("cbc:LineExtensionAmount", format_amount(invoice.net_total),
+                 "currencyID" => invoice.currency)
+          b.text("cbc:TaxExclusiveAmount", format_amount(invoice.net_total),
+                 "currencyID" => invoice.currency)
+          b.text("cbc:TaxInclusiveAmount", format_amount(invoice.gross_total),
+                 "currencyID" => invoice.currency)
+          b.text("cbc:PayableAmount", format_amount(invoice.due_amount),
+                 "currencyID" => invoice.currency)
+        end
+      end
+      private_class_method :monetary_total
+
+      def self.invoice_line(b, line, index, currency)
+        b.tag("cac:InvoiceLine") do
+          b.text("cbc:ID", index.to_s)
+          b.text("cbc:InvoicedQuantity", format_quantity(line.quantity), "unitCode" => line.unit)
+          b.text("cbc:LineExtensionAmount", format_amount(line.net_amount),
+                 "currencyID" => currency)
+          b.tag("cac:Item") do
+            b.text("cbc:Description", line.description)
+            b.text("cbc:Name",        line.description)
+            b.tag("cac:ClassifiedTaxCategory") do
+              b.text("cbc:ID",      line.tax_category_code)
+              b.text("cbc:Percent", format_amount(line.vat_rate_percent))
+              b.tag("cac:TaxScheme") { b.text("cbc:ID", "VAT") }
+            end
+          end
+          b.tag("cac:Price") do
+            b.text("cbc:PriceAmount", format_amount(line.unit_price),
+                   "currencyID" => currency)
+          end
+        end
+      end
+      private_class_method :invoice_line
+
+      def self.billing_reference(b, invoice)
+        b.tag("cac:BillingReference") do
+          b.tag("cac:InvoiceDocumentReference") do
+            b.text("cbc:ID", invoice.original_invoice_number)
+            if invoice.original_invoice_date
+              b.text("cbc:IssueDate", format_date(invoice.original_invoice_date))
+            end
+          end
+        end
+      end
+      private_class_method :billing_reference
+
+      def self.payment_means(b, invoice)
+        b.tag("cac:PaymentMeans") do
+          b.text("cbc:PaymentMeansCode", invoice.payment_means_code.to_s)
+          if invoice.iban
+            b.tag("cac:PayeeFinancialAccount") do
+              b.text("cbc:ID", invoice.iban)
+              if invoice.bic
+                b.tag("cac:FinancialInstitutionBranch") do
+                  b.text("cbc:ID", invoice.bic)
+                end
+              end
+            end
+          end
+        end
+      end
+      private_class_method :payment_means
+
+      def self.format_date(date)
+        d = date.is_a?(Date) ? date : Date.parse(date.to_s)
+        d.strftime("%Y-%m-%d")
+      end
+      private_class_method :format_date
+
+      def self.format_amount(value)
+        format("%.2f", value)
+      end
+      private_class_method :format_amount
+
+      def self.format_quantity(value)
+        v = value.to_f
+        v % 1 == 0 ? v.to_i.to_s : format("%.4f", v)
+      end
+      private_class_method :format_quantity
+    end
+  end
+end

data/lib/einvoicing/i18n.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Einvoicing
+  # Thin wrapper around ::I18n with graceful fallback for standalone use.
+  # When used outside Rails, ::I18n may not be available; in that case the
+  # dotted key string is returned as-is.
+  module I18n
+    DEFAULT_LOCALE = :en
+
+    def self.t(key, **options)
+      return key.to_s unless defined?(::I18n)
+
+      locale = options.delete(:locale) { ::I18n.locale rescue DEFAULT_LOCALE }
+      ::I18n.t("einvoicing.#{key}", locale: locale, **options)
+    rescue ::I18n::MissingTranslationData
+      # Fallback to English if translation missing in current locale
+      ::I18n.t("einvoicing.#{key}", locale: DEFAULT_LOCALE, **options)
+    rescue StandardError
+      key.to_s
+    end
+  end
+end

data/lib/einvoicing/invoice.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "bigdecimal/util"
+
+module Einvoicing
+  # Core invoice model. All monetary values are in the invoice currency.
+  #
+  # @example
+  #   seller = Einvoicing::Party.new(name: "Acme SAS", siren: "123456789", vat_number: "FR12123456789")
+  #   buyer  = Einvoicing::Party.new(name: "Client SA", siren: "987654321")
+  #   line   = Einvoicing::LineItem.new(description: "Consulting", quantity: 1, unit_price: 1000.00)
+  #
+  #   invoice = Einvoicing::Invoice.new(
+  #     invoice_number: "INV-2024-001",
+  #     issue_date: Date.today,
+  #     seller: seller,
+  #     buyer: buyer,
+  #     lines: [line]
+  #   )
+  Invoice = Data.define(
+    :invoice_number,
+    :issue_date,
+    :due_date,
+    :currency,
+    :tax_currency,
+    :seller,
+    :buyer,
+    :lines,
+    :tax_breakdown,
+    :payment_reference,
+    :note,
+    :payment_means_code,
+    :iban,
+    :bic,
+    :document_type,
+    :original_invoice_number,
+    :original_invoice_date
+  ) do
+    def initialize(invoice_number:, issue_date:, seller:, buyer:, lines:,
+                   due_date: nil, currency: "EUR", tax_currency: nil, tax_breakdown: nil,
+                   payment_reference: nil, note: nil,
+                   payment_means_code: nil, iban: nil, bic: nil,
+                   document_type: :invoice, original_invoice_number: nil, original_invoice_date: nil)
+      computed_breakdown = tax_breakdown || compute_tax_breakdown(lines)
+      super(
+        invoice_number: invoice_number,
+        issue_date: issue_date,
+        due_date: due_date,
+        currency: currency,
+        tax_currency: tax_currency,
+        seller: seller,
+        buyer: buyer,
+        lines: lines,
+        tax_breakdown: computed_breakdown,
+        payment_reference: payment_reference,
+        note: note,
+        payment_means_code: payment_means_code,
+        iban: iban,
+        bic: bic,
+        document_type: document_type,
+        original_invoice_number: original_invoice_number,
+        original_invoice_date: original_invoice_date
+      )
+    end
+
+    # Sum of all line net amounts (excl. VAT).
+    def net_total
+      lines.sum(BigDecimal("0"), &:net_amount).round(2, :half_up)
+    end
+
+    # Total VAT across all lines.
+    def tax_total
+      tax_breakdown.sum(BigDecimal("0"), &:tax_amount).round(2, :half_up)
+    end
+
+    # Grand total including VAT — computed from per-line gross amounts to avoid
+    # double-rounding through already-rounded net_total/tax_total (EN 16931 BR-CO-13).
+    def gross_total
+      lines.sum(BigDecimal("0"), &:gross_amount).round(2, :half_up)
+    end
+
+    # Amount due (same as gross_total; override for prepayments).
+    def due_amount
+      gross_total
+    end
+
+    private
+
+    def compute_tax_breakdown(lines)
+      grouped = lines.group_by { |l| [l.vat_rate, l.category] }
+      grouped.map do |(rate, category), rate_lines|
+        taxable = rate_lines.sum(BigDecimal("0"), &:net_amount).round(2, :half_up)
+        tax_amt = rate_lines.sum(BigDecimal("0"), &:vat_amount).round(2, :half_up)
+        Tax.new(rate: rate, taxable_amount: taxable, tax_amount: tax_amt, category: category)
+      end
+    end
+  end
+end

data/lib/einvoicing/invoiceable.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Einvoicing
+  # ActiveSupport::Concern that adds e-invoicing capabilities to an
+  # ActiveRecord model.
+  #
+  # The model must respond to the following methods (columns or Ruby methods):
+  #   invoice_number, issue_date, due_date, currency,
+  #   einvoicing_seller, einvoicing_buyer, einvoicing_lines
+  #
+  # @example
+  #   class Invoice < ApplicationRecord
+  #     include Einvoicing::Invoiceable
+  #
+  #     def einvoicing_seller
+  #       Einvoicing::Party.new(
+  #         name:       company.name,
+  #         siren:      company.siren,
+  #         vat_number: company.vat_number,
+  #         street:     company.street,
+  #         city:       company.city,
+  #         postal_code: company.postal_code
+  #       )
+  #     end
+  #
+  #     def einvoicing_buyer
+  #       Einvoicing::Party.new(name: client.name, siren: client.siren)
+  #     end
+  #
+  #     def einvoicing_lines
+  #       line_items.map do |li|
+  #         Einvoicing::LineItem.new(
+  #           description: li.description,
+  #           quantity:    li.quantity,
+  #           unit_price:  li.unit_price,
+  #           vat_rate:    li.vat_rate
+  #         )
+  #       end
+  #     end
+  #   end
+  module Invoiceable
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # Override to use a different validator. Defaults to FR.
+      # @example
+      #   self.einvoicing_validator = Einvoicing::Validators::DE
+      def einvoicing_validator
+        @einvoicing_validator || Einvoicing::Validators::FR
+      end
+
+      def einvoicing_validator=(validator)
+        @einvoicing_validator = validator
+      end
+    end
+
+    # Build an Einvoicing::Invoice from this record.
+    # @return [Einvoicing::Invoice]
+    def to_einvoice
+      has_due_date = self.class.respond_to?(:column_names) \
+        ? self.class.column_names.include?("due_date") \
+        : respond_to?(:due_date)
+
+      Einvoicing::Invoice.new(
+        invoice_number: invoice_number,
+        issue_date:     issue_date,
+        due_date:       has_due_date ? due_date : nil,
+        currency:       respond_to?(:currency) ? (currency || "EUR") : "EUR",
+        seller:         einvoicing_seller,
+        buyer:          einvoicing_buyer,
+        lines:          einvoicing_lines
+      )
+    end
+
+    # Generate CII D16B XML string.
+    # @return [String]
+    def to_cii_xml
+      Einvoicing::Formats::CII.generate(to_einvoice)
+    end
+
+    # Generate UBL 2.1 XML string.
+    # @return [String]
+    def to_ubl_xml
+      Einvoicing::Formats::UBL.generate(to_einvoice)
+    end
+
+    # Generate Factur-X PDF by embedding CII XML into an existing PDF blob.
+    # @param pdf_data [String] original PDF binary
+    # @return [String] Factur-X PDF binary
+    def to_facturx(pdf_data)
+      xml = to_cii_xml
+      Einvoicing::Formats::FacturX.embed(pdf_data, xml)
+    end
+
+    # Validate the invoice using the configured validator.
+    # @return [Array<Hash>] list of error hashes ({ field:, error:, message: })
+    def einvoicing_errors
+      self.class.einvoicing_validator.validate(to_einvoice)
+    end
+
+    # @return [Boolean]
+    def einvoicing_valid?
+      einvoicing_errors.empty?
+    end
+
+    # Raise ValidationError unless valid.
+    def validate_einvoice!
+      self.class.einvoicing_validator.validate!(to_einvoice)
+    end
+
+    # Stub: override in your model or configure an adapter.
+    # Returns a hash with :status and optionally :reference.
+    def transmit!(adapter: nil)
+      raise NotImplementedError,
+            "Configure a transmission adapter or override #transmit! in #{self.class}"
+    end
+  end
+end