einvoicing 0.6.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24047fa12d3baaca75ebea76468a98ee023e5716bdee7dfa90f7f532e13ab5d1
-  data.tar.gz: 934ca40e5c588c9593d39b839e13eabd413b34b3f36f56d5481e99dddb5a1b69
+  metadata.gz: a27d36b05ee79942e8828c53055b9b3088bec50a526d1277dff05aa7b447e405
+  data.tar.gz: bf8f072d6f8a3e15b5f74c06117f3e8def1fd1eb81173dcb2edcaf1bced32f02
 SHA512:
-  metadata.gz: 54accf1d18eb7e32a35aba28d1c5c9f362eb1de5f19025b89c784724285ce59535394c603b9272a678a8bda7b1b13ae6f6a4dfca949528a303cf41a070681c43
-  data.tar.gz: 2eebc04105e663f581c83c6e81523aceba000188f0fc4b00c15138094d7659008bf59ce98b7afa5f867d875e307b806dbbea5281824d7d8c3eb11659976f7e86
+  metadata.gz: 235d066a6f7d45ed40d10cbd871a560008a33e3bd5c2791e66bafd5f5649a62da0c84f31b7df854e06bf78e8c9514f948f23c88a5043f27bc8ed7f36b46ca11e
+  data.tar.gz: 357abed47d361906c413171f66ba6d66963b275e4149d141d94886822dca14958ca75d0e164ed3d523b293482454ad3baee49347702aec29b8e00bb97d78099f

data/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [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
+- `prepaid_amount` on `Invoice` (BT-113 `TotalPrepaidAmount` in CII / `PrepaidAmount` in UBL) so a retained/prepaid amount (e.g. retenue de garantie) reduces the amount due (BR-CO-16: `DuePayableAmount = GrandTotal − TotalPrepaidAmount`) without affecting the taxable base or VAT totals
+- CII profile support: `:chorus_pro` and `:en16931` selectable per invoice
+
+### Fixed
+- CII `schemeID` SIRET correctly emitted for Chorus Pro
+- `PaymentMeans` is now required when generating CII/UBL
+
+## [0.6.0] - 2026-03-14
+
+### Changed
+- Codebase aligned on `rubocop-rails-omakase` standards
+- Locale strings extracted into `config/locales/*.yml` (English + French)
+
 ## [0.5.0] - 2026-03-14
 
 ### Fixed
@@ -73,5 +96,6 @@ 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.7.1...HEAD
+[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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SXN Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -55,7 +55,7 @@ seller = Einvoicing::Party.new(
 
 buyer = Einvoicing::Party.new(
   name:         "Gecobat",
-  street:       "12 rue du Bâtiment",
+  street:       "12 Construction Street",
   city:         "Paris",
   postal_code:  "75001",
   country_code: "FR",
@@ -65,13 +65,13 @@ buyer = Einvoicing::Party.new(
 
 lines = [
   Einvoicing::LineItem.new(
-    description: "Développement backend — API REST (forfait)",
+    description: "Backend development — REST API (fixed fee)",
     quantity:    1,
     unit_price:  BigDecimal("2500.00"),
     vat_rate:    0.20
   ),
   Einvoicing::LineItem.new(
-    description: "Intégration Factur-X",
+    description: "Factur-X integration",
     quantity:    5,
     unit_price:  BigDecimal("350.00"),
     vat_rate:    0.20
@@ -86,7 +86,7 @@ invoice = Einvoicing::Invoice.new(
   buyer:              buyer,
   lines:              lines,
   payment_reference:  "FAC-2024-0042",
-  note:               "30 jours net",
+  note:               "Net 30",
   payment_means_code: 30,
   iban:               "FR7630006000011234567890189",
   bic:                "BNPAFRPP"
@@ -175,6 +175,20 @@ ubl = Einvoicing::Formats::UBL.generate(invoice)
 
 Produces a UBL 2.1 `Invoice` document with Peppol BIS Billing 3.0 customization ID.
 
+## Chorus Pro / PPF (France)
+
+When submitting to Chorus Pro (French B2G portal), generate CII XML with the `:chorus_pro` profile:
+
+```ruby
+xml = Einvoicing.xml(invoice, format: :cii, profile: :chorus_pro)
+```
+
+Chorus Pro-specific requirements:
+- `schemeID` for SIRET identifiers must be `"SIRET"` (not the ISO 6523 code `"0002"`)
+- `SpecifiedTradeSettlementPaymentMeans` is mandatory — set `payment_means_code:` on the invoice (30 = credit transfer)
+- Invoice ID (`invoice_number`) must not exceed 20 characters
+- Use `einvoicing-connect` for the actual API submission
+
 ## Rails Integration
 
 Include `Einvoicing::Invoiceable` in your ActiveRecord model and implement three methods:

data/config/locales/einvoicing.en.yml

@@ -10,6 +10,8 @@ en:
         original_invoice_number_missing: "Original invoice number is required for credit notes"
         iban_invalid: "IBAN format or checksum is invalid"
         bic_invalid: "BIC format is invalid (8 or 11 characters)"
+        prepaid_amount_negative: "Prepaid amount cannot be negative"
+        prepaid_amount_exceeds_total: "Prepaid amount cannot exceed the invoice total"
       seller:
         name_missing: "Seller name is required"
         siren_invalid: "Seller SIREN must be 9 digits (Luhn check failed)"

data/config/locales/einvoicing.fr.yml

@@ -10,6 +10,8 @@ fr:
         original_invoice_number_missing: "Le numéro de facture d'origine est requis pour les avoirs"
         iban_invalid: "Le format ou la somme de contrôle de l'IBAN est invalide"
         bic_invalid: "Le format du BIC est invalide (8 ou 11 caractères)"
+        prepaid_amount_negative: "Le montant déjà payé ne peut pas être négatif"
+        prepaid_amount_exceeds_total: "Le montant déjà payé ne peut pas dépasser le total de la facture"
       seller:
         name_missing: "Le nom du vendeur est requis"
         siren_invalid: "Le SIREN du vendeur doit comporter 9 chiffres (vérification Luhn échouée)"

data/lib/einvoicing/formats/cii.rb

@@ -16,7 +16,7 @@ module Einvoicing
       UDT_NS = "urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100"
       QDT_NS = "urn:un:unece:uncefact:data:standard:QualifiedDataType:100"
 
-      def self.generate(invoice)
+      def self.generate(invoice, profile: :en16931)
         b = XMLBuilder.new
         b.tag(
           "rsm:CrossIndustryInvoice",
@@ -28,7 +28,7 @@ module Einvoicing
         ) do
           exchanged_document_context(b)
           exchanged_document(b, invoice)
-          supply_chain_trade_transaction(b, invoice)
+          supply_chain_trade_transaction(b, invoice, profile)
         end
         b.to_xml
       end
@@ -51,28 +51,32 @@ 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 = "Avoir sur facture #{invoice.original_invoice_number}"
-              note += " du #{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.supply_chain_trade_transaction(b, invoice)
+      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|
             trade_line_item(b, line, idx + 1, invoice.currency)
           end
-          header_trade_agreement(b, invoice)
+          header_trade_agreement(b, invoice, profile)
           b.tag("ram:ApplicableHeaderTradeDelivery")
           header_trade_settlement(b, invoice)
         end
@@ -109,21 +113,23 @@ module Einvoicing
       end
       private_class_method :trade_line_item
 
-      def self.header_trade_agreement(b, invoice)
+      def self.header_trade_agreement(b, invoice, profile)
         b.tag("ram:ApplicableHeaderTradeAgreement") do
           # BuyerReference must be first in the sequence (EN 16931 BR-10 / XSD order).
           b.text("ram:BuyerReference", invoice.payment_reference || "")
-          b.tag("ram:SellerTradeParty") { party_xml(b, invoice.seller) }
-          b.tag("ram:BuyerTradeParty")  { party_xml(b, invoice.buyer) }
+          b.tag("ram:SellerTradeParty") { party_xml(b, invoice.seller, profile) }
+          b.tag("ram:BuyerTradeParty")  { party_xml(b, invoice.buyer, profile) }
         end
       end
       private_class_method :header_trade_agreement
 
-      def self.party_xml(b, party)
+      def self.party_xml(b, party, profile)
         b.text("ram:Name", party.name)
-        if party.siren_number
+        legal_id = party.siret || party.siren
+        if legal_id
           b.tag("ram:SpecifiedLegalOrganization") do
-            b.text("ram:ID", party.siren_number, "schemeID" => "0002")
+            scheme = (profile == :chorus_pro && party.siret) ? "SIRET" : "0002"
+            b.text("ram:ID", legal_id, "schemeID" => scheme)
           end
         end
         b.tag("ram:PostalTradeAddress") do
@@ -190,12 +196,28 @@ module Einvoicing
             b.text("ram:TaxTotalAmount",     format_amount(invoice.tax_total),
                    "currencyID" => invoice.currency)
             b.text("ram:GrandTotalAmount",   format_amount(invoice.gross_total))
+            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
 
+      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)
@@ -203,6 +225,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

@@ -159,6 +159,10 @@ module Einvoicing
                  "currencyID" => invoice.currency)
           b.text("cbc:TaxInclusiveAmount", format_amount(invoice.gross_total),
                  "currencyID" => invoice.currency)
+          if invoice.prepaid_amount.positive?
+            b.text("cbc:PrepaidAmount", format_amount(invoice.prepaid_amount),
+                   "currencyID" => invoice.currency)
+          end
           b.text("cbc:PayableAmount", format_amount(invoice.due_amount),
                  "currencyID" => invoice.currency)
         end

data/lib/einvoicing/invoice.rb

@@ -35,13 +35,15 @@ module Einvoicing
     :bic,
     :document_type,
     :original_invoice_number,
-    :original_invoice_date
+    :original_invoice_date,
+    :prepaid_amount
   ) do
     def initialize(invoice_number:, issue_date:, seller:, buyer:, lines:,
                    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)
+                   document_type: :invoice, original_invoice_number: nil, original_invoice_date: nil,
+                   prepaid_amount: BigDecimal(0))
       computed_breakdown = tax_breakdown || compute_tax_breakdown(lines)
       super(
         invoice_number: invoice_number,
@@ -60,7 +62,8 @@ module Einvoicing
         bic: bic,
         document_type: document_type,
         original_invoice_number: original_invoice_number,
-        original_invoice_date: original_invoice_date
+        original_invoice_date: original_invoice_date,
+        prepaid_amount: prepaid_amount.nil? ? BigDecimal(0) : BigDecimal(prepaid_amount.to_s)
       )
     end
 
@@ -80,9 +83,11 @@ module Einvoicing
       lines.sum(BigDecimal("0"), &:gross_amount).round(2, :half_up)
     end
 
-    # Amount due (same as gross_total; override for prepayments).
+    # Amount due after deducting any retained/prepaid amount (BT-113).
+    # VAT remains due on the full gross_total — only the payable balance is reduced
+    # (EN 16931 BR-CO-16: DuePayableAmount = GrandTotal − TotalPrepaidAmount).
     def due_amount
-      gross_total
+      gross_total - prepaid_amount
     end
 
     private

data/lib/einvoicing/ppf/client.rb

@@ -46,9 +46,9 @@ module Einvoicing
       end
 
       # POST /v1/soumettre/factures — submit an invoice.
-      # facture_hash: Hash matching the Chorus Pro invoice schema.
-      def submit_invoice(facture_hash)
-        post("/v1/soumettre/factures", facture_hash)
+      # invoice_hash: Hash matching the Chorus Pro invoice schema.
+      def submit_invoice(invoice_hash)
+        post("/v1/soumettre/factures", invoice_hash)
       end
 
       private

data/lib/einvoicing/ppf/invoice_adapter.rb

@@ -8,12 +8,12 @@ module Einvoicing
       # @param invoice [Einvoicing::Invoice]
       # @param id_structure_cpp [Integer] from find_structure()
       # @param code_service [String, nil] from list_services() — optional
-      # @param numero_engagement [String, nil] buyer PO/engagement number — optional for B2B
-      def self.to_chorus_payload(invoice, id_structure_cpp:, code_service: nil, numero_engagement: nil)
+      # @param engagement_number [String, nil] buyer PO/engagement number — optional for B2B
+      def self.to_chorus_payload(invoice, id_structure_cpp:, code_service: nil, engagement_number: nil)
         {
           idStructureCPP:   id_structure_cpp,
           codeService:      code_service,
-          numeroEngagement: numero_engagement,
+          numeroEngagement: engagement_number,
           cadreFacturation: {
             codeCadreFacturation: "FACTURE_FOURNISSEUR",
             codeServiceValideur:  nil

data/lib/einvoicing/ppf/submitter.rb

@@ -12,17 +12,17 @@ module Einvoicing
       #
       # @param invoice [Einvoicing::Invoice]
       # @param code_service [String, nil] optional service code from list_services
-      # @param numero_engagement [String, nil] optional engagement number
-      def submit(invoice, code_service: nil, numero_engagement: nil)
+      # @param engagement_number [String, nil] optional engagement number
+      def submit(invoice, code_service: nil, engagement_number: nil)
         structure    = @client.find_structure(siret: invoice.buyer.siret)
         id_structure = structure["idStructureCPP"] || structure.dig("parametres", "idStructureCPP")
         raise ValidationError, "Buyer SIRET #{invoice.buyer.siret} not found in Chorus Pro" unless id_structure
 
         payload = InvoiceAdapter.to_chorus_payload(
           invoice,
-          id_structure_cpp:  id_structure,
-          code_service:      code_service,
-          numero_engagement: numero_engagement
+          id_structure_cpp: id_structure,
+          code_service:     code_service,
+          engagement_number: engagement_number
         )
 
         @client.submit_invoice(payload)

data/lib/einvoicing/validators/fr.rb

@@ -124,6 +124,13 @@ module Einvoicing
           errors << { field: :bic, error: :bic_invalid,
                       message: Einvoicing::I18n.t("errors.invoice.bic_invalid") }
         end
+        if invoice.prepaid_amount.negative?
+          errors << { field: :prepaid_amount, error: :prepaid_amount_negative,
+                      message: Einvoicing::I18n.t("errors.invoice.prepaid_amount_negative") }
+        elsif invoice.prepaid_amount > invoice.gross_total
+          errors << { field: :prepaid_amount, error: :prepaid_amount_exceeds_total,
+                      message: Einvoicing::I18n.t("errors.invoice.prepaid_amount_exceeds_total") }
+        end
         errors
       end
       private_class_method :validate_invoice_fields

data/lib/einvoicing/version.rb

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

data/lib/einvoicing.rb

@@ -56,10 +56,11 @@ module Einvoicing
   # Generate XML from an invoice.
   # @param invoice [Einvoicing::Invoice]
   # @param format [Symbol] :cii (default, Factur-X) or :ubl (Peppol BIS 3.0)
+  # @param profile [Symbol] :en16931 (default) or :chorus_pro (French B2G portal)
   # @return [String] XML document
-  def self.xml(invoice, format: :cii)
+  def self.xml(invoice, format: :cii, profile: :en16931)
     case format
-    when :cii then Formats::CII.generate(invoice)
+    when :cii then Formats::CII.generate(invoice, profile: profile)
     when :ubl then Formats::UBL.generate(invoice)
     else raise ArgumentError, Einvoicing::I18n.t("formats.unknown_format", fmt: format.inspect)
     end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: einvoicing
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.1
 platform: ruby
 authors:
 - Nathan Le Ray
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-14 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hexapdf
@@ -161,6 +160,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
+- LICENSE
 - README.md
 - config/locales/einvoicing.en.yml
 - config/locales/einvoicing.fr.yml
@@ -200,7 +200,6 @@ metadata:
   source_code_uri: https://github.com/sxnlabs/einvoicing
   changelog_uri: https://github.com/sxnlabs/einvoicing/blob/master/CHANGELOG.md
   documentation_uri: https://www.sxnlabs.com/en/gems/einvoicing/
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -215,8 +214,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
-signing_key:
+rubygems_version: 4.0.16
 specification_version: 4
 summary: EU electronic invoicing for Ruby — EN 16931, Factur-X, UBL 2.1
 test_files: []