einvoicing 0.8.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 548238110199faaae0ccfe8c7b278169728edb8b57dfb84ae10ba5d871c5e883
-  data.tar.gz: 8a517b11240b33c5f6a80d3fc05db58f7c4531a1375fb72ceb4bc790b284f68c
+  metadata.gz: f41193fc67e566fb4f03b91fcbb9666e81540c72411d03535ac58fe92d3573a2
+  data.tar.gz: 3d36fab9deb25fb3f25cadde7e435c5227a20f37e9011d3c22977659e1058bb2
 SHA512:
-  metadata.gz: fc6e9095689ef5485eba2d52cc576dc6e144f11eaff51ea00128a4608342778d97366cf4d0689632233dc9019bcd3b076bf886340800df0bd8d18855dbbc3b43
-  data.tar.gz: b959a718712cddeb2efd777570b7d780038bc881ee9232be0e99a39bf62a648db5cc1a23730077abea5624f80dcc62fbfb9ba64df4fde97bf64e21f00b8afad5
+  metadata.gz: 98d84a972f5dc4eaa604ca1360d741a916ceac43f54ec824f6dfd25143706c793cb27c5376d2e959cf919e61805fef9eb64066d839a3da3c875a638db9927261
+  data.tar.gz: fa99bcf35ebdbf90bb4ede4a031406201899fc4c288093a634df8126b0b738830340ba1894027b932c84397c232c3f4b8dab7f0cbd208a7a3148fcff1c499cc5

data/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-08-05
+
+Everything here comes from a batch of 15 deliberately hostile Factur-X invoices
+(multi-rate, reverse charge, 500 lines, DOM rates, foreign currency) run through
+the XSD, the PDF/A-3 container checks and a hand-recomputed EN 16931 rule set.
+Four of the five findings were ours.
+
+### Added
+- The full EN 16931 VAT category set (BT-118) on `LineItem`, `AllowanceCharge` and `Tax`: `:standard` (S), `:zero_rated` (Z), `:exempt` (E), `:reverse_charge` (AE), `:intra_community` (K), `:export` (G), `:not_subject` (O). An unknown category now raises instead of silently emitting `S`
+- VAT exemption reason (BT-120) and reason code (BT-121), emitted as `ram:ExemptionReason` / `ram:ExemptionReasonCode` in CII and `cbc:TaxExemptionReason` / `cbc:TaxExemptionReasonCode` in UBL. AE, K, G and O default to their VATEX code (`VATEX-EU-AE`, `VATEX-EU-IC`, `VATEX-EU-G`, `VATEX-EU-O`); E takes the caller's, with `Einvoicing::Tax::VATEX_FR_FRANCHISE` provided for the art. 293 B franchise. S and Z never carry one (BR-Z-10)
+- `tax_exchange_rate` on `Invoice`, plus `#tax_accounting_currency?` and `#tax_total_in_tax_currency`. When BT-6 differs from BT-5, CII now emits `ram:TaxCurrencyCode` and a second `ram:TaxTotalAmount` in the accounting currency (BT-111), and UBL a second `cac:TaxTotal` — BR-53
+- `Einvoicing::Validators::FR.valid_vat_rate?`, and FR validator checks for a missing exemption reason (BR-E-10, BR-AE-10, BR-IC-10, BR-G-10, BR-O-10) and for a declared accounting currency with no exchange rate (BR-53)
+
+### Fixed
+- Each VAT category's tax amount (BT-117) is now derived from its rounded taxable base (BT-116 × BT-119) instead of summing the rounded per-line VAT. The two agree on small invoices and drift apart on large ones — a 500-line invoice was off by 3 and 15 cents on two categories, which a strict BR-S-09 check rejects outright
+- The FR validator no longer rejects a counterparty's own VAT number. It now validates against the party's country (BT-40 / BT-55), with patterns for the 27 member states plus XI; every intra-Community and reverse-charge invoice used to fail on the buyer's VAT number
+- The French VAT rate list now includes the rates the "20 / 10 / 5.5 / 0" shortlist leaves out: 2.1 % (press, reimbursable medicine), the DOM rates 8.5 %, 1.75 % and 1.05 %, and the Corsican rates 13 % and 0.9 %. Comparison moved to `BigDecimal` at 4 decimals so 1.05 % and 1.75 % stop colliding
+- Exempt, reverse-charge and out-of-scope categories now bill 0 % whatever rate was passed in, so `RateApplicablePercent` and `CalculatedAmount` can no longer disagree
+- `Invoice#with` no longer returns an invoice with a nil `tax_breakdown` on Ruby 3.2. It relied on `Data#with` calling `#initialize`, which only holds from Ruby 3.3 on; on 3.2 the members are copied straight across, so the deliberate `tax_breakdown: nil` was written as-is and every total derived from it raised `NoMethodError`. Broken since 0.8.0 for `#with(lines:)`, `#with(allowances:)` and `#with(charges:)` — the gem declares `>= 3.2`
+
 ## [0.8.1] - 2026-07-25
 
 ### Fixed

data/README.md

@@ -18,7 +18,8 @@ This gem gives you a clean Ruby API to build compliant invoices, validate them a
 - 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
+- Full EN 16931 **VAT category set** (S, Z, E, AE, K, G, O) with exemption reasons (BT-120 / BT-121)
+- Validate French B2B requirements: SIREN, SIRET (Luhn), EU VAT number formats, French VAT rates including the DOM and Corsican ones
 - 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
@@ -287,6 +288,71 @@ invoice.gross_total      # BT-112                                 => 1140.00
 
 Each allowance and charge adjusts the taxable base and the VAT of its own category in the breakdown (EN 16931 BR-CO-10 to BR-CO-13). EN 16931 requires a reason or a reason code on each one (BR-33 / BR-38), and the FR validator enforces it.
 
+## VAT Categories and Exemption Reasons
+
+Every EN 16931 VAT category (BT-118) is available on a line, on a document-level
+allowance or charge, and on a hand-built breakdown entry:
+
+| Symbol | Code | Meaning |
+|---|---|---|
+| `:standard` | S | Standard rate |
+| `:zero_rated` | Z | Zero rated |
+| `:exempt` | E | Exempt from VAT |
+| `:reverse_charge` | AE | Reverse charge |
+| `:intra_community` | K | Intra-Community supply |
+| `:export` | G | Export outside the EU |
+| `:not_subject` | O | Outside the scope of VAT |
+
+`E`, `AE`, `K`, `G` and `O` must state why no VAT is charged (BR-E-10, BR-AE-10,
+BR-IC-10, BR-G-10, BR-O-10). AE, K, G and O fall back to their VATEX code; `E`
+depends on the exemption invoked, so you supply it:
+
+```ruby
+Einvoicing::LineItem.new(
+  description: "Prestation de conseil",
+  quantity:    1,
+  unit_price:  BigDecimal("2500.00"),
+  vat_rate:    0,
+  category:    :exempt,
+  exemption_reason:      "TVA non applicable, art. 293 B du CGI",
+  exemption_reason_code: Einvoicing::Tax::VATEX_FR_FRANCHISE
+)
+```
+
+A reverse-charge line needs nothing extra — the breakdown carries
+`VATEX-EU-AE` / "Reverse charge" on its own:
+
+```ruby
+Einvoicing::LineItem.new(description: "Développement", quantity: 1,
+                         unit_price: BigDecimal("10920.00"),
+                         vat_rate: 0, category: :reverse_charge)
+```
+
+Category VAT (BT-117) is computed from the category's taxable base (BT-116 ×
+BT-119), not by summing the per-line VAT — the two diverge by a cent every few
+dozen lines and BR-S-09 is checked to the cent.
+
+## VAT Accounting Currency
+
+When you invoice in one currency and account for VAT in another (BT-6 ≠ BT-5),
+BR-53 requires the VAT total restated in the accounting currency (BT-111). Give
+the gem the rate and it emits both:
+
+```ruby
+invoice = Einvoicing::Invoice.new(
+  # ... other fields ...
+  currency:          "USD",
+  tax_currency:      "EUR",
+  tax_exchange_rate: BigDecimal("0.92")
+)
+
+invoice.tax_total                  # => 1840.00 (USD)
+invoice.tax_total_in_tax_currency  # => 1692.80 (EUR)
+```
+
+The FR validator flags a declared `tax_currency` with no `tax_exchange_rate`,
+since the document could not satisfy BR-53.
+
 ## Payment Means
 
 Add IBAN, BIC, and UNCL4461 payment type code to the invoice. Both CII and UBL generators emit the appropriate elements automatically.

data/config/locales/einvoicing.en.yml

@@ -12,32 +12,36 @@ en:
         bic_invalid: "BIC format is invalid (8 or 11 characters)"
         prepaid_amount_negative: "Prepaid amount cannot be negative"
         prepaid_amount_exceeds_total: "Prepaid amount cannot exceed the invoice total"
+        tax_exchange_rate_missing: "A VAT accounting currency (BT-6) requires tax_exchange_rate so the VAT total can be restated in it (BT-111)"
       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"
+        vat_number_invalid: "Seller VAT number format is invalid for its country prefix"
       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"
+        vat_number_invalid: "Buyer VAT number format is invalid for its country prefix"
       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%%)"
+        vat_rate_invalid: "Line %{index}: VAT rate must be a known French rate (0%%, 0.9%%, 1.05%%, 1.75%%, 2.1%%, 5.5%%, 8.5%%, 10%%, 13%%, 20%%)"
       allowance:
         amount_invalid: "Allowance %{index}: amount must be non-negative"
         reason_missing: "Allowance %{index}: a reason or a reason code is required"
-        vat_rate_invalid: "Allowance %{index}: VAT rate must be a known French rate (0%%, 5.5%%, 10%%, 20%%)"
+        vat_rate_invalid: "Allowance %{index}: VAT rate must be a known French rate (0%%, 0.9%%, 1.05%%, 1.75%%, 2.1%%, 5.5%%, 8.5%%, 10%%, 13%%, 20%%)"
       charge:
         amount_invalid: "Charge %{index}: amount must be non-negative"
         reason_missing: "Charge %{index}: a reason or a reason code is required"
-        vat_rate_invalid: "Charge %{index}: VAT rate must be a known French rate (0%%, 5.5%%, 10%%, 20%%)"
+        vat_rate_invalid: "Charge %{index}: VAT rate must be a known French rate (0%%, 0.9%%, 1.05%%, 1.75%%, 2.1%%, 5.5%%, 8.5%%, 10%%, 13%%, 20%%)"
+      tax:
+        exemption_reason_missing: "VAT category %{category} requires an exemption reason (BT-120) or an exemption reason code (BT-121)"
     formats:
       unknown_format: "Unknown format: %{fmt}. Use :cii or :ubl"
       unknown_market: "Unknown market: %{market}. Use :fr"
       invalid_pdf: "pdf_data does not appear to be a valid PDF (missing %PDF- magic bytes)"
     tax:
       invalid_rate: "rate must be >= 0, got %{rate}"
+      unknown_category: "unknown VAT category %{category}"

data/config/locales/einvoicing.fr.yml

@@ -12,32 +12,36 @@ fr:
         bic_invalid: "Le format du BIC est invalide (8 ou 11 caractères)"
         prepaid_amount_negative: "Le montant déjà payé ne peut pas être négatif"
         prepaid_amount_exceeds_total: "Le montant déjà payé ne peut pas dépasser le total de la facture"
+        tax_exchange_rate_missing: "Une devise de comptabilisation de la TVA (BT-6) impose tax_exchange_rate pour exprimer le total de TVA dans cette devise (BT-111)"
       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"
+        vat_number_invalid: "Le format du numéro de TVA du vendeur est invalide pour son préfixe pays"
       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"
+        vat_number_invalid: "Le format du numéro de TVA de l'acheteur est invalide pour son préfixe pays"
       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%%)"
+        vat_rate_invalid: "Ligne %{index} : le taux de TVA doit être un taux français standard (0%%, 0,9%%, 1,05%%, 1,75%%, 2,1%%, 5,5%%, 8,5%%, 10%%, 13%%, 20%%)"
       allowance:
         amount_invalid: "Remise %{index} : le montant doit être non négatif"
         reason_missing: "Remise %{index} : un motif ou un code motif est requis"
-        vat_rate_invalid: "Remise %{index} : le taux de TVA doit être un taux français standard (0%%, 5,5%%, 10%%, 20%%)"
+        vat_rate_invalid: "Remise %{index} : le taux de TVA doit être un taux français standard (0%%, 0,9%%, 1,05%%, 1,75%%, 2,1%%, 5,5%%, 8,5%%, 10%%, 13%%, 20%%)"
       charge:
         amount_invalid: "Frais %{index} : le montant doit être non négatif"
         reason_missing: "Frais %{index} : un motif ou un code motif est requis"
-        vat_rate_invalid: "Frais %{index} : le taux de TVA doit être un taux français standard (0%%, 5,5%%, 10%%, 20%%)"
+        vat_rate_invalid: "Frais %{index} : le taux de TVA doit être un taux français standard (0%%, 0,9%%, 1,05%%, 1,75%%, 2,1%%, 5,5%%, 8,5%%, 10%%, 13%%, 20%%)"
+      tax:
+        exemption_reason_missing: "La catégorie de TVA %{category} impose un motif d'exonération (BT-120) ou un code motif (BT-121)"
     formats:
       unknown_format: "Format inconnu : %{fmt}. Utilisez :cii ou :ubl"
       unknown_market: "Marché inconnu : %{market}. Utilisez :fr"
       invalid_pdf: "pdf_data ne semble pas être un PDF valide (octets magiques %PDF- manquants)"
     tax:
       invalid_rate: "le taux doit être >= 0, valeur reçue : %{rate}"
+      unknown_category: "catégorie de TVA inconnue : %{category}"

data/lib/einvoicing/allowance_charge.rb

@@ -20,16 +20,21 @@ module Einvoicing
   #     percentage:  10
   #   )
   AllowanceCharge = Data.define(:amount, :vat_rate, :category, :reason,
-                                :reason_code, :base_amount, :percentage) do
+                                :reason_code, :base_amount, :percentage,
+                                :exemption_reason, :exemption_reason_code) do
     # @param amount [Numeric] BT-92 / BT-99 — always positive
     # @param vat_rate [Numeric] BT-96 / BT-103 — the rate the amount applies to
-    # @param category [Symbol, nil] nil for standard/zero, :reverse_charge for AE
+    # @param category [Symbol, nil] a key of Einvoicing::Tax::CATEGORY_CODES;
+    #   nil infers standard or zero-rated from the rate
     # @param reason [String, nil] BT-97 / BT-104
     # @param reason_code [String, nil] BT-98 / BT-105 (UNCL5189 / UNCL7161)
     # @param base_amount [Numeric, nil] BT-93 / BT-100
     # @param percentage [Numeric, nil] BT-94 / BT-101
+    # @param exemption_reason [String, nil] BT-120, carried into the VAT breakdown
+    # @param exemption_reason_code [String, nil] BT-121, carried into the VAT breakdown
     def initialize(amount:, vat_rate: 0.20, category: nil, reason: nil,
-                   reason_code: nil, base_amount: nil, percentage: nil)
+                   reason_code: nil, base_amount: nil, percentage: nil,
+                   exemption_reason: nil, exemption_reason_code: nil)
       super(
         amount:      BigDecimal(amount.to_s),
         vat_rate:    vat_rate,
@@ -37,19 +42,19 @@ module Einvoicing
         reason:      reason,
         reason_code: reason_code,
         base_amount: base_amount.nil? ? nil : BigDecimal(base_amount.to_s),
-        percentage:  percentage
+        percentage:  percentage,
+        exemption_reason:      exemption_reason,
+        exemption_reason_code: exemption_reason_code
       )
     end
 
     # VAT carried by this allowance/charge at its own rate.
     def vat_amount
-      (amount * BigDecimal(vat_rate.to_s)).round(2, :half_up)
+      (amount * Tax.effective_rate(rate: vat_rate, category: category)).round(2, :half_up)
     end
 
     def vat_rate_percent
-      return BigDecimal("0") if category == :reverse_charge
-
-      (BigDecimal(vat_rate.to_s) * 100).round(2)
+      (Tax.effective_rate(rate: vat_rate, category: category) * 100).round(2)
     end
 
     # CII/UBL tax category code — delegates to shared Tax logic.

data/lib/einvoicing/formats/cii.rb

@@ -154,6 +154,8 @@ module Einvoicing
       def self.header_trade_settlement(b, invoice)
         b.tag("ram:ApplicableHeaderTradeSettlement") do
           b.text("ram:PaymentReference", invoice.payment_reference || invoice.invoice_number)
+          # BT-6 precedes BT-5 in the CII sequence.
+          b.text("ram:TaxCurrencyCode", invoice.tax_currency) if invoice.tax_accounting_currency?
           b.text("ram:InvoiceCurrencyCode", invoice.currency)
 
           if invoice.payment_means_code
@@ -176,8 +178,12 @@ module Einvoicing
             b.tag("ram:ApplicableTradeTax") do
               b.text("ram:CalculatedAmount", format_amount(tax.tax_amount))
               b.text("ram:TypeCode", "VAT")
+              # BT-120 / BT-121 sit either side of BasisAmount/CategoryCode in
+              # the CII sequence — order is not ours to choose.
+              b.text("ram:ExemptionReason", tax.exemption_reason) if emit_exemption?(tax, :reason)
               b.text("ram:BasisAmount", format_amount(tax.taxable_amount))
               b.text("ram:CategoryCode", tax.category_code)
+              b.text("ram:ExemptionReasonCode", tax.exemption_reason_code) if emit_exemption?(tax, :code)
               b.text("ram:RateApplicablePercent", format_amount(tax.rate_percent))
             end
           end
@@ -200,6 +206,12 @@ module Einvoicing
             b.text("ram:TaxBasisTotalAmount", format_amount(invoice.net_total))
             b.text("ram:TaxTotalAmount",     format_amount(invoice.tax_total),
                    "currencyID" => invoice.currency)
+            # BT-111 — BR-53 requires the VAT total in the accounting currency
+            # as soon as BT-6 is present.
+            if (converted = invoice.tax_total_in_tax_currency)
+              b.text("ram:TaxTotalAmount", format_amount(converted),
+                     "currencyID" => invoice.tax_currency)
+            end
             b.text("ram:GrandTotalAmount",   format_amount(invoice.gross_total))
             b.text("ram:TotalPrepaidAmount", format_amount(invoice.prepaid_amount)) if invoice.prepaid_amount.positive?
             b.text("ram:DuePayableAmount",   format_amount(invoice.due_amount))
@@ -232,6 +244,15 @@ module Einvoicing
       end
       private_class_method :trade_allowance_charge
 
+      # BR-Z-10 and the standard category forbid BT-120/BT-121; the exempt-like
+      # categories require one of the two.
+      def self.emit_exemption?(tax, part)
+        return false unless tax.exemption_required?
+
+        part == :reason ? !tax.exemption_reason.nil? : !tax.exemption_reason_code.nil?
+      end
+      private_class_method :emit_exemption?
+
       def self.preceding_invoice_reference(b, invoice)
         b.tag("ram:InvoiceReferencedDocument") do
           b.text("ram:IssuerAssignedID", invoice.original_invoice_number)

data/lib/einvoicing/formats/ubl.rb

@@ -54,7 +54,7 @@ module Einvoicing
         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:TaxCurrencyCode", invoice.tax_currency) if invoice.tax_accounting_currency?
         b.text("cbc:BuyerReference",  invoice.payment_reference || invoice.invoice_number)
       end
       private_class_method :header
@@ -145,11 +145,25 @@ module Einvoicing
               b.tag("cac:TaxCategory") do
                 b.text("cbc:ID",      tax.category_code)
                 b.text("cbc:Percent", format_amount(tax.rate_percent))
+                if tax.exemption_required?
+                  if tax.exemption_reason_code
+                    b.text("cbc:TaxExemptionReasonCode", tax.exemption_reason_code)
+                  end
+                  b.text("cbc:TaxExemptionReason", tax.exemption_reason) if tax.exemption_reason
+                end
                 b.tag("cac:TaxScheme") { b.text("cbc:ID", "VAT") }
               end
             end
           end
         end
+
+        # BT-111 — a second TaxTotal carrying only the VAT total converted into
+        # the VAT accounting currency (BR-53).
+        return unless (converted = invoice.tax_total_in_tax_currency)
+
+        b.tag("cac:TaxTotal") do
+          b.text("cbc:TaxAmount", format_amount(converted), "currencyID" => invoice.tax_currency)
+        end
       end
       private_class_method :tax_total
 

data/lib/einvoicing/invoice.rb

@@ -24,6 +24,7 @@ module Einvoicing
     :due_date,
     :currency,
     :tax_currency,
+    :tax_exchange_rate,
     :seller,
     :buyer,
     :lines,
@@ -42,7 +43,8 @@ module Einvoicing
   ) do
     def initialize(invoice_number:, issue_date:, seller:, buyer:, lines:,
                    allowances: [], charges: [],
-                   due_date: nil, currency: "EUR", tax_currency: nil, tax_breakdown: nil,
+                   due_date: nil, currency: "EUR", tax_currency: nil,
+                   tax_exchange_rate: 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,
@@ -56,6 +58,7 @@ module Einvoicing
         due_date: due_date,
         currency: currency,
         tax_currency: tax_currency,
+        tax_exchange_rate: tax_exchange_rate.nil? ? nil : BigDecimal(tax_exchange_rate.to_s),
         seller: seller,
         buyer: buyer,
         lines: lines,
@@ -74,16 +77,23 @@ module Einvoicing
       )
     end
 
-    # Data#with feeds every current member back through the constructor, which
-    # would carry the already-computed tax_breakdown over to the copy and leave
-    # it stale. Drop it so the copy recomputes — unless the caller supplies one.
+    # Changing any of these invalidates the memoised breakdown, so the copy has
+    # to recompute it — unless the caller supplies one of their own.
     RECOMPUTES_TAX_BREAKDOWN = %i[lines allowances charges].freeze
 
+    # Rebuilt through the constructor rather than by delegating to Data#with:
+    # only Ruby >= 3.3 routes #with through #initialize. On 3.2 it copies the
+    # members straight across, so `tax_breakdown: nil` would be written as-is
+    # and every total computed from it would blow up on nil.
     def with(**kwargs)
-      return super if kwargs.key?(:tax_breakdown)
-      return super if (kwargs.keys & RECOMPUTES_TAX_BREAKDOWN).empty?
+      return self if kwargs.empty?
 
-      super(**kwargs, tax_breakdown: nil)
+      attributes = to_h.merge(kwargs)
+      if !kwargs.key?(:tax_breakdown) && kwargs.keys.intersect?(RECOMPUTES_TAX_BREAKDOWN)
+        attributes[:tax_breakdown] = nil
+      end
+
+      self.class.new(**attributes)
     end
 
     # Sum of all line net amounts, before document-level adjustments (BT-106).
@@ -126,11 +136,31 @@ module Einvoicing
       gross_total - prepaid_amount
     end
 
+    # BT-6 is set and differs from the invoice currency (BT-5), so BR-53 requires
+    # the total VAT to also be stated in the VAT accounting currency (BT-111).
+    def tax_accounting_currency?
+      !tax_currency.nil? && tax_currency != currency
+    end
+
+    # Total VAT in the VAT accounting currency (BT-111). Derived from
+    # `tax_exchange_rate` when given; nil when there is nothing to convert.
+    def tax_total_in_tax_currency
+      return nil unless tax_accounting_currency?
+      return nil if tax_exchange_rate.nil?
+
+      (tax_total * tax_exchange_rate).round(2, :half_up)
+    end
+
     private
 
     # Per-category taxable base (BT-116) and VAT (BT-117), adjusted by the
     # document-level allowances and charges that carry the same rate/category
     # (EN 16931 BR-CO-10 through BR-CO-12).
+    #
+    # BT-117 is derived from the rounded category base, not from the sum of the
+    # per-line VAT amounts: BR-S-09 (and its BR-Z/E/AE/K/G/O siblings) require
+    # BT-117 = BT-116 × BT-119. Summing rounded line VAT drifts by a cent per
+    # few dozen lines and a strict validator rejects the invoice.
     def compute_tax_breakdown(lines, allowances, charges)
       key = ->(item) { [ item.vat_rate, item.category ] }
       grouped_lines      = lines.group_by(&key)
@@ -143,18 +173,28 @@ module Einvoicing
         rate_allowances = grouped_allowances.fetch(k, [])
         rate_charges    = grouped_charges.fetch(k, [])
 
-        taxable = sum_of(rate_lines, :net_amount) -
-                  sum_of(rate_allowances, :amount) +
-                  sum_of(rate_charges, :amount)
-        tax_amt = sum_of(rate_lines, :vat_amount) -
-                  sum_of(rate_allowances, :vat_amount) +
-                  sum_of(rate_charges, :vat_amount)
+        taxable = (sum_of(rate_lines, :net_amount) -
+                   sum_of(rate_allowances, :amount) +
+                   sum_of(rate_charges, :amount)).round(2, :half_up)
+        tax_amt = (taxable * Tax.effective_rate(rate: rate, category: category)).round(2, :half_up)
+
+        reason, reason_code = exemption_for(rate_lines + rate_allowances + rate_charges)
 
-        Tax.new(rate: rate, taxable_amount: taxable.round(2, :half_up),
-                tax_amount: tax_amt.round(2, :half_up), category: category)
+        Tax.new(rate: rate, taxable_amount: taxable, tax_amount: tax_amt, category: category,
+                exemption_reason: reason, exemption_reason_code: reason_code)
       end
     end
 
+    # BT-120 / BT-121 travel with the items; the breakdown adopts the first
+    # reason found in the group. Tax falls back to the VATEX default for the
+    # category when none is supplied.
+    def exemption_for(items)
+      [
+        items.find { |i| !i.exemption_reason.nil? }&.exemption_reason,
+        items.find { |i| !i.exemption_reason_code.nil? }&.exemption_reason_code
+      ]
+    end
+
     def sum_of(items, method)
       items.sum(BigDecimal("0"), &method)
     end

data/lib/einvoicing/line_item.rb

@@ -13,15 +13,24 @@ module Einvoicing
   #     unit_price: 150.00,
   #     vat_rate: 0.20
   #   )
-  LineItem = Data.define(:description, :quantity, :unit_price, :vat_rate, :unit, :category) do
-    def initialize(description:, quantity:, unit_price:, vat_rate: 0.20, unit: "C62", category: nil)
+  LineItem = Data.define(:description, :quantity, :unit_price, :vat_rate, :unit, :category,
+                         :exemption_reason, :exemption_reason_code) do
+    # @param category [Symbol, nil] a key of Einvoicing::Tax::CATEGORY_CODES
+    #   (:standard, :zero_rated, :exempt, :reverse_charge, :intra_community,
+    #   :export, :not_subject); nil infers standard or zero-rated from the rate
+    # @param exemption_reason [String, nil] BT-120, carried into the VAT breakdown
+    # @param exemption_reason_code [String, nil] BT-121, carried into the VAT breakdown
+    def initialize(description:, quantity:, unit_price:, vat_rate: 0.20, unit: "C62",
+                   category: nil, exemption_reason: nil, exemption_reason_code: nil)
       super(
         description: description,
         quantity:    BigDecimal(quantity.to_s),
         unit_price:  BigDecimal(unit_price.to_s),
         vat_rate:    vat_rate,
         unit:        unit,
-        category:    category
+        category:    category,
+        exemption_reason:      exemption_reason,
+        exemption_reason_code: exemption_reason_code
       )
     end
 
@@ -30,9 +39,9 @@ module Einvoicing
       (quantity * unit_price).round(2, :half_up)
     end
 
-    # VAT amount for this line.
+    # VAT amount for this line. Exempt / reverse-charge categories bill 0 %.
     def vat_amount
-      (net_amount * BigDecimal(vat_rate.to_s)).round(2, :half_up)
+      (net_amount * Tax.effective_rate(rate: vat_rate, category: category)).round(2, :half_up)
     end
 
     # Gross line total (including VAT).
@@ -41,9 +50,7 @@ module Einvoicing
     end
 
     def vat_rate_percent
-      return BigDecimal("0") if category == :reverse_charge
-
-      (BigDecimal(vat_rate.to_s) * 100).round(2)
+      (Tax.effective_rate(rate: vat_rate, category: category) * 100).round(2)
     end
 
     # CII/UBL tax category code — delegates to shared Tax logic.

data/lib/einvoicing/tax.rb

@@ -4,35 +4,94 @@ require "bigdecimal"
 require "bigdecimal/util"
 
 module Einvoicing
-  # VAT breakdown entry for a single tax rate.
-  Tax = Data.define(:rate, :taxable_amount, :tax_amount, :category) do
-    # @param rate [Numeric] e.g. 0.20 for 20% VAT; 0 for zero-rated or reverse charge
-    # @param taxable_amount [Numeric] net amount subject to this rate
-    # @param tax_amount [Numeric] VAT amount for this rate
-    # @param category [Symbol, nil] nil for standard/zero, :reverse_charge for AE
-    def initialize(rate:, taxable_amount:, tax_amount:, category: nil)
-      raise ArgumentError, Einvoicing::I18n.t("tax.invalid_rate", rate: rate) if rate.to_f.negative?
+  # VAT breakdown entry (BG-23) for a single rate/category pair.
+  class Tax < Data.define(:rate, :taxable_amount, :tax_amount, :category,
+                          :exemption_reason, :exemption_reason_code)
+    # EN 16931 BT-118 — the UNCL5305 subset the standard allows.
+    CATEGORY_CODES = {
+      standard:        "S",   # Standard rate
+      zero_rated:      "Z",   # Zero rated goods
+      exempt:          "E",   # Exempt from VAT
+      reverse_charge:  "AE",  # VAT reverse charge
+      intra_community: "K",   # Intra-Community supply
+      export:          "G",   # Export outside the EU
+      not_subject:     "O"    # Services outside scope of tax
+    }.freeze
 
-      super
-    end
+    # BR-E-10, BR-AE-10, BR-IC-10, BR-G-10, BR-O-10: these categories must carry
+    # a VAT exemption reason (BT-120) or reason code (BT-121). BR-Z-10 and the
+    # standard category must NOT carry one.
+    EXEMPTION_REQUIRED_CODES = %w[E AE K G O].freeze
+
+    # Categories that net out to 0 % VAT whatever rate the caller passed in.
+    ZERO_VAT_CODES = %w[Z E AE K G O].freeze
+
+    # Defaults from the EN 16931 VATEX code list. "E" is deliberately absent:
+    # the reason depends on which exemption is invoked, so the caller supplies
+    # it (e.g. VATEX_FR_FRANCHISE for the French art. 293 B franchise).
+    DEFAULT_EXEMPTIONS = {
+      "AE" => [ "VATEX-EU-AE", "Reverse charge" ],
+      "K"  => [ "VATEX-EU-IC", "Intra-Community supply" ],
+      "G"  => [ "VATEX-EU-G",  "Export outside the EU" ],
+      "O"  => [ "VATEX-EU-O",  "Not subject to VAT" ]
+    }.freeze
+
+    # France, art. 293 B du CGI — franchise en base de TVA.
+    VATEX_FR_FRANCHISE = "VATEX-FR-FRANCHISE"
 
-    # Shared lookup used by both Tax and LineItem.
+    # Shared lookup used by Tax, LineItem and AllowanceCharge.
     def self.category_code_for(rate:, category: nil)
-      if rate.to_f == 0.0
-        category == :reverse_charge ? "AE" : "Z"
-      else
-        "S"
+      return rate.to_f.zero? ? "Z" : "S" if category.nil?
+
+      CATEGORY_CODES.fetch(category) do
+        raise ArgumentError, Einvoicing::I18n.t("tax.unknown_category", category: category.inspect)
       end
     end
 
+    # The rate actually billed once the category is taken into account: an
+    # exempt / reverse-charge / out-of-scope category charges 0 % whatever rate
+    # was passed in.
+    def self.effective_rate(rate:, category: nil)
+      return BigDecimal("0") if ZERO_VAT_CODES.include?(category_code_for(rate: rate, category: category))
+
+      BigDecimal(rate.to_s)
+    end
+
+    # @param rate [Numeric] e.g. 0.20 for 20% VAT; 0 for zero-rated or exempt
+    # @param taxable_amount [Numeric] net amount subject to this rate (BT-116)
+    # @param tax_amount [Numeric] VAT amount for this rate (BT-117)
+    # @param category [Symbol, nil] a key of CATEGORY_CODES; nil infers standard
+    #   or zero-rated from the rate
+    # @param exemption_reason [String, nil] BT-120
+    # @param exemption_reason_code [String, nil] BT-121
+    def initialize(rate:, taxable_amount:, tax_amount:, category: nil,
+                   exemption_reason: nil, exemption_reason_code: nil)
+      raise ArgumentError, Einvoicing::I18n.t("tax.invalid_rate", rate: rate) if rate.to_f.negative?
+
+      code = Tax.category_code_for(rate: rate, category: category)
+      default_code, default_reason = DEFAULT_EXEMPTIONS.fetch(code, [ nil, nil ])
+
+      super(
+        rate: rate,
+        taxable_amount: taxable_amount,
+        tax_amount: tax_amount,
+        category: category,
+        exemption_reason: exemption_reason || default_reason,
+        exemption_reason_code: exemption_reason_code || default_code
+      )
+    end
+
     def category_code
       Tax.category_code_for(rate: rate, category: category)
     end
 
-    def rate_percent
-      return BigDecimal("0") if category == :reverse_charge
+    # True when EN 16931 requires BT-120 or BT-121 on this breakdown line.
+    def exemption_required?
+      EXEMPTION_REQUIRED_CODES.include?(category_code)
+    end
 
-      (BigDecimal(rate.to_s) * 100).round(2)
+    def rate_percent
+      (Tax.effective_rate(rate: rate, category: category) * 100).round(2)
     end
   end
 end

data/lib/einvoicing/validators/fr.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "bigdecimal"
+require "bigdecimal/util"
+
 module Einvoicing
   module Validators
     # French invoice validator.
@@ -17,6 +20,40 @@ module Einvoicing
       # FR VAT: "FR" + 2 alphanumeric chars + 9-digit SIREN
       VAT_RE     = /\AFR[A-Z0-9]{2}\d{9}\z/
       INV_NUM_RE = /\A[\w\-\/]{1,35}\z/
+
+      # An invoice to a company in another member state carries that country's
+      # VAT number (BT-48), not a French one. Rejecting it broke every
+      # intra-Community and reverse-charge invoice.
+      EU_VAT_PATTERNS = {
+        "AT" => /\AATU\d{8}\z/,                 "BE" => /\ABE[01]\d{9}\z/,
+        "BG" => /\ABG\d{9,10}\z/,               "CY" => /\ACY\d{8}[A-Z]\z/,
+        "CZ" => /\ACZ\d{8,10}\z/,               "DE" => /\ADE\d{9}\z/,
+        "DK" => /\ADK\d{8}\z/,                  "EE" => /\AEE\d{9}\z/,
+        "EL" => /\AEL\d{9}\z/,                  "ES" => /\AES[A-Z0-9]\d{7}[A-Z0-9]\z/,
+        "FI" => /\AFI\d{8}\z/,                  "FR" => VAT_RE,
+        "HR" => /\AHR\d{11}\z/,                 "HU" => /\AHU\d{8}\z/,
+        "IE" => /\AIE(\d{7}[A-Z]{1,2}|\d[A-Z0-9+*]\d{5}[A-Z])\z/,
+        "IT" => /\AIT\d{11}\z/,                 "LT" => /\ALT(\d{9}|\d{12})\z/,
+        "LU" => /\ALU\d{8}\z/,                  "LV" => /\ALV\d{11}\z/,
+        "MT" => /\AMT\d{8}\z/,                  "NL" => /\ANL\d{9}B\d{2}\z/,
+        "PL" => /\APL\d{10}\z/,                 "PT" => /\APT\d{9}\z/,
+        "RO" => /\ARO\d{2,10}\z/,               "SE" => /\ASE\d{12}\z/,
+        "SI" => /\ASI\d{8}\z/,                  "SK" => /\ASK\d{10}\z/,
+        # Northern Ireland keeps an EU VAT identifier under the Windsor Framework.
+        "XI" => /\AXI(\d{9}|\d{12}|(GD|HA)\d{3})\z/
+      }.freeze
+
+      # Fallback for non-EU counterparties: 2-letter country prefix + 2 to 15
+      # alphanumeric characters. Enough to catch a typo, not a customs ruling.
+      NON_EU_VAT_RE = /\A[A-Z]{2}[A-Z0-9]{2,15}\z/
+
+      # France (metropolitan): 20 %, 10 %, 5.5 %, 2.1 %.
+      # DOM (Guadeloupe, Martinique, Réunion): 8.5 %, 2.1 %, 1.75 %, 1.05 %.
+      # Corsica: 20 %, 13 %, 10 %, 2.1 %, 0.9 %.
+      VAT_RATES = [
+        "0", "0.009", "0.0105", "0.0175", "0.021",
+        "0.055", "0.085", "0.10", "0.13", "0.20"
+      ].map { |r| BigDecimal(r) }.freeze
       # IBAN: country code (2 alpha) + 2 check digits + BBAN (11-30 alphanumeric) = 15-34 total
       IBAN_RE    = /\A[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}\z/
       # BIC: 4 alpha (institution) + 2 alpha (country) + 2 alphanumeric (location) + optional 3 alphanumeric (branch)
@@ -31,7 +68,9 @@ module Einvoicing
           *validate_party(invoice.buyer,  :buyer),
           *validate_lines(invoice.lines),
           *validate_allowances_charges(invoice.allowances, :allowance),
-          *validate_allowances_charges(invoice.charges, :charge)
+          *validate_allowances_charges(invoice.charges, :charge),
+          *validate_tax_breakdown(invoice.tax_breakdown),
+          *validate_tax_currency(invoice)
         ]
       end
 
@@ -61,11 +100,26 @@ module Einvoicing
         Base.luhn_valid?(siret.to_s)
       end
 
-      # Validate a French VAT number format.
-      # @param vat [String] e.g. "FR12123456789"
+      # Validate a VAT number against the format of the country it belongs to.
+      # The party's own country wins when known, so a French party still has to
+      # carry an FR number; otherwise the number's own prefix decides.
+      # @param vat [String] e.g. "FR12123456789", "DE811907980"
+      # @param country_code [String, nil] the party's country (BT-40 / BT-55)
+      # @return [Boolean]
+      def self.valid_vat_number?(vat, country_code: nil)
+        str = vat.to_s.gsub(/\s/, "").upcase
+        pattern = EU_VAT_PATTERNS[country_code.to_s.upcase] || EU_VAT_PATTERNS[str[0, 2]]
+        return str.match?(pattern) if pattern
+
+        str.match?(NON_EU_VAT_RE)
+      end
+
+      # A known French VAT rate, including the DOM and Corsican rates that the
+      # "20 / 10 / 5.5 / 0" shortlist leaves out.
+      # @param rate [Numeric] e.g. 0.021
       # @return [Boolean]
-      def self.valid_vat_number?(vat)
-        vat.to_s.match?(VAT_RE)
+      def self.valid_vat_rate?(rate)
+        VAT_RATES.include?(BigDecimal(rate.to_s).round(4))
       end
 
       # Validate an invoice number format (alphanumeric, dashes, slashes, 1-35 chars).
@@ -157,7 +211,8 @@ module Einvoicing
                       message: Einvoicing::I18n.t("errors.#{role}.siret_invalid") }
         end
 
-        if party.vat_number && !valid_vat_number?(party.vat_number)
+        if party.vat_number &&
+           !valid_vat_number?(party.vat_number, country_code: party.country_code)
           errors << { field: :"#{role}_vat_number", error: :vat_number_invalid,
                       message: Einvoicing::I18n.t("errors.#{role}.vat_number_invalid") }
         end
@@ -187,7 +242,7 @@ module Einvoicing
                { field: :"line_#{n}_unit_price", error: :unit_price_invalid,
                  message: Einvoicing::I18n.t("errors.line.unit_price_invalid", index: n) }
              end),
-            (unless [ 0.0, 0.055, 0.10, 0.20 ].include?(line.vat_rate.to_f.round(3))
+            (unless valid_vat_rate?(line.vat_rate)
                { field: :"line_#{n}_vat_rate", error: :vat_rate_invalid,
                  message: Einvoicing::I18n.t("errors.line.vat_rate_invalid", index: n) }
              end)
@@ -212,7 +267,7 @@ module Einvoicing
                { field: :"#{kind}_#{n}_reason", error: :reason_missing,
                  message: Einvoicing::I18n.t("errors.#{kind}.reason_missing", index: n) }
              end),
-            (unless [ 0.0, 0.055, 0.10, 0.20 ].include?(item.vat_rate.to_f.round(3))
+            (unless valid_vat_rate?(item.vat_rate)
                { field: :"#{kind}_#{n}_vat_rate", error: :vat_rate_invalid,
                  message: Einvoicing::I18n.t("errors.#{kind}.vat_rate_invalid", index: n) }
              end)
@@ -220,6 +275,35 @@ module Einvoicing
         end.compact
       end
       private_class_method :validate_allowances_charges
+
+      # BR-E-10 / BR-AE-10 / BR-IC-10 / BR-G-10 / BR-O-10: an exempt, reverse
+      # charge, intra-Community, export or out-of-scope breakdown line must
+      # state why no VAT is charged (BT-120 or BT-121).
+      def self.validate_tax_breakdown(breakdown)
+        return [] if breakdown.nil? || breakdown.empty?
+
+        breakdown.each_with_index.filter_map do |tax, idx|
+          next unless tax.exemption_required?
+          next unless tax.exemption_reason.to_s.strip.empty? &&
+                      tax.exemption_reason_code.to_s.strip.empty?
+
+          { field: :"tax_#{idx + 1}_exemption_reason", error: :exemption_reason_missing,
+            message: Einvoicing::I18n.t("errors.tax.exemption_reason_missing",
+                                        category: tax.category_code) }
+        end
+      end
+      private_class_method :validate_tax_breakdown
+
+      # BR-53: once a VAT accounting currency (BT-6) is declared, the VAT total
+      # has to be restated in it (BT-111).
+      def self.validate_tax_currency(invoice)
+        return [] unless invoice.tax_accounting_currency?
+        return [] unless invoice.tax_total_in_tax_currency.nil?
+
+        [ { field: :tax_exchange_rate, error: :tax_exchange_rate_missing,
+            message: Einvoicing::I18n.t("errors.invoice.tax_exchange_rate_missing") } ]
+      end
+      private_class_method :validate_tax_currency
     end
   end
 end

data/lib/einvoicing/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: einvoicing
 version: !ruby/object:Gem::Version
-  version: 0.8.1
+  version: 0.9.0
 platform: ruby
 authors:
 - Nathan Le Ray
@@ -215,7 +215,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.17
 specification_version: 4
 summary: EU electronic invoicing for Ruby — EN 16931, Factur-X, UBL 2.1
 test_files: []