einvoicing 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7581f06decdc863a7f8c7509a3ff696f73ca8d223579aa4695a3eee160f3e196
-  data.tar.gz: 1355d8b9034f874d7f3bd7c38315428c90477c6f987ef9642e0deca071f17587
+  metadata.gz: d547dfe66db0d1629517aae3053ac762eb5f67757f79cea0c143c1c64b8a45dc
+  data.tar.gz: 2c30feb03f0679e0a98f45f96f42df87552316a4aaa64070d1a62904c7f788b8
 SHA512:
-  metadata.gz: '0146294e7c5ea5515211eabf88d54dde12525052409b69a29aa4206df02762622a96b92bfd2c9e5afef820a50b4c34d939ba2e52baa4c217adf843b324bb90b6'
-  data.tar.gz: 19dac11dd07c6dafb9856fe0878201de2ddc259678bbddef425107413a2d4649058568d6fdae988002df71223b4165b1aee38d3692bf4f7ec390a874b61a8b45
+  metadata.gz: a1869726902c83f9942dcc7a1eaa667e9ef6acca8c142310b2b7cec2f02dd8221756db936753ae91a5c7c5512900edeeddd56bef76ad323f9164313861259fbe
+  data.tar.gz: cd041966fd406bdcefbedec61ff00af79eb67a62a1ef7cce48fd0c2098e5c55251bffe16da93906d278e1993458813cbf56cabfd6af4a75e1f66d898b4e7cb6a

data/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-07-25
+
+### Added
+- Document-level allowances (BG-20) and charges (BG-21) via `Einvoicing::AllowanceCharge`, passed to `Invoice` as `allowances:` and `charges:` — emitted as `ram:SpecifiedTradeAllowanceCharge` in CII and `cac:AllowanceCharge` in UBL, with reason (BT-97/BT-104), reason code (BT-98/BT-105), base amount (BT-93/BT-100) and percentage (BT-94/BT-101)
+- `Invoice#line_total` (BT-106), `#allowance_total` (BT-107) and `#charge_total` (BT-108); `#net_total` is now BT-109 (`line_total − allowance_total + charge_total`, BR-CO-13) and the VAT breakdown adjusts each category's taxable base and VAT accordingly (BR-CO-10 to BR-CO-12)
+- `einvoicing_allowances` / `einvoicing_charges` hooks on `Einvoicing::Invoiceable` (both default to `[]`)
+- FR validator checks on allowances and charges: non-negative amount, reason or reason code required (BR-33 / BR-38), known French VAT rate
+
+### Fixed
+- `Invoice#with` recomputes the tax breakdown when `lines`, `allowances` or `charges` change, instead of carrying the stale one over to the copy — pass `tax_breakdown:` explicitly to keep a custom breakdown
+
+## [0.7.1] - 2026-07-16
+
+### Fixed
+- CII credit notes now emit the preceding invoice number (BT-25) and optional issue date (BT-26) as a machine-readable EN 16931 BG-3 reference while retaining the legacy human-readable note when no explicit invoice note is provided
+
 ## [0.7.0] - 2026-07-14
 
 ### Added
@@ -91,5 +107,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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
+[Unreleased]: https://github.com/sxnlabs/einvoicing/compare/v0.8.0...HEAD
+[0.8.0]: https://github.com/sxnlabs/einvoicing/compare/v0.7.1...v0.8.0
+[0.7.1]: https://github.com/sxnlabs/einvoicing/compare/v0.7.0...v0.7.1
 [0.1.0]: https://github.com/sxnlabs/einvoicing/releases/tag/v0.1.0

data/README.md

@@ -254,6 +254,39 @@ end
 
 A custom validator is any module that responds to `.validate(invoice)` and returns `Array<Hash>`.
 
+## Document-Level Allowances and Charges
+
+A global discount (BG-20) or a global charge such as shipping (BG-21) is not a line item — it applies to the whole document, at a given VAT rate:
+
+```ruby
+invoice = Einvoicing::Invoice.new(
+  # ... other fields ...
+  lines: lines,
+  allowances: [
+    Einvoicing::AllowanceCharge.new(
+      amount:      BigDecimal("100.00"),   # BT-92 — always positive
+      vat_rate:    0.20,                   # BT-96 — the rate it applies to
+      reason:      "Remise commerciale",   # BT-97
+      reason_code: "95",                   # BT-98 (UNCL5189)
+      base_amount: BigDecimal("1000.00"),  # BT-93 (optional)
+      percentage:  10                      # BT-94 (optional)
+    )
+  ],
+  charges: [
+    Einvoicing::AllowanceCharge.new(amount: BigDecimal("50.00"), vat_rate: 0.20, reason: "Frais de port")
+  ]
+)
+
+invoice.line_total       # BT-106 — sum of line net amounts       => 1000.00
+invoice.allowance_total  # BT-107                                 =>  100.00
+invoice.charge_total     # BT-108                                 =>   50.00
+invoice.net_total        # BT-109 — lines − allowances + charges  =>  950.00
+invoice.tax_total        # BT-110 — VAT on the adjusted base      =>  190.00
+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.
+
 ## 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

@@ -27,6 +27,14 @@ en:
         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%%)"
+      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%%)"
+      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%%)"
     formats:
       unknown_format: "Unknown format: %{fmt}. Use :cii or :ubl"
       unknown_market: "Unknown market: %{market}. Use :fr"

data/config/locales/einvoicing.fr.yml

@@ -27,6 +27,14 @@ fr:
         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%%)"
+      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%%)"
+      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%%)"
     formats:
       unknown_format: "Format inconnu : %{fmt}. Utilisez :cii ou :ubl"
       unknown_market: "Marché inconnu : %{market}. Utilisez :fr"

data/lib/einvoicing/allowance_charge.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "bigdecimal/util"
+
+module Einvoicing
+  # A document-level allowance (BG-20) or charge (BG-21).
+  #
+  # The same shape covers both: whether it is deducted or added is decided by
+  # the array it sits in on the invoice (`allowances:` or `charges:`), so the
+  # amount itself is always expressed as a positive value.
+  #
+  # @example A 10% commercial discount on a 20% VAT base
+  #   Einvoicing::AllowanceCharge.new(
+  #     amount:      BigDecimal("100.00"),
+  #     vat_rate:    0.20,
+  #     reason:      "Remise commerciale",
+  #     reason_code: "95",
+  #     base_amount: BigDecimal("1000.00"),
+  #     percentage:  10
+  #   )
+  AllowanceCharge = Data.define(:amount, :vat_rate, :category, :reason,
+                                :reason_code, :base_amount, :percentage) 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 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
+    def initialize(amount:, vat_rate: 0.20, category: nil, reason: nil,
+                   reason_code: nil, base_amount: nil, percentage: nil)
+      super(
+        amount:      BigDecimal(amount.to_s),
+        vat_rate:    vat_rate,
+        category:    category,
+        reason:      reason,
+        reason_code: reason_code,
+        base_amount: base_amount.nil? ? nil : BigDecimal(base_amount.to_s),
+        percentage:  percentage
+      )
+    end
+
+    # VAT carried by this allowance/charge at its own rate.
+    def vat_amount
+      (amount * BigDecimal(vat_rate.to_s)).round(2, :half_up)
+    end
+
+    def vat_rate_percent
+      return BigDecimal("0") if category == :reverse_charge
+
+      (BigDecimal(vat_rate.to_s) * 100).round(2)
+    end
+
+    # CII/UBL tax category code — delegates to shared Tax logic.
+    def tax_category_code
+      Tax.category_code_for(rate: vat_rate, category: category)
+    end
+  end
+end

data/lib/einvoicing/formats/cii.rb

@@ -51,22 +51,26 @@ module Einvoicing
           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
+          if (note = document_note(invoice))
             b.tag("ram:IncludedNote") do
-              note = "Credit note for invoice #{invoice.original_invoice_number}"
-              note += " dated #{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.document_note(invoice)
+        return invoice.note unless invoice.note.to_s.strip.empty?
+        return unless invoice.document_type == :credit_note
+        return if invoice.original_invoice_number.to_s.strip.empty?
+
+        note = "Credit note for invoice #{invoice.original_invoice_number}"
+        note += " dated #{format_display_date(invoice.original_invoice_date)}" if invoice.original_invoice_date
+        note
+      end
+      private_class_method :document_note
+
       def self.supply_chain_trade_transaction(b, invoice, profile)
         b.tag("rsm:SupplyChainTradeTransaction") do
           invoice.lines.each_with_index do |line, idx|
@@ -178,6 +182,9 @@ module Einvoicing
             end
           end
 
+          invoice.allowances.each { |allowance| trade_allowance_charge(b, allowance, charge: false) }
+          invoice.charges.each    { |charge|    trade_allowance_charge(b, charge,    charge: true) }
+
           if invoice.due_date
             b.tag("ram:SpecifiedTradePaymentTerms") do
               b.tag("ram:DueDateDateTime") do
@@ -187,7 +194,9 @@ module Einvoicing
           end
 
           b.tag("ram:SpecifiedTradeSettlementHeaderMonetarySummation") do
-            b.text("ram:LineTotalAmount",    format_amount(invoice.net_total))
+            b.text("ram:LineTotalAmount",    format_amount(invoice.line_total))
+            b.text("ram:ChargeTotalAmount",  format_amount(invoice.charge_total)) if invoice.charge_total.positive?
+            b.text("ram:AllowanceTotalAmount", format_amount(invoice.allowance_total)) if invoice.allowance_total.positive?
             b.text("ram:TaxBasisTotalAmount", format_amount(invoice.net_total))
             b.text("ram:TaxTotalAmount",     format_amount(invoice.tax_total),
                    "currencyID" => invoice.currency)
@@ -195,10 +204,46 @@ module Einvoicing
             b.text("ram:TotalPrepaidAmount", format_amount(invoice.prepaid_amount)) if invoice.prepaid_amount.positive?
             b.text("ram:DuePayableAmount",   format_amount(invoice.due_amount))
           end
+
+          preceding_invoice_reference(b, invoice) if invoice.document_type == :credit_note &&
+                                                      invoice.original_invoice_number
         end
       end
       private_class_method :header_trade_settlement
 
+      # BG-20 (allowance) / BG-21 (charge) at document level. The element order
+      # follows the Factur-X EN16931 profile sequence.
+      def self.trade_allowance_charge(b, item, charge:)
+        b.tag("ram:SpecifiedTradeAllowanceCharge") do
+          b.tag("ram:ChargeIndicator") do
+            b.text("udt:Indicator", charge.to_s)
+          end
+          b.text("ram:CalculationPercent", format_amount(item.percentage)) if item.percentage
+          b.text("ram:BasisAmount", format_amount(item.base_amount)) if item.base_amount
+          b.text("ram:ActualAmount", format_amount(item.amount))
+          b.text("ram:ReasonCode", item.reason_code) if item.reason_code
+          b.text("ram:Reason", item.reason) if item.reason
+          b.tag("ram:CategoryTradeTax") do
+            b.text("ram:TypeCode", "VAT")
+            b.text("ram:CategoryCode", item.tax_category_code)
+            b.text("ram:RateApplicablePercent", format_amount(item.vat_rate_percent))
+          end
+        end
+      end
+      private_class_method :trade_allowance_charge
+
+      def self.preceding_invoice_reference(b, invoice)
+        b.tag("ram:InvoiceReferencedDocument") do
+          b.text("ram:IssuerAssignedID", invoice.original_invoice_number)
+          if invoice.original_invoice_date
+            b.tag("ram:FormattedIssueDateTime") do
+              b.text("qdt:DateTimeString", format_date(invoice.original_invoice_date), "format" => "102")
+            end
+          end
+        end
+      end
+      private_class_method :preceding_invoice_reference
+
       # 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)
@@ -206,6 +251,12 @@ module Einvoicing
       end
       private_class_method :format_date
 
+      def self.format_display_date(date)
+        d = date.is_a?(Date) ? date : Date.parse(date.to_s)
+        d.strftime("%d/%m/%Y")
+      end
+      private_class_method :format_display_date
+
       def self.format_amount(value)
         format("%.2f", value)
       end

data/lib/einvoicing/formats/ubl.rb

@@ -32,6 +32,8 @@ module Einvoicing
           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
+          invoice.allowances.each { |a| allowance_charge(b, a, invoice.currency, charge: false) }
+          invoice.charges.each    { |c| allowance_charge(b, c, invoice.currency, charge: true) }
           tax_total(b, invoice)
           monetary_total(b, invoice)
           invoice.lines.each_with_index do |line, idx|
@@ -151,14 +153,42 @@ module Einvoicing
       end
       private_class_method :tax_total
 
+      # BG-20 (allowance) / BG-21 (charge) at document level.
+      def self.allowance_charge(b, item, currency, charge:)
+        b.tag("cac:AllowanceCharge") do
+          b.text("cbc:ChargeIndicator", charge.to_s)
+          b.text("cbc:AllowanceChargeReasonCode", item.reason_code) if item.reason_code
+          b.text("cbc:AllowanceChargeReason", item.reason) if item.reason
+          b.text("cbc:MultiplierFactorNumeric", format_amount(item.percentage)) if item.percentage
+          b.text("cbc:Amount", format_amount(item.amount), "currencyID" => currency)
+          if item.base_amount
+            b.text("cbc:BaseAmount", format_amount(item.base_amount), "currencyID" => currency)
+          end
+          b.tag("cac:TaxCategory") do
+            b.text("cbc:ID",      item.tax_category_code)
+            b.text("cbc:Percent", format_amount(item.vat_rate_percent))
+            b.tag("cac:TaxScheme") { b.text("cbc:ID", "VAT") }
+          end
+        end
+      end
+      private_class_method :allowance_charge
+
       def self.monetary_total(b, invoice)
         b.tag("cac:LegalMonetaryTotal") do
-          b.text("cbc:LineExtensionAmount", format_amount(invoice.net_total),
+          b.text("cbc:LineExtensionAmount", format_amount(invoice.line_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)
+          if invoice.allowance_total.positive?
+            b.text("cbc:AllowanceTotalAmount", format_amount(invoice.allowance_total),
+                   "currencyID" => invoice.currency)
+          end
+          if invoice.charge_total.positive?
+            b.text("cbc:ChargeTotalAmount", format_amount(invoice.charge_total),
+                   "currencyID" => invoice.currency)
+          end
           if invoice.prepaid_amount.positive?
             b.text("cbc:PrepaidAmount", format_amount(invoice.prepaid_amount),
                    "currencyID" => invoice.currency)

data/lib/einvoicing/invoice.rb

@@ -27,6 +27,8 @@ module Einvoicing
     :seller,
     :buyer,
     :lines,
+    :allowances,
+    :charges,
     :tax_breakdown,
     :payment_reference,
     :note,
@@ -39,12 +41,15 @@ module Einvoicing
     :prepaid_amount
   ) do
     def initialize(invoice_number:, issue_date:, seller:, buyer:, lines:,
+                   allowances: [], charges: [],
                    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,
                    prepaid_amount: BigDecimal(0))
-      computed_breakdown = tax_breakdown || compute_tax_breakdown(lines)
+      allowances = allowances || []
+      charges = charges || []
+      computed_breakdown = tax_breakdown || compute_tax_breakdown(lines, allowances, charges)
       super(
         invoice_number: invoice_number,
         issue_date: issue_date,
@@ -54,6 +59,8 @@ module Einvoicing
         seller: seller,
         buyer: buyer,
         lines: lines,
+        allowances: allowances,
+        charges: charges,
         tax_breakdown: computed_breakdown,
         payment_reference: payment_reference,
         note: note,
@@ -67,20 +74,49 @@ module Einvoicing
       )
     end
 
-    # Sum of all line net amounts (excl. VAT).
-    def net_total
+    # 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.
+    RECOMPUTES_TAX_BREAKDOWN = %i[lines allowances charges].freeze
+
+    def with(**kwargs)
+      return super if kwargs.key?(:tax_breakdown)
+      return super if (kwargs.keys & RECOMPUTES_TAX_BREAKDOWN).empty?
+
+      super(**kwargs, tax_breakdown: nil)
+    end
+
+    # Sum of all line net amounts, before document-level adjustments (BT-106).
+    def line_total
       lines.sum(BigDecimal("0"), &:net_amount).round(2, :half_up)
     end
 
-    # Total VAT across all lines.
+    # Sum of document-level allowances (BT-107).
+    def allowance_total
+      allowances.sum(BigDecimal("0"), &:amount).round(2, :half_up)
+    end
+
+    # Sum of document-level charges (BT-108).
+    def charge_total
+      charges.sum(BigDecimal("0"), &:amount).round(2, :half_up)
+    end
+
+    # Total amount without VAT (BT-109) — BR-CO-13:
+    # line_total − allowance_total + charge_total.
+    def net_total
+      (line_total - allowance_total + charge_total).round(2, :half_up)
+    end
+
+    # Total VAT across every category (BT-110).
     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).
+    # Grand total including VAT (BT-112) — BR-CO-15: net_total + tax_total.
+    # Both operands are already rounded to 2 decimals from per-line amounts, so
+    # this introduces no double-rounding.
     def gross_total
-      lines.sum(BigDecimal("0"), &:gross_amount).round(2, :half_up)
+      (net_total + tax_total).round(2, :half_up)
     end
 
     # Amount due after deducting any retained/prepaid amount (BT-113).
@@ -92,13 +128,35 @@ module Einvoicing
 
     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)
+    # 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).
+    def compute_tax_breakdown(lines, allowances, charges)
+      key = ->(item) { [ item.vat_rate, item.category ] }
+      grouped_lines      = lines.group_by(&key)
+      grouped_allowances = allowances.group_by(&key)
+      grouped_charges    = charges.group_by(&key)
+
+      (grouped_lines.keys | grouped_allowances.keys | grouped_charges.keys).map do |(rate, category)|
+        k = [ rate, category ]
+        rate_lines      = grouped_lines.fetch(k, [])
+        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)
+
+        Tax.new(rate: rate, taxable_amount: taxable.round(2, :half_up),
+                tax_amount: tax_amt.round(2, :half_up), category: category)
       end
     end
+
+    def sum_of(items, method)
+      items.sum(BigDecimal("0"), &method)
+    end
   end
 end

data/lib/einvoicing/invoiceable.rb

@@ -70,10 +70,24 @@ module Einvoicing
         currency:       respond_to?(:currency) ? (currency || "EUR") : "EUR",
         seller:         einvoicing_seller,
         buyer:          einvoicing_buyer,
-        lines:          einvoicing_lines
+        lines:          einvoicing_lines,
+        allowances:     einvoicing_allowances,
+        charges:        einvoicing_charges
       )
     end
 
+    # Document-level allowances (BG-20). Override to return
+    # Array<Einvoicing::AllowanceCharge>.
+    def einvoicing_allowances
+      []
+    end
+
+    # Document-level charges (BG-21). Override to return
+    # Array<Einvoicing::AllowanceCharge>.
+    def einvoicing_charges
+      []
+    end
+
     # Generate CII D16B XML string.
     # @return [String]
     def to_cii_xml

data/lib/einvoicing/validators/fr.rb

@@ -29,7 +29,9 @@ module Einvoicing
           *validate_invoice_fields(invoice),
           *validate_party(invoice.seller, :seller),
           *validate_party(invoice.buyer,  :buyer),
-          *validate_lines(invoice.lines)
+          *validate_lines(invoice.lines),
+          *validate_allowances_charges(invoice.allowances, :allowance),
+          *validate_allowances_charges(invoice.charges, :charge)
         ]
       end
 
@@ -193,6 +195,31 @@ module Einvoicing
         end.compact
       end
       private_class_method :validate_lines
+
+      # Document-level allowances (BG-20) and charges (BG-21). EN 16931 BR-31 /
+      # BR-36 require an amount, BR-33 / BR-38 a reason or a reason code.
+      def self.validate_allowances_charges(items, kind)
+        return [] if items.nil? || items.empty?
+
+        items.each_with_index.flat_map do |item, idx|
+          n = idx + 1
+          [
+            (if item.amount.negative?
+               { field: :"#{kind}_#{n}_amount", error: :amount_invalid,
+                 message: Einvoicing::I18n.t("errors.#{kind}.amount_invalid", index: n) }
+             end),
+            (if item.reason.to_s.strip.empty? && item.reason_code.to_s.strip.empty?
+               { 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))
+               { field: :"#{kind}_#{n}_vat_rate", error: :vat_rate_invalid,
+                 message: Einvoicing::I18n.t("errors.#{kind}.vat_rate_invalid", index: n) }
+             end)
+          ]
+        end.compact
+      end
+      private_class_method :validate_allowances_charges
     end
   end
 end

data/lib/einvoicing/version.rb

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

data/lib/einvoicing.rb

@@ -11,6 +11,7 @@ require_relative "einvoicing/party"
 require_relative "einvoicing/siret_lookup"
 require_relative "einvoicing/fr"
 require_relative "einvoicing/line_item"
+require_relative "einvoicing/allowance_charge"
 require_relative "einvoicing/invoice"
 require_relative "einvoicing/xml_builder"
 require_relative "einvoicing/formats/cii"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: einvoicing
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Nathan Le Ray
@@ -165,6 +165,7 @@ files:
 - config/locales/einvoicing.en.yml
 - config/locales/einvoicing.fr.yml
 - lib/einvoicing.rb
+- lib/einvoicing/allowance_charge.rb
 - lib/einvoicing/data/PEPPOL-EN16931-UBL.xslt
 - lib/einvoicing/data/srgb.icc
 - lib/einvoicing/errors.rb