factur-x-builder 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac6a0f9f68bea474096e87b73b676318343d3aff63d83dbc452f742a67ebb8f8
-  data.tar.gz: 7c07d34573f36f5f16ce094ab8f84df948d288ab052e3a3c69ea1370176b1470
+  metadata.gz: 2f380d59a7b981bd4999314d3321a99dc762ac9c67709f6e543cc5632eade2c4
+  data.tar.gz: 553e1dda58b31b9804ede1acc9c75ff4ee515b1bcf152a508fb56bca7ebf2357
 SHA512:
-  metadata.gz: 3cff2a09eae0ec30028c99e5453a5149154b9b45869dfa4bd88950e4803aeb58af4455f49b154f2e1b715ffe5877e38cdff482b0e190a57bab9fc4cc9af1afdd
-  data.tar.gz: 7376dda081fe40784a55c71554215951cf7ec4d0f2a2f67e76e0370bbf0b8b927da565e1754722e2890b8591becb670ce3472d523f0040569f05a9d65e56e72e
+  metadata.gz: 54363eb24098df15598c699e48956247464bc739435af190736762e0707b77513f98e12b836db743e832b98672ef989fc225833c08ab06402b391bd10474f83d
+  data.tar.gz: 71355fc896353819a7d66da2b3d1fb078f251184858add396e3d25bc6475535c6eb7593ffeb6ec23b48fb4900e9fe8a76440b8576e10dc20173c41e556461223

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.1)
       nokogiri (~> 1.15, < 1.16)
 
 GEM

data/README.md

@@ -112,6 +112,47 @@ 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`).
+
+### 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/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.2"
 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.2
 platform: ruby
 authors:
 - Hotentic
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-10 00:00:00.000000000 Z
+date: 2026-08-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri