factur-x-builder 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73b17dce8190b48d61b4b2f1d521396374ef906351888926d986fb45268f0226
-  data.tar.gz: a35e0da9ed5066ef58d5ba29adf2168d86de8d16c3ec8bfee0d5503aae282de2
+  metadata.gz: 2f380d59a7b981bd4999314d3321a99dc762ac9c67709f6e543cc5632eade2c4
+  data.tar.gz: 553e1dda58b31b9804ede1acc9c75ff4ee515b1bcf152a508fb56bca7ebf2357
 SHA512:
-  metadata.gz: ca76d2866e7950a772f07b2dc4b17ea2390a1ea8f1b450b2daff5d21347662b0f32cc8bb2e33bc020c39e12d9a5a40096e33b1912a56bdd7ebc5d1a9fc50ca28
-  data.tar.gz: d5661ef43aad892fd4bb67a56714455c1b959545e13cbf4ecb6d88292e41d5bf8e1087277d0999fe4473b0e941010d60a7f34b6d0215ba5e1cc214c84f90c981
+  metadata.gz: 54363eb24098df15598c699e48956247464bc739435af190736762e0707b77513f98e12b836db743e832b98672ef989fc225833c08ab06402b391bd10474f83d
+  data.tar.gz: 71355fc896353819a7d66da2b3d1fb078f251184858add396e3d25bc6475535c6eb7593ffeb6ec23b48fb4900e9fe8a76440b8576e10dc20173c41e556461223

data/.gitignore

@@ -11,3 +11,4 @@
 .ruby-version
 .nvmrc
 .DS_Store
+*.gem

data/CHANGELOG.md

@@ -1,6 +1,36 @@
+## [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
+
+- The vendored XSD files were renamed without updating the `schemaLocation` of the files that
+  import them, which made every `FacturX.build` raise `Nokogiri::XML::SyntaxError`. A test now
+  checks that the schema compiles and that every `schemaLocation` resolves to an existing file.
+
+### Added
+
+- `Party#legal_information` (BT-33, seller additional legal information), emitted as
+  `SellerTradeParty/Description`: legal form, share capital, RCS registration, or a registered
+  office that differs from the invoicing establishment. EN 16931 allows a single postal address
+  per party, so this is the only structured place for a second one.
+
 ## [0.1.0] - 2026-08-05
 
 - Initial release
+
 ### Added
 
 - `FacturX.build` generates an EN 16931 `factur-x.xml` document from invoicing domain objects:

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,73 @@ 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
+establishment identified by the SIRET carried in `GlobalID`. There is no second slot: the element
+that would hold a registered office, `SpecifiedLegalOrganization/PostalTradeAddress`, exists in the
+`extended` XSD but the French CTC schematron forbids it (`CII-SR-225`), as it forbids
+`ShipFromTradeParty` (`CII-SR-166`).
+
+When the registered office differs from the invoicing establishment, it belongs in BT-33:
+
+```ruby
+FacturX::Party.new(
+  name: "OFFICE DE TOURISME DES MONTS FICTIFS - Établissement de Chambéry",
+  legal_information: "SARL au capital de 50 000 € - RCS Clermont-Ferrand 398 765 438 - " \
+                     "Siège social : 4 boulevard des Sources, 63240 LE MONT-FICTIF",
+  siret: "39876543800005",
+  siren: "398765438",
+  vat_number: "FR79398765438",
+  address: FacturX::Address.new(line_one: "8 rue des Entrepôts", postcode: "73000",
+                                city: "Chambéry", country_code: "FR")
+)
+```
+
+BT-33 is free text — the counterpart of `cbc:CompanyLegalForm` in UBL. Receivers display it, they do
+not parse it.
+
 ### Profiles
 
 By default the French e-invoicing rules apply on top of EN 16931: an invoicing mode (BT-23) and 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/document.rb

@@ -306,6 +306,7 @@ module FacturX
       xml["ram"].send(element_name) do
         text(xml, :GlobalID, party.global_id, scheme_attribute(party.global_id_scheme))
         text(xml, :Name, party.name)
+        text(xml, :Description, party.legal_information)
         emit_legal_organization(xml, party)
         emit_contact(xml, party)
         emit_address(xml, party.address)

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

@@ -9,18 +9,26 @@ module FacturX
   # (scheme 0009), `siren` the legal organization ID (scheme 0002), and
   # `routing_id` the electronic address (scheme 0225) used to route the
   # invoice through the PPF, defaulting to the SIRET.
+  #
+  # `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
+  # is also where a registered office that differs from the invoicing
+  # establishment belongs.
   class Party
-    attr_reader :name, :trading_name, :siret, :siren, :vat_number, :tax_id,
+    attr_reader :name, :trading_name, :legal_information, :siret, :siren, :vat_number, :tax_id,
                 :address, :contact, :global_id, :global_id_scheme,
                 :legal_id, :legal_id_scheme, :routing_id, :routing_id_scheme
 
     def initialize(name:, address: nil, contact: nil, trading_name: nil,
+                   legal_information: nil,
                    siret: nil, siren: nil, vat_number: nil, tax_id: nil,
                    global_id: nil, global_id_scheme: nil,
                    legal_id: nil, legal_id_scheme: nil,
                    routing_id: :derive_from_siret, routing_id_scheme: nil)
       @name = name
       @trading_name = trading_name
+      @legal_information = legal_information
       @address = address
       @contact = contact
       @siret = siret

data/lib/factur_x/schemas/Factur-X_1.09_EN16931_ReusableAggregateBusinessInformationEntity_100.xsd

@@ -5,8 +5,8 @@
     xmlns:udt="urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100"
     targetNamespace="urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100"
     elementFormDefault="qualified">
-  <xs:import namespace="urn:un:unece:uncefact:data:standard:QualifiedDataType:100" schemaLocation="Factur-X_1.09_EN16931_urn_un_unece_uncefact_data_standard_QualifiedDataType_100.xsd"/>
-  <xs:import namespace="urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100" schemaLocation="Factur-X_1.09_EN16931_urn_un_unece_uncefact_data_standard_UnqualifiedDataType_100.xsd"/>
+  <xs:import namespace="urn:un:unece:uncefact:data:standard:QualifiedDataType:100" schemaLocation="Factur-X_1.09_EN16931_QualifiedDataType_100.xsd"/>
+  <xs:import namespace="urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100" schemaLocation="Factur-X_1.09_EN16931_UnqualifiedDataType_100.xsd"/>
   <xs:complexType name="CreditorFinancialAccountType">
     <xs:sequence>
       <xs:element name="IBANID" type="udt:IDType" minOccurs="0"/>

data/lib/factur_x/schemas/Factur-X_EN16931.xsd

@@ -6,9 +6,9 @@
     xmlns:udt="urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100"
     targetNamespace="urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100"
     elementFormDefault="qualified">
-  <xs:import namespace="urn:un:unece:uncefact:data:standard:QualifiedDataType:100" schemaLocation="Factur-X_1.09_EN16931_urn_un_unece_uncefact_data_standard_QualifiedDataType_100.xsd"/>
-  <xs:import namespace="urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100" schemaLocation="Factur-X_1.09_EN16931_urn_un_unece_uncefact_data_standard_ReusableAggregateBusinessInformationEntity_100.xsd"/>
-  <xs:import namespace="urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100" schemaLocation="Factur-X_1.09_EN16931_urn_un_unece_uncefact_data_standard_UnqualifiedDataType_100.xsd"/>
+  <xs:import namespace="urn:un:unece:uncefact:data:standard:QualifiedDataType:100" schemaLocation="Factur-X_1.09_EN16931_QualifiedDataType_100.xsd"/>
+  <xs:import namespace="urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100" schemaLocation="Factur-X_1.09_EN16931_ReusableAggregateBusinessInformationEntity_100.xsd"/>
+  <xs:import namespace="urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100" schemaLocation="Factur-X_1.09_EN16931_UnqualifiedDataType_100.xsd"/>
   <xs:element name="CrossIndustryInvoice" type="rsm:CrossIndustryInvoiceType"/>
   <xs:complexType name="CrossIndustryInvoiceType">
     <xs:sequence>

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.0"
+  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.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Hotentic
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-09 00:00:00.000000000 Z
+date: 2026-08-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri