einvoicing 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d6bcd9f49244d9bbf84368950614affcd7aa4d5c1b0c04d916fccb7f7fc746f1
-  data.tar.gz: f545fef84047395303df7de366869e9141f902aafcb36ddb4d6950ea1a418437
+  metadata.gz: 01ba6a9d7f94ac75ba98a3c64141ae25293b27323e8f8c8b55c147bd8ae5ff4c
+  data.tar.gz: 9e929b17b7f00a01b23186b9e8ebded133bb5e3a7fc60da9f6cbbb271cab2074
 SHA512:
-  metadata.gz: f38dec217a71dd543058aa3e0fc92f66f92250eda2f64a6c23dccf247689e47ff5891bcd99e6b8186a6791b7814fca95347b3ec9a14dfdd05c42c1c0d2d5741a
-  data.tar.gz: cf284e33d542d80acc5e693d5d46f4b0639f8b9f8c99887d98316e086efaaf6919514c66b12af8b4cc19a40f96b396948f856fe5de40b554e546efce3615efd3
+  metadata.gz: 4c70ee9bfa6505caa0d17993a166bdf9220bd435649893ca349cb0e3efc2d8948db40fb691293f833a3ad0eb0318a9924eadd53415872c47b552a99e30d2153d
+  data.tar.gz: 4adc977fe39f03b2aa1395ca0ade81ff3d942425f1e580994b48b212c5dba458e305d1fb78776f5d36138c73d30239aa3e8e82b268db1f2fac4193633838f15f

data/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+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.3.0] - 2026-03-13
+
+### Added
+- Credit notes (`document_type: :credit_note`, TypeCode 381) in CII and UBL
+- BillingReference in UBL credit notes referencing original invoice
+- IBAN and BIC format validation in FR validator
+- TaxCurrencyCode support in UBL for non-EUR invoices
+- XSD schema validation in test suite
+- BuyerReference always emitted in UBL (EN 16931 BT-10 compliance, fallback to invoice_number)
+
+## [0.2.0] - 2026-03-13
+
+### Added
+- i18n error messages with English and French translations
+- Payment means support (IBAN, BIC, payment type code) in CII and UBL
+- Ruby symbol error codes in validators (`{ field:, error:, message: }`)
+- Configurable validator in Invoiceable concern (`einvoicing_validator=`)
+- ELI5 documentation in docs/eli5-e-invoicing.md
+
+### Fixed
+- PDF/A-3 conformance: bundled sRGB ICC profile for OutputIntent (Mustang PDF:valid)
+- BigDecimal arithmetic throughout (was Float — rounding errors on financial totals)
+- CII element ordering: URIUniversalCommunication before SpecifiedTaxRegistration
+- Reverse charge: category: :reverse_charge instead of sentinel -1; emits RateApplicablePercent 0
+- BuyerReference emitted in ApplicableHeaderTradeAgreement
+- Empty XML elements suppressed by XMLBuilder
+- SIREN/SIRET examples in sample script use known-valid Luhn values
+- Gemfile.lock excluded from gem package
+
+### Changed
+- Validator errors now return `Array<Hash>` with `:field`, `:error`, `:message` keys
+- All monetary amounts use BigDecimal (breaking change for Float inputs: wrap in BigDecimal())
+
+## [0.1.0] - 2026-03-13
+
+### Added
+- Core invoice data model (`Invoice`, `Party`, `LineItem`, `Tax`) using Ruby 3.2 `Data.define`
+- CII D16B XML generator (`Einvoicing::Formats::CII`) — EN 16931 / Factur-X EN16931 profile
+- UBL 2.1 XML generator (`Einvoicing::Formats::UBL`) — EN 16931 / Peppol BIS Billing 3.0
+- Factur-X embedding (`Einvoicing::Formats::FacturX`) — embeds CII XML into PDF/A-3 via hexapdf
+- French validators (`Einvoicing::Validators::FR`) — SIREN, SIRET (Luhn), TVA format, invoice number
+- Rails concern (`Einvoicing::Invoiceable`) — `to_cii_xml`, `to_ubl_xml`, `to_facturx`, `einvoicing_valid?`
+- Rails engine (`Einvoicing::Rails::Engine`)
+- Zero runtime dependencies beyond hexapdf (stdlib-only XML generation via internal builder)
+- RSpec test suite
+
+[Unreleased]: https://github.com/sxnlabs/einvoicing/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/sxnlabs/einvoicing/releases/tag/v0.1.0

data/README.md

@@ -0,0 +1,277 @@
+# einvoicing
+
+[![Gem Version](https://badge.fury.io/rb/einvoicing.svg)](https://rubygems.org/gems/einvoicing)
+[![CI](https://github.com/sxnlabs/einvoicing/actions/workflows/ci.yml/badge.svg)](https://github.com/sxnlabs/einvoicing/actions)
+
+**EN 16931 electronic invoicing for Ruby.** Generate Factur-X (PDF/A-3 + CII XML), UBL 2.1, and CII D16B invoices. Validate French B2B compliance (SIREN, SIRET, TVA). Rails-ready.
+
+## Why
+
+France mandates structured e-invoicing for all B2B transactions starting **September 2026** (Ordonnance n° 2021-1190). Every invoice between French VAT-registered companies must be issued in a structured format (Factur-X, UBL, or CII) and transmitted via the PPF or a certified PDP.
+
+This gem gives you a clean Ruby API to build compliant invoices, validate them against French rules, and produce all required output formats — without pulling in a heavy XML library.
+
+## Features
+
+- Generate **Factur-X** invoices (PDF/A-3b with embedded CII D16B XML)
+- Generate **UBL 2.1** XML (Peppol BIS Billing 3.0)
+- Generate **CII D16B** XML (EN 16931 / ZUGFeRD)
+- Validate French B2B requirements: SIREN, SIRET (Luhn), TVA format, standard VAT rates
+- Structured error reporting: `{ field:, error:, message: }` with i18n support (EN + FR)
+- Payment means: IBAN, BIC/SWIFT, UNCL4461 type codes
+- **Rails concern** (`Einvoicing::Invoiceable`) for ActiveRecord models
+- Only one runtime dependency: `hexapdf` (for PDF/A-3 embedding). XML generation uses Ruby stdlib.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "einvoicing"
+```
+
+```sh
+bundle install
+```
+
+## Quick Start
+
+```ruby
+require "einvoicing"
+require "date"
+
+seller = Einvoicing::Party.new(
+  name:         "SXN Labs",
+  street:       "5 Lot Coat an Lem",
+  city:         "Plouezoc'h",
+  postal_code:  "29252",
+  country_code: "FR",
+  siren:        "898208145",
+  siret:        "89820814500018",
+  vat_number:   "FR46898208145",
+  email:        "contact@sxnlabs.com"
+)
+
+buyer = Einvoicing::Party.new(
+  name:         "Gecobat",
+  street:       "12 rue du Bâtiment",
+  city:         "Paris",
+  postal_code:  "75001",
+  country_code: "FR",
+  siren:        "552032534",
+  vat_number:   "FR83552032534"
+)
+
+lines = [
+  Einvoicing::LineItem.new(
+    description: "Développement backend — API REST (forfait)",
+    quantity:    1,
+    unit_price:  BigDecimal("2500.00"),
+    vat_rate:    0.20
+  ),
+  Einvoicing::LineItem.new(
+    description: "Intégration Factur-X",
+    quantity:    5,
+    unit_price:  BigDecimal("350.00"),
+    vat_rate:    0.20
+  )
+]
+
+invoice = Einvoicing::Invoice.new(
+  invoice_number:     "FAC-2024-0042",
+  issue_date:         Date.new(2024, 3, 15),
+  due_date:           Date.new(2024, 4, 15),
+  seller:             seller,
+  buyer:              buyer,
+  lines:              lines,
+  payment_reference:  "FAC-2024-0042",
+  note:               "30 jours net",
+  payment_means_code: 30,
+  iban:               "FR7630006000011234567890189",
+  bic:                "BNPAFRPP"
+)
+
+# Totals are computed automatically (BigDecimal, no rounding errors)
+invoice.net_total    # => 0.4000e4  (4000.00)
+invoice.tax_total    # => 0.800e3   (800.00)
+invoice.gross_total  # => 0.4800e4  (4800.00)
+
+# Validate for French compliance
+errors = Einvoicing::Validators::FR.validate(invoice)
+errors.empty? # => true
+
+# Generate CII D16B XML (Factur-X / ZUGFeRD)
+xml = Einvoicing::Formats::CII.generate(invoice)
+File.write("invoice.xml", xml)
+
+# Generate UBL 2.1 XML (Peppol)
+ubl = Einvoicing::Formats::UBL.generate(invoice)
+File.write("invoice_ubl.xml", ubl)
+
+# Embed CII XML into an existing PDF → Factur-X PDF/A-3
+pdf_data   = File.binread("invoice.pdf")
+facturx    = Einvoicing::Formats::FacturX.embed(pdf_data, xml)
+File.binwrite("invoice_facturx.pdf", facturx)
+```
+
+## Validation Errors
+
+Errors are returned as an array of hashes — no exceptions, no monkey-patching:
+
+```ruby
+errors = Einvoicing::Validators::FR.validate(invoice)
+# => [
+#   { field: :seller_siren, error: :siren_invalid,  message: "SIREN is invalid" },
+#   { field: :invoice_number, error: :number_invalid, message: "Invoice number format is invalid" }
+# ]
+
+# Raise instead of returning
+Einvoicing::Validators::FR.validate!(invoice)
+# => raises Einvoicing::Validators::ValidationError on failure
+```
+
+### i18n (French messages)
+
+The gem integrates with Rails i18n automatically. For standalone Ruby, set the locale before validating:
+
+```ruby
+require "i18n"
+I18n.load_path += Dir[File.join(__dir__, "config/locales/*.yml")]
+I18n.locale = :fr
+
+errors = Einvoicing::Validators::FR.validate(invoice)
+# => [{ field: :seller_siren, error: :siren_invalid, message: "Le numéro SIREN est invalide" }]
+```
+
+## Formats
+
+### Factur-X (PDF/A-3 + CII)
+
+The standard French hybrid format: a valid PDF that also carries machine-readable XML inside.
+
+```ruby
+xml      = Einvoicing::Formats::CII.generate(invoice)
+pdf_data = File.binread("invoice.pdf")
+facturx  = Einvoicing::Formats::FacturX.embed(pdf_data, xml)
+File.binwrite("invoice_facturx.pdf", facturx)
+```
+
+The result is PDF/A-3b conformant with an embedded `factur-x.xml` file tagged as `AFRelationship: Data`.
+
+### CII D16B (XML only)
+
+```ruby
+xml = Einvoicing::Formats::CII.generate(invoice)
+```
+
+Produces a `rsm:CrossIndustryInvoice` document with guideline ID `urn:cen.eu:en16931:2017`.
+
+### UBL 2.1 (Peppol)
+
+```ruby
+ubl = Einvoicing::Formats::UBL.generate(invoice)
+```
+
+Produces a UBL 2.1 `Invoice` document with Peppol BIS Billing 3.0 customization ID.
+
+## Rails Integration
+
+Include `Einvoicing::Invoiceable` in your ActiveRecord model and implement three methods:
+
+```ruby
+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.address_street,
+      city:        company.address_city,
+      postal_code: company.address_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_excl_tax,
+        vat_rate:    li.vat_rate
+      )
+    end
+  end
+end
+```
+
+Then in a controller or service:
+
+```ruby
+invoice = Invoice.find(42)
+
+if invoice.einvoicing_valid?
+  cii_xml = invoice.to_cii_xml
+  ubl_xml = invoice.to_ubl_xml
+
+  pdf_data    = invoice.pdf_attachment.download
+  facturx_pdf = invoice.to_facturx(pdf_data)
+else
+  puts invoice.einvoicing_errors.map { |e| e[:message] }
+end
+```
+
+### Custom validator
+
+Use a different validator (e.g. for a non-French context):
+
+```ruby
+class Invoice < ApplicationRecord
+  include Einvoicing::Invoiceable
+  self.einvoicing_validator = Einvoicing::Validators::FR  # default; swap for your own
+end
+```
+
+A custom validator is any module that responds to `.validate(invoice)` and returns `Array<Hash>`.
+
+## Payment Means
+
+Add IBAN, BIC, and UNCL4461 payment type code to the invoice. Both CII and UBL generators emit the appropriate elements automatically.
+
+```ruby
+invoice = Einvoicing::Invoice.new(
+  # ... other fields ...
+  payment_means_code: 30,               # UNCL4461: 30 = credit transfer
+  iban:               "FR7630006000011234567890189",
+  bic:                "BNPAFRPP"
+)
+```
+
+Common `payment_means_code` values (UNCL4461):
+
+| Code | Meaning |
+|------|---------|
+| 30   | Credit transfer |
+| 42   | Payment to bank account |
+| 58   | SEPA credit transfer |
+
+## Requirements
+
+- **Ruby >= 3.2** (uses `Data.define`)
+- **hexapdf ~> 1.0** (runtime, for Factur-X PDF/A-3 embedding)
+- **Java** (optional) — for local validation with the Mustang CLI validator
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Write tests first (`bundle exec rspec`)
+4. Submit a pull request
+
+## License
+
+MIT — see [LICENSE](LICENSE).

data/config/locales/einvoicing.en.yml

@@ -0,0 +1,27 @@
+en:
+  einvoicing:
+    errors:
+      invoice:
+        number_missing: "Invoice number is required"
+        number_invalid: "Invoice number format is invalid (1-35 alphanumeric/dash/slash chars)"
+        issue_date_missing: "Issue date is required"
+        currency_missing: "Currency is required"
+        lines_empty: "Invoice must have at least one line item"
+        original_invoice_number_missing: "Original invoice number is required for credit notes"
+        iban_invalid: "IBAN format or checksum is invalid"
+        bic_invalid: "BIC format is invalid (8 or 11 characters)"
+      seller:
+        name_missing: "Seller name is required"
+        siren_invalid: "Seller SIREN must be 9 digits (Luhn check failed)"
+        siret_invalid: "Seller SIRET must be 14 digits (Luhn check failed)"
+        vat_number_invalid: "Seller VAT number must be in format FR + 2 chars + 9 digits"
+      buyer:
+        name_missing: "Buyer name is required"
+        siren_invalid: "Buyer SIREN must be 9 digits (Luhn check failed)"
+        siret_invalid: "Buyer SIRET must be 14 digits (Luhn check failed)"
+        vat_number_invalid: "Buyer VAT number must be in format FR + 2 chars + 9 digits"
+      line:
+        description_missing: "Line %{index}: description is required"
+        quantity_invalid: "Line %{index}: quantity must be positive"
+        unit_price_invalid: "Line %{index}: unit price must be non-negative"
+        vat_rate_invalid: "Line %{index}: VAT rate must be a known French rate (0%%, 5.5%%, 10%%, 20%%)"

data/config/locales/einvoicing.fr.yml

@@ -0,0 +1,27 @@
+fr:
+  einvoicing:
+    errors:
+      invoice:
+        number_missing: "Le numéro de facture est requis"
+        number_invalid: "Le format du numéro de facture est invalide (1 à 35 caractères alphanumériques, tirets ou barres obliques)"
+        issue_date_missing: "La date d'émission est requise"
+        currency_missing: "La devise est requise"
+        lines_empty: "La facture doit comporter au moins une ligne"
+        original_invoice_number_missing: "Le numéro de facture d'origine est requis pour les avoirs"
+        iban_invalid: "Le format ou la somme de contrôle de l'IBAN est invalide"
+        bic_invalid: "Le format du BIC est invalide (8 ou 11 caractères)"
+      seller:
+        name_missing: "Le nom du vendeur est requis"
+        siren_invalid: "Le SIREN du vendeur doit comporter 9 chiffres (vérification Luhn échouée)"
+        siret_invalid: "Le SIRET du vendeur doit comporter 14 chiffres (vérification Luhn échouée)"
+        vat_number_invalid: "Le numéro de TVA du vendeur doit être au format FR + 2 caractères + 9 chiffres"
+      buyer:
+        name_missing: "Le nom de l'acheteur est requis"
+        siren_invalid: "Le SIREN de l'acheteur doit comporter 9 chiffres (vérification Luhn échouée)"
+        siret_invalid: "Le SIRET de l'acheteur doit comporter 14 chiffres (vérification Luhn échouée)"
+        vat_number_invalid: "Le numéro de TVA de l'acheteur doit être au format FR + 2 caractères + 9 chiffres"
+      line:
+        description_missing: "Ligne %{index} : la description est requise"
+        quantity_invalid: "Ligne %{index} : la quantité doit être positive"
+        unit_price_invalid: "Ligne %{index} : le prix unitaire doit être non négatif"
+        vat_rate_invalid: "Ligne %{index} : le taux de TVA doit être un taux français standard (0%%, 5,5%%, 10%%, 20%%)"

data/lib/einvoicing/formats/cii.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+module Einvoicing
+  module Formats
+    # Generates CII D16B (Cross Industry Invoice) XML compliant with EN 16931
+    # and the Factur-X EN16931 profile.
+    #
+    # @example
+    #   xml = Einvoicing::Formats::CII.generate(invoice)
+    #   File.write("invoice.xml", xml)
+    module CII
+      GUIDELINE_ID = "urn:cen.eu:en16931:2017"
+
+      RSM_NS = "urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100"
+      RAM_NS = "urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100"
+      UDT_NS = "urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100"
+      QDT_NS = "urn:un:unece:uncefact:data:standard:QualifiedDataType:100"
+
+      def self.generate(invoice)
+        b = XMLBuilder.new
+        b.tag(
+          "rsm:CrossIndustryInvoice",
+          "xmlns:rsm" => RSM_NS,
+          "xmlns:ram" => RAM_NS,
+          "xmlns:udt" => UDT_NS,
+          "xmlns:qdt" => QDT_NS,
+          "xmlns:xsi" => "http://www.w3.org/2001/XMLSchema-instance"
+        ) do
+          exchanged_document_context(b)
+          exchanged_document(b, invoice)
+          supply_chain_trade_transaction(b, invoice)
+        end
+        b.to_xml
+      end
+
+      # -- Private helpers ---------------------------------------------------
+
+      def self.exchanged_document_context(b)
+        b.tag("rsm:ExchangedDocumentContext") do
+          b.tag("ram:GuidelineSpecifiedDocumentContextParameter") do
+            b.text("ram:ID", GUIDELINE_ID)
+          end
+        end
+      end
+      private_class_method :exchanged_document_context
+
+      def self.exchanged_document(b, invoice)
+        b.tag("rsm:ExchangedDocument") do
+          b.text("ram:ID", invoice.invoice_number)
+          b.text("ram:TypeCode", invoice.document_type == :credit_note ? "381" : "380")
+          b.tag("ram:IssueDateTime") do
+            b.text("udt:DateTimeString", format_date(invoice.issue_date), "format" => "102")
+          end
+          if invoice.document_type == :credit_note && invoice.original_invoice_number
+            b.tag("ram:IncludedNote") do
+              note = "Avoir sur facture #{invoice.original_invoice_number}"
+              note += " du #{invoice.original_invoice_date.strftime('%d/%m/%Y')}" if invoice.original_invoice_date
+              b.text("ram:Content", note)
+            end
+          end
+          if invoice.note
+            b.tag("ram:IncludedNote") do
+              b.text("ram:Content", invoice.note)
+            end
+          end
+        end
+      end
+      private_class_method :exchanged_document
+
+      def self.supply_chain_trade_transaction(b, invoice)
+        b.tag("rsm:SupplyChainTradeTransaction") do
+          invoice.lines.each_with_index do |line, idx|
+            trade_line_item(b, line, idx + 1, invoice.currency)
+          end
+          header_trade_agreement(b, invoice)
+          b.tag("ram:ApplicableHeaderTradeDelivery")
+          header_trade_settlement(b, invoice)
+        end
+      end
+      private_class_method :supply_chain_trade_transaction
+
+      def self.trade_line_item(b, line, index, currency)
+        b.tag("ram:IncludedSupplyChainTradeLineItem") do
+          b.tag("ram:AssociatedDocumentLineDocument") do
+            b.text("ram:LineID", index.to_s)
+          end
+          b.tag("ram:SpecifiedTradeProduct") do
+            b.text("ram:Name", line.description)
+          end
+          b.tag("ram:SpecifiedLineTradeAgreement") do
+            b.tag("ram:NetPriceProductTradePrice") do
+              b.text("ram:ChargeAmount", format_amount(line.unit_price))
+            end
+          end
+          b.tag("ram:SpecifiedLineTradeDelivery") do
+            b.text("ram:BilledQuantity", format_quantity(line.quantity), "unitCode" => line.unit)
+          end
+          b.tag("ram:SpecifiedLineTradeSettlement") do
+            b.tag("ram:ApplicableTradeTax") do
+              b.text("ram:TypeCode", "VAT")
+              b.text("ram:CategoryCode", line.tax_category_code)
+              b.text("ram:RateApplicablePercent", format_amount(line.vat_rate_percent))
+            end
+            b.tag("ram:SpecifiedTradeSettlementLineMonetarySummation") do
+              b.text("ram:LineTotalAmount", format_amount(line.net_amount))
+            end
+          end
+        end
+      end
+      private_class_method :trade_line_item
+
+      def self.header_trade_agreement(b, invoice)
+        b.tag("ram:ApplicableHeaderTradeAgreement") do
+          # BuyerReference must be first in the sequence (EN 16931 BR-10 / XSD order).
+          b.text("ram:BuyerReference", invoice.payment_reference || "")
+          b.tag("ram:SellerTradeParty") { party_xml(b, invoice.seller) }
+          b.tag("ram:BuyerTradeParty")  { party_xml(b, invoice.buyer) }
+        end
+      end
+      private_class_method :header_trade_agreement
+
+      def self.party_xml(b, party)
+        b.text("ram:Name", party.name)
+        if party.siren_number
+          b.tag("ram:SpecifiedLegalOrganization") do
+            b.text("ram:ID", party.siren_number, "schemeID" => "0002")
+          end
+        end
+        b.tag("ram:PostalTradeAddress") do
+          b.text("ram:PostcodeCode", party.postal_code)
+          b.text("ram:LineOne",      party.street)
+          b.text("ram:CityName",     party.city)
+          b.text("ram:CountryID",    party.country_code || "FR")
+        end
+        if party.email
+          b.tag("ram:URIUniversalCommunication") do
+            b.text("ram:URIID", party.email, "schemeID" => "EM")
+          end
+        end
+        if party.vat_number
+          b.tag("ram:SpecifiedTaxRegistration") do
+            b.text("ram:ID", party.vat_number, "schemeID" => "VA")
+          end
+        end
+      end
+      private_class_method :party_xml
+
+      def self.header_trade_settlement(b, invoice)
+        b.tag("ram:ApplicableHeaderTradeSettlement") do
+          b.text("ram:PaymentReference", invoice.payment_reference || invoice.invoice_number)
+          b.text("ram:InvoiceCurrencyCode", invoice.currency)
+
+          if invoice.payment_means_code
+            b.tag("ram:SpecifiedTradeSettlementPaymentMeans") do
+              b.text("ram:TypeCode", invoice.payment_means_code.to_s)
+              if invoice.iban
+                b.tag("ram:PayeePartyCreditorFinancialAccount") do
+                  b.text("ram:IBANID", invoice.iban)
+                end
+              end
+              if invoice.bic
+                b.tag("ram:PayeeSpecifiedCreditorFinancialInstitution") do
+                  b.text("ram:BICID", invoice.bic)
+                end
+              end
+            end
+          end
+
+          invoice.tax_breakdown.each do |tax|
+            b.tag("ram:ApplicableTradeTax") do
+              b.text("ram:CalculatedAmount", format_amount(tax.tax_amount))
+              b.text("ram:TypeCode", "VAT")
+              b.text("ram:BasisAmount", format_amount(tax.taxable_amount))
+              b.text("ram:CategoryCode", tax.category_code)
+              b.text("ram:RateApplicablePercent", format_amount(tax.rate_percent))
+            end
+          end
+
+          if invoice.due_date
+            b.tag("ram:SpecifiedTradePaymentTerms") do
+              b.tag("ram:DueDateDateTime") do
+                b.text("udt:DateTimeString", format_date(invoice.due_date), "format" => "102")
+              end
+            end
+          end
+
+          b.tag("ram:SpecifiedTradeSettlementHeaderMonetarySummation") do
+            b.text("ram:LineTotalAmount",    format_amount(invoice.net_total))
+            b.text("ram:TaxBasisTotalAmount", format_amount(invoice.net_total))
+            b.text("ram:TaxTotalAmount",     format_amount(invoice.tax_total),
+                   "currencyID" => invoice.currency)
+            b.text("ram:GrandTotalAmount",   format_amount(invoice.gross_total))
+            b.text("ram:DuePayableAmount",   format_amount(invoice.due_amount))
+          end
+        end
+      end
+      private_class_method :header_trade_settlement
+
+      # Format a Date or string as YYYYMMDD (CII date format 102).
+      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