factur-x-builder 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac6a0f9f68bea474096e87b73b676318343d3aff63d83dbc452f742a67ebb8f8
-  data.tar.gz: 7c07d34573f36f5f16ce094ab8f84df948d288ab052e3a3c69ea1370176b1470
+  metadata.gz: 224858d0b676c38126632f450793b3ea65302d795ee6eba2f5fd34c532d7bc51
+  data.tar.gz: 67e574e617b043c7e2e433b95c17193c31dcd98df49d0d454338773a2b461acc
 SHA512:
-  metadata.gz: 3cff2a09eae0ec30028c99e5453a5149154b9b45869dfa4bd88950e4803aeb58af4455f49b154f2e1b715ffe5877e38cdff482b0e190a57bab9fc4cc9af1afdd
-  data.tar.gz: 7376dda081fe40784a55c71554215951cf7ec4d0f2a2f67e76e0370bbf0b8b927da565e1754722e2890b8591becb670ce3472d523f0040569f05a9d65e56e72e
+  metadata.gz: 3a674455d7d5c036df7469dd489cd4d932912b1f0113a2aaecb48508a4f48abd4efd42174cdc525123f69e48b81193f8e052b8cbf2c72abe196f55f74d7c747d
+  data.tar.gz: d283359e423f7e88dcfd0a88cd56721812ed6be147dc9de9ce39f5cc784740115531011a43941c4174673c3b1baf137e47d91e9a88cdb266af24af783139c7e0

data/.rubocop.yml

@@ -27,3 +27,6 @@ Style/StringLiteralsInInterpolation:
 
 Layout/LineLength:
   Max: 120
+
+Gemspec/RequireMFA:
+  Enabled: false

data/CHANGELOG.md

@@ -1,4 +1,18 @@
-## [Unreleased]
+## [0.1.2] - 2026-08-15
+
+### Added
+
+- `Codes::PaymentMeansType::ALL` lists the 84 UNTDID 4461 codes EN 16931 permits for BT-81, and a
+  payment means outside that list is now rejected instead of producing XML the schematron refuses.
+  More codes are named (`PAYMENT_TO_BANK_ACCOUNT`, `CREDIT_CARD`, `ONLINE_PAYMENT_SERVICE`,
+  `MUTUALLY_DEFINED`, …); the constants are a convenience, not the permitted set.
+- BT-87 is checked against BR-51, which caps a card number at 10 characters — the first 6 and last
+  4 digits PCI DSS allows to be displayed. Masking the middle with asterisks overflows that limit
+  and was previously emitted, producing XML the schematron refuses.
+- Unit prices are checked against BR-27 and BR-28: a negative BT-146 or BT-148 is rejected with a
+  message pointing at credit notes, which use type code 381 with positive amounts.
+
+## [0.1.1] - 2026-08-10
 
 ### Fixed
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    factur-x-builder (0.1.0)
+    factur-x-builder (0.1.3)
       nokogiri (~> 1.15, < 1.16)
 
 GEM
@@ -12,6 +12,8 @@ GEM
     language_server-protocol (3.17.0.6)
     lint_roller (1.1.0)
     minitest (5.26.1)
+    nokogiri (1.15.7-arm64-darwin)
+      racc (~> 1.4)
     nokogiri (1.15.7-x86_64-darwin)
       racc (~> 1.4)
     parallel (1.28.0)
@@ -43,6 +45,7 @@ GEM
     unicode-emoji (4.2.0)
 
 PLATFORMS
+  arm64-darwin-25
   x86_64-darwin-21
 
 DEPENDENCIES

data/README.md

@@ -112,6 +112,64 @@ FacturX.violations(invoice)  # => ["...", "..."]
 FacturX.valid?(invoice)      # => false
 ```
 
+### Payment states
+
+An issued invoice is immutable. Payments received **after** issuance are not written back into it —
+they are reported to the platform as lifecycle statuses (`Encaissée`), a separate message flow that
+this gem does not produce and is not meant to.
+
+What the invoice records is the state **at issuance**, through BT-113 and BT-115:
+
+| Situation | `prepaid` (BT-113) | `due_payable` (BT-115) | `type_code` |
+|---|---|---|---|
+| Nothing paid | omitted | grand total | `380` |
+| Paid before issuance | grand total | `0.00` | `380` |
+| Deposit collected before issuance | the deposit | the balance | `380` |
+| Cancellation | omitted | amount to refund | `381` + `preceding_invoices` |
+
+`BR-CO-16` ties them together — `BT-115 = BT-112 − BT-113 + BT-114` — and is checked before
+anything is generated.
+
+A credit note carries **positive** amounts; the type code conveys the direction. Negative unit
+prices are rejected (`BR-27`, `BR-28`).
+
+### Routing address
+
+`routing_id` is the electronic address the platform delivers to (BT-34 for the seller, BT-49 for the
+buyer). It defaults to the SIRET, and its scheme identifier — mandatory under BR-62 and BR-63 — is
+filled in as `0225`.
+
+That code designates the addressing of the French reform itself, not a particular identifier, so it
+stays `0225` whatever the directory registered: SIREN, SIRET, `SIREN_SIRET`, or
+`SIREN_SIRET_CODE_ROUTAGE` for an address finer than the establishment. The value is opaque to the
+gem — forwarded verbatim, never parsed — and every shape is covered by the conformance suite.
+
+```ruby
+FacturX::Party.new(name: "…", siret: "39876543800005",
+                   routing_id: "398765438_39876543800005_COMPTA")
+# => <ram:URIID schemeID="0225">398765438_39876543800005_COMPTA</ram:URIID>
+```
+
+### Payment instructions are optional
+
+`payment_means` maps to BG-16 *Payment instructions*, which both schematrons accept as absent. It
+states how the seller **expects** to be paid — it is not a record of the buyer's choice, since the
+invoice precedes the payment. Several means may be declared at once.
+
+Once a means is declared, the rules apply: a credit transfer (`30`, `58`) requires an account
+identifier (BR-61, BR-CO-27), and the code must belong to UNTDID 4461 —
+`Codes::PaymentMeansType::ALL` holds the 84 permitted values, checked against the code database the
+official schematron uses. The named constants (`CREDIT_TRANSFER`, `BANK_CARD`, …) cover the common
+cases; any other code can be passed as a plain string.
+
+A platform may narrow the list further. Chorus Pro accepts only `30`, `42`, `48`, `49`, `58`, `59`
+and `97` for the public sector — a restriction no schematron encodes, so the gem cannot catch it.
+
+Nothing downstream contradicts it. The `Encaissée` lifecycle status reports only the invoice number,
+the payment date and the amount collected per VAT rate — the means actually used is not among the
+data transmitted, so a buyer paying by cheque against an invoice quoting a transfer raises no
+compliance issue.
+
 ### One address per party
 
 EN 16931 gives each party exactly one `PostalTradeAddress`, and it must be the address of the

data/lib/factur_x/codes.rb

@@ -37,15 +37,34 @@ module FacturX
       REQUIRING_EXEMPTION_REASON = [EXEMPT, REVERSE_CHARGE, INTRA_COMMUNITY, EXPORT].freeze
     end
 
+    # NOTE: Chorus Pro only accepts 30, 42, 48, 49, 58, 59 and 97
     module PaymentMeansType
+      NOT_DEFINED = "1"
       CASH = "10"
       CHEQUE = "20"
       CREDIT_TRANSFER = "30"
+      PAYMENT_TO_BANK_ACCOUNT = "42"
+      # The instrument, whatever the channel: a card read on a physical
+      # terminal and a card entered on a web page are both 48.
       BANK_CARD = "48"
       DIRECT_DEBIT = "49"
+      CREDIT_CARD = "54"
+      DEBIT_CARD = "55"
+      STANDING_AGREEMENT = "57"
       SEPA_CREDIT_TRANSFER = "58"
       SEPA_DIRECT_DEBIT = "59"
-      NOT_DEFINED = "1"
+      # The service is itself the instrument - a wallet or a provider that
+      # collects in its own name. A card payment through a payment page is
+      # still BANK_CARD, not this.
+      ONLINE_PAYMENT_SERVICE = "68"
+      CLEARING_BETWEEN_PARTNERS = "97"
+      MUTUALLY_DEFINED = "ZZZ"
+
+      # The complete UNTDID 4461 subset of the EN 16931 code list, as published
+      # in the Factur-X code database used by the official schematron.
+      ALL = (
+        (1..70).to_a + (74..78).to_a + (91..98).to_a
+      ).map(&:to_s).push("ZZZ").freeze
 
       REQUIRING_CREDITOR_ACCOUNT = [CREDIT_TRANSFER, SEPA_CREDIT_TRANSFER].freeze
       REQUIRING_MANDATE = [DIRECT_DEBIT, SEPA_DIRECT_DEBIT].freeze

data/lib/factur_x/line.rb

@@ -7,7 +7,7 @@ module FacturX
   class Line
     attr_reader :number, :name, :description, :seller_item_id, :buyer_item_id,
                 :global_id, :global_id_scheme, :unit_price, :gross_unit_price,
-                :unit_discount, :quantity, :unit_code, :vat_category, :vat_rate,
+                :unit_discount, :quantity, :unit_code, :vat_category, :vat_rate, :vat_amount,
                 :net_amount, :note, :origin_country, :period_start, :period_end,
                 :order_line_id, :accounting_reference
 
@@ -15,7 +15,7 @@ module FacturX
                    number: nil, description: nil, seller_item_id: nil, buyer_item_id: nil,
                    global_id: nil, global_id_scheme: nil, gross_unit_price: nil,
                    unit_discount: nil, unit_code: Codes::PIECE_UNIT,
-                   vat_category: Codes::VatCategory::STANDARD, vat_rate: nil,
+                   vat_category: Codes::VatCategory::STANDARD, vat_rate: nil, vat_amount: nil,
                    note: nil, origin_country: nil, period_start: nil, period_end: nil,
                    order_line_id: nil, accounting_reference: nil)
       @number = number
@@ -32,6 +32,7 @@ module FacturX
       @unit_code = unit_code
       @vat_category = vat_category
       @vat_rate = vat_rate
+      @vat_amount = vat_amount
       @net_amount = net_amount
       @note = note
       @origin_country = origin_country
@@ -72,8 +73,8 @@ module FacturX
         global_id: global_id, global_id_scheme: global_id_scheme,
         unit_price: unit_price, gross_unit_price: gross_unit_price,
         unit_discount: unit_discount, quantity: quantity, unit_code: unit_code,
-        vat_category: vat_category, vat_rate: vat_rate, net_amount: net_amount,
-        note: note, origin_country: origin_country,
+        vat_category: vat_category, vat_rate: vat_rate, vat_amount: vat_amount,
+        net_amount: net_amount, note: note, origin_country: origin_country,
         period_start: period_start, period_end: period_end,
         order_line_id: order_line_id, accounting_reference: accounting_reference
       }

data/lib/factur_x/party.rb

@@ -10,6 +10,12 @@ module FacturX
   # `routing_id` the electronic address (scheme 0225) used to route the
   # invoice through the PPF, defaulting to the SIRET.
   #
+  # Scheme 0225 designates the addressing of the French reform itself, not a
+  # particular identifier, so it holds whatever shape the directory registered:
+  # SIREN, SIRET, SIREN_SIRET, or SIREN_SIRET_CODE_ROUTAGE for an address finer
+  # than the establishment. The value is opaque here - it is forwarded verbatim,
+  # never parsed - so a new directory shape needs no change to this gem.
+  #
   # `legal_information` is BT-33, the seller's additional legal information:
   # legal form, share capital, RCS registration, and any other statement the
   # printed invoice must carry. A party holds a single postal address, so this

data/lib/factur_x/validation/rules.rb

@@ -22,6 +22,8 @@ module FacturX
 
       ROUNDING_TOLERANCE = BigDecimal("0.01")
 
+      CARD_NUMBER_MAX_LENGTH = 10
+
       PROFILES = %i[en16931 fr_ctc].freeze
 
       # BR-FR-05: every invoice must carry these three statements.
@@ -174,7 +176,25 @@ module FacturX
           add("#{label}: name is required (BT-153)") if blank?(line.name)
           add("#{label}: unit code is required (BT-130)") if blank?(line.unit_code)
           check_vat_category(line.vat_category, line.vat_rate, label)
+          check_unit_prices(line, label)
+        end
+      end
+
+      # A credit note carries positive amounts: the document type code (BT-3)
+      # 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")
         end
+
+        return unless negative?(line.gross_unit_price)
+
+        add("#{label}: gross unit price must not be negative (BT-148, BR-28)")
+      end
+
+      def negative?(value)
+        !value.nil? && Formatting.decimal(value).negative?
       end
 
       def check_vat_category(category, rate, label)
@@ -274,6 +294,9 @@ module FacturX
         [item.vat_category, Formatting.decimal(item.vat_rate || 0)]
       end
 
+      # Payment instructions (BG-16) are optional: an invoice with no payment
+      # means at all satisfies both schematrons. What is checked here applies
+      # only once a payment means has been declared.
       def check_payment
         invoice.payment_means.each do |means|
           if blank?(means.type_code)
@@ -281,18 +304,39 @@ module FacturX
             next
           end
 
+          unless Codes::PaymentMeansType::ALL.include?(means.type_code.to_s)
+            add("payment means #{means.type_code.inspect} is not a UNTDID 4461 code (BT-81)")
+            next
+          end
+
           if Codes::PaymentMeansType::REQUIRING_CREDITOR_ACCOUNT.include?(means.type_code) &&
              !means.creditor_account?
             add("payment means #{means.type_code} (credit transfer) requires a creditor " \
-                "account identifier (BR-61)")
+                "account identifier - an IBAN or a proprietary account id (BR-61, BR-CO-27)")
           end
 
           if means.iban && !means.iban.to_s.delete(" ").match?(IBAN_PATTERN)
             add("payment IBAN #{means.iban.inspect} is not a well-formed IBAN")
           end
+
+          check_card_number(means)
         end
       end
 
+      # BR-51 caps BT-87 at 10 characters, which is what PCI DSS allows to be
+      # displayed: the first 6 and last 4 digits. Masking the middle with
+      # asterisks overflows that limit and is rejected.
+      def check_card_number(means)
+        return if means.card_id.nil?
+
+        length = means.card_id.to_s.strip.length
+        return if length <= CARD_NUMBER_MAX_LENGTH
+
+        add("payment card number is #{length} characters; an invoice must never carry a full " \
+            "card number (BT-87, BR-51). Keep at most #{CARD_NUMBER_MAX_LENGTH} characters - " \
+            "the first 6 and last 4 digits, without masking characters")
+      end
+
       def check_totals
         totals = invoice.totals
         if totals.nil?

data/lib/factur_x/version.rb

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

metadata

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