factur-x-builder 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 224858d0b676c38126632f450793b3ea65302d795ee6eba2f5fd34c532d7bc51
-  data.tar.gz: 67e574e617b043c7e2e433b95c17193c31dcd98df49d0d454338773a2b461acc
+  metadata.gz: aa8357e047314e65502e6f758ee4ec36cb9b58af3fbfd8b171cf0b4c69d1692a
+  data.tar.gz: f574b56e54c9e19768599b2092d4d38b3559df165289f6435d76db6d8fdc5bb8
 SHA512:
-  metadata.gz: 3a674455d7d5c036df7469dd489cd4d932912b1f0113a2aaecb48508a4f48abd4efd42174cdc525123f69e48b81193f8e052b8cbf2c72abe196f55f74d7c747d
-  data.tar.gz: d283359e423f7e88dcfd0a88cd56721812ed6be147dc9de9ce39f5cc784740115531011a43941c4174673c3b1baf137e47d91e9a88cdb266af24af783139c7e0
+  metadata.gz: 4df9ad9574aeb30e5c34d6b790e64fc7997137d0947f7370c964e8dea902bfe86e2a022f50434e0b13f2ef96acf23227f08dbc5d5a24480a1e01daa4113c3481
+  data.tar.gz: 129bbecb17198fdb472cd294d27ed702bd5ec6486e7ff85cd81c73632b9f5b023830f80ae64a80a0553dbafff112bf4a37f4a889e8bb0d721d2eafb4490f4b11

data/CHANGELOG.md

@@ -1,3 +1,31 @@
+## [0.1.5] - 2026-11-10
+
+### Added
+
+- `Party.addressed_by_email` builds a party with no registry identifier, routed by email under
+  scheme `EM` (`Codes::Scheme::EMAIL`), for invoices exchanged directly rather than deposited on an
+  accredited platform. The seller is deliberately excluded: BR-CO-9 still requires it to identify
+  itself, though it may be addressed by email while keeping its identifiers.
+- An email routing address declared under scheme `0225` is now rejected. That scheme designates a
+  French directory address, and no schematron checks the value against it, so a mislabelled address
+  would have gone out silently.
+- Conformance coverage for invoicing mode `S2` on a settled invoice, for a due date (BT-9) that
+  precedes the issue date, for an email-addressed buyer, and for a VAT exemption carried by the
+  reason code (BT-121) rather than the reason text (BT-120) — BR-E-10 accepts either.
+
+### Fixed
+
+- The BR-27 message on a negative unit price only mentioned credit notes, sending anyone trying to
+  bill a discount down the wrong path. It now names the two ways EN 16931 expresses a reduction —
+  a document allowance and a unit price discount — and keeps the credit note as the refund case.
+
+### Added
+
+- A credit note is now checked against BR-FR-CO-05: it must reference the invoice it corrects with
+  both the number (BT-25) and the issue date (BT-26). A reference missing its date failed the
+  French schematron exactly like an absent one, and neither was caught before generating.
+  `Codes::CREDIT_NOTE_TYPES` names the document types the rule applies to.
+
 ## [0.1.2] - 2026-08-15
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    factur-x-builder (0.1.3)
+    factur-x-builder (0.1.5)
       nokogiri (~> 1.15, < 1.16)
 
 GEM

data/README.md

@@ -133,6 +133,76 @@ anything is generated.
 A credit note carries **positive** amounts; the type code conveys the direction. Negative unit
 prices are rejected (`BR-27`, `BR-28`).
 
+Cancelling invoice A with credit note B changes four things and nothing else — B's own number
+(BT-1) and issue date (BT-2), the type code `381` (BT-3), and a reference to A carrying **both** its
+number and its issue date (BG-3). That reference is required by the French profile (`BR-FR-CO-05`)
+though not by EN 16931 alone, and a reference without a date fails just like a missing one. Parties,
+lines, prices, VAT breakdown and totals are copied over untouched.
+
+```ruby
+FacturX::Invoice.new(
+  number: "AV-2026-0012",
+  issued_on: Date.today,
+  type_code: FacturX::Codes::CREDIT_NOTE,
+  preceding_invoices: [
+    FacturX::ReferencedInvoice.new(number: "5-2026-0004", issued_on: Date.new(2026, 8, 4))
+  ],
+  # … everything else identical to the invoice being cancelled
+)
+```
+
+### A party with no SIREN
+
+For an invoice exchanged directly rather than deposited on an accredited platform — a private
+individual, a foreign counterpart, any buyer whose SIREN is unknown — the buyer can be addressed by
+email instead:
+
+```ruby
+buyer = FacturX::Party.addressed_by_email(
+  name: "Client particulier",
+  email: "client@example.net",
+  address: FacturX::Address.new(line_one: "12 rue des Lilas", postcode: "69001",
+                                city: "Lyon", country_code: "FR")
+)
+```
+
+No `GlobalID`, no `SpecifiedLegalOrganization`, no `SpecifiedTaxRegistration`; the routing address
+becomes `<ram:URIID schemeID="EM">client@example.net</ram:URIID>`. Name and postal address stay —
+BR-11 still requires the buyer country code.
+
+The **seller** cannot do the same: it is liable for the VAT and BR-CO-9 requires an identifier. It
+may still be *addressed* by email while keeping its SIRET, SIREN and VAT number — `addressed_by_email`
+only changes the routing; dropping the identifiers is the separate choice of not passing them.
+
+Scheme `0225` means "French directory address", so an email declared under it is mislabelled. No
+schematron notices, so the gem rejects that combination itself.
+
+### Discounts
+
+EN 16931 has no negative line. A reduction is an **allowance**, and a negative unit price is
+rejected by BR-27. Two mechanisms, both covered by the conformance suite:
+
+```ruby
+# On the whole invoice (BG-20) — reduces the taxable base
+allowances: [
+  FacturX::AllowanceCharge.allowance(amount: 159.20, basis_amount: 1592.00, percentage: 10.0,
+                                     reason: "Remise commerciale 10 %",
+                                     vat_category: "S", vat_rate: 20.0)
+]
+
+# Off a line's unit price (BT-147) — gross price, discount, net price billed
+FacturX::Line.new(name: "Option spot TV",
+                  gross_unit_price: 1290.00, unit_discount: 290.00, unit_price: 1000.00,
+                  quantity: 1, vat_rate: 20.0, net_amount: 1000.00)
+```
+
+A document allowance carries its own VAT category and rate, and is subtracted from the taxable base
+of that rate — `line_total − allowance_total + charge_total = tax_basis_total` (BR-CO-13), checked
+before generating.
+
+Line level allowances (BG-27) are not implemented: a flat discount on a line is currently expressed
+through the unit price.
+
 ### Routing address
 
 `routing_id` is the electronic address the platform delivers to (BT-34 for the seller, BT-49 for the

data/lib/factur_x/codes.rb

@@ -10,6 +10,11 @@ module FacturX
 
     DOCUMENT_TYPES = [COMMERCIAL_INVOICE, CREDIT_NOTE, SELF_BILLED_INVOICE].freeze
 
+    # The document types BR-FR-CO-05 treats as credit notes. Only 381 is
+    # emitted by this gem; the others are listed so the rule keeps matching
+    # if DOCUMENT_TYPES ever widens.
+    CREDIT_NOTE_TYPES = %w[261 381 396 502 503].freeze
+
     # Invoicing modes accepted by the French e-invoicing reform (BR-FR-08).
     BUSINESS_PROCESSES = %w[B1 S1 M1 B2 S2 M2 S3 B4 S4 M4 S5 S6 B7 S7 B8 S8 M8 B9 S9 M9].freeze
 
@@ -87,6 +92,9 @@ module FacturX
       GTIN = "0160"
       VAT = "VA"
       FISCAL = "FC"
+      # Addresses a party by email rather than by a directory identifier, for
+      # invoices that are not deposited on an accredited platform.
+      EMAIL = "EM"
     end
 
     PIECE_UNIT = "C62"

data/lib/factur_x/party.rb

@@ -52,6 +52,21 @@ module FacturX
       @routing_id_scheme = routing_id_scheme || (Codes::Scheme::ROUTING_SIRET if @routing_id)
     end
 
+    # A party with no SIREN available, addressed by email instead (scheme EM).
+    # No GlobalID, no legal organization and no tax registration are emitted,
+    # which keeps the document valid for an invoice exchanged directly rather
+    # than deposited on an accredited platform.
+    def self.addressed_by_email(name:, email:, address: nil, contact: nil, **attributes)
+      new(name: name, address: address,
+          contact: contact || Contact.new(email: email),
+          routing_id: email, routing_id_scheme: Codes::Scheme::EMAIL,
+          **attributes)
+    end
+
+    def addressed_by_email?
+      routing_id_scheme == Codes::Scheme::EMAIL
+    end
+
     def contact?
       !contact.nil? && !contact.empty?
     end

data/lib/factur_x/validation/rules.rb

@@ -91,6 +91,21 @@ module FacturX
               "notes (BT-22 with subject code #{code}, BR-FR-05) - " \
               "Note.french_legal_mentions provides the three of them")
         end
+
+        check_corrected_invoice
+      end
+
+      # BR-FR-CO-05: a credit note must say which invoice it corrects. EN 16931
+      # alone is happy without it, the French profile is not. The number and the
+      # issue date are both required - a reference carrying only the number
+      # fails the rule just as an absent one does.
+      def check_corrected_invoice
+        return unless Codes::CREDIT_NOTE_TYPES.include?(invoice.type_code)
+        return if invoice.preceding_invoices.any? { |ref| !blank?(ref.number) && !ref.issued_on.nil? }
+
+        add("a credit note must reference the invoice it corrects, with both its number and " \
+            "its issue date (BT-25 and BT-26, BR-FR-CO-05) - pass preceding_invoices: " \
+            "[ReferencedInvoice.new(number:, issued_on:)]")
       end
 
       def check_document
@@ -123,6 +138,23 @@ module FacturX
 
         check_french_identifiers(invoice.seller, "seller")
         check_french_identifiers(invoice.buyer, "buyer")
+        check_routing_address(invoice.seller, "seller")
+        check_routing_address(invoice.buyer, "buyer")
+      end
+
+      # Scheme 0225 designates a French directory address, so an email carrying
+      # it is mislabelled. Neither schematron notices - they only check that the
+      # scheme code exists - which is why this is worth catching here. Pass
+      # Party.addressed_by_email, or routing_id_scheme: Codes::Scheme::EMAIL.
+      def check_routing_address(party, role)
+        return if party.nil? || party.routing_id.nil?
+        return unless party.routing_id.to_s.include?("@")
+        return unless party.routing_id_scheme == Codes::Scheme::ROUTING_SIRET
+
+        add("#{role} routing address #{party.routing_id.inspect} is an email address but is " \
+            "declared under scheme 0225, which designates a French directory address " \
+            "(BT-34-1 / BT-49-1) - use Party.addressed_by_email or scheme " \
+            "#{Codes::Scheme::EMAIL}")
       end
 
       def check_party(party, role)
@@ -184,8 +216,12 @@ module FacturX
       # conveys the direction, not the sign of the prices.
       def check_unit_prices(line, label)
         if negative?(line.unit_price)
-          add("#{label}: unit price must not be negative (BT-146, BR-27) - a credit note uses " \
-              "type code #{Codes::CREDIT_NOTE} with positive amounts")
+          add("#{label}: unit price must not be negative (BT-146, BR-27). EN 16931 expresses a " \
+              "reduction as an allowance, never as a negative line: use " \
+              "AllowanceCharge.allowance in `allowances` for a discount on the whole invoice, " \
+              "or gross_unit_price with unit_discount on the line for a discount off the unit " \
+              "price. A refund of a whole invoice is a credit note instead (type code " \
+              "#{Codes::CREDIT_NOTE}), also with positive amounts")
         end
 
         return unless negative?(line.gross_unit_price)

data/lib/factur_x/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FacturX
-  VERSION = "0.1.3"
+  VERSION = "0.1.5"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: factur-x-builder
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.5
 platform: ruby
 authors:
 - Hotentic
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-03 00:00:00.000000000 Z
+date: 2026-11-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri