einvoicing 0.2.0 → 0.3.0

data/lib/einvoicing/line_item.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "bigdecimal/util"
+
+module Einvoicing
+  # A single line on an invoice.
+  #
+  # @example
+  #   Einvoicing::LineItem.new(
+  #     description: "Software consulting",
+  #     quantity: 5,
+  #     unit_price: 150.00,
+  #     vat_rate: 0.20
+  #   )
+  LineItem = Data.define(:description, :quantity, :unit_price, :vat_rate, :unit, :category) do
+    def initialize(description:, quantity:, unit_price:, vat_rate: 0.20, unit: "C62", category: nil)
+      super(
+        description: description,
+        quantity:    BigDecimal(quantity.to_s),
+        unit_price:  BigDecimal(unit_price.to_s),
+        vat_rate:    vat_rate,
+        unit:        unit,
+        category:    category
+      )
+    end
+
+    # Net line total (excluding VAT).
+    def net_amount
+      (quantity * unit_price).round(2, :half_up)
+    end
+
+    # VAT amount for this line.
+    def vat_amount
+      (net_amount * BigDecimal(vat_rate.to_s)).round(2, :half_up)
+    end
+
+    # Gross line total (including VAT).
+    def gross_amount
+      (net_amount + vat_amount).round(2, :half_up)
+    end
+
+    def vat_rate_percent
+      return BigDecimal("0") if category == :reverse_charge
+
+      (BigDecimal(vat_rate.to_s) * 100).round(2)
+    end
+
+    # CII/UBL tax category code — delegates to shared Tax logic.
+    def tax_category_code
+      Tax.category_code_for(rate: vat_rate, category: category)
+    end
+  end
+end

data/lib/einvoicing/party.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Einvoicing
+  # Represents a seller or buyer on an invoice.
+  #
+  # @example
+  #   Einvoicing::Party.new(
+  #     name: "Acme SAS",
+  #     street: "1 rue de la Paix",
+  #     city: "Paris",
+  #     postal_code: "75001",
+  #     country_code: "FR",
+  #     siren: "123456789",
+  #     vat_number: "FR12123456789"
+  #   )
+  Party = Data.define(:name, :street, :city, :postal_code, :country_code,
+                      :siren, :siret, :vat_number, :email) do
+    def initialize(name:, street: nil, city: nil, postal_code: nil,
+                   country_code: "FR", siren: nil, siret: nil,
+                   vat_number: nil, email: nil)
+      super
+    end
+
+    # The 9-digit SIREN derived from SIRET if siren not provided directly.
+    def siren_number
+      siren || (siret && siret[0, 9])
+    end
+  end
+end

data/lib/einvoicing/ppf/client.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+
+module Einvoicing
+  module PPF
+    class Client
+      SANDBOX_OAUTH_URL = "https://sandbox-oauth.piste.gouv.fr"
+      SANDBOX_API_URL   = "https://sandbox-api.piste.gouv.fr/cpro/factures"
+      PROD_OAUTH_URL    = "https://oauth.piste.gouv.fr"
+      PROD_API_URL      = "https://api.piste.gouv.fr/cpro/factures"
+
+      attr_reader :sandbox
+
+      def initialize(client_id:, client_secret:, sandbox: true)
+        @client_id        = client_id
+        @client_secret    = client_secret
+        @sandbox          = sandbox
+        @token            = nil
+        @token_expires_at = nil
+      end
+
+      # Returns current access token, refreshing if expired.
+      def access_token
+        refresh_token! if token_expired?
+        @token
+      end
+
+      # POST /v1/rechercher/structure — find structure by SIRET, returns idStructureCPP.
+      def find_structure(siret:)
+        post("/v1/rechercher/structure", { siret: siret })
+      end
+
+      # POST /v1/consulter/structure — get mandatory params (engagement, service codes).
+      def get_structure(id_structure_cpp:)
+        post("/v1/consulter/structure", { idStructureCPP: id_structure_cpp })
+      end
+
+      # POST /v1/rechercher/service/structure — list active services for a structure.
+      def list_services(id_structure_cpp:, page: 1)
+        post("/v1/rechercher/service/structure", {
+          idStructureCPP: id_structure_cpp,
+          pageResultat:   page
+        })
+      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)
+      end
+
+      private
+
+      def base_url
+        sandbox ? SANDBOX_API_URL : PROD_API_URL
+      end
+
+      def oauth_url
+        sandbox ? SANDBOX_OAUTH_URL : PROD_OAUTH_URL
+      end
+
+      def token_expired?
+        @token.nil? || @token_expires_at.nil? || Time.now >= @token_expires_at
+      end
+
+      def refresh_token!
+        uri = URI("#{oauth_url}/api/oauth/token")
+        req = Net::HTTP::Post.new(uri)
+        req.set_form_data(
+          grant_type:    "client_credentials",
+          client_id:     @client_id,
+          client_secret: @client_secret,
+          scope:         "openid"
+        )
+        res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
+        raise AuthenticationError, "OAuth token request failed: #{res.code} #{res.body}" unless res.is_a?(Net::HTTPSuccess)
+
+        data = JSON.parse(res.body)
+        @token            = data["access_token"]
+        @token_expires_at = Time.now + data.fetch("expires_in", 3600).to_i - 60
+      end
+
+      def post(path, body)
+        uri = URI("#{base_url}#{path}")
+        req = Net::HTTP::Post.new(uri)
+        req["Authorization"] = "Bearer #{access_token}"
+        req["Content-Type"]  = "application/json;charset=UTF-8"
+        req["Accept"]        = "application/json"
+        req.body = body.to_json
+        res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |h| h.request(req) }
+        handle_response(res)
+      end
+
+      def handle_response(res)
+        body = begin
+          JSON.parse(res.body)
+        rescue StandardError
+          res.body
+        end
+        case res
+        when Net::HTTPSuccess
+          body
+        when Net::HTTPUnauthorized
+          raise AuthenticationError, "Unauthorized: #{body}"
+        when Net::HTTPForbidden
+          raise AuthorizationError, "Forbidden: #{body}"
+        when Net::HTTPNotFound
+          raise NotFoundError, "Not found: #{body}"
+        else
+          raise APIError, "API error #{res.code}: #{body}"
+        end
+      end
+    end
+  end
+end

data/lib/einvoicing/ppf/errors.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Einvoicing
+  module PPF
+    Error               = Class.new(StandardError)
+    AuthenticationError = Class.new(Error)
+    AuthorizationError  = Class.new(Error)
+    NotFoundError       = Class.new(Error)
+    APIError            = Class.new(Error)
+    ValidationError     = Class.new(Error)
+  end
+end

data/lib/einvoicing/ppf/invoice_adapter.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Einvoicing
+  module PPF
+    class InvoiceAdapter
+      # Converts an Einvoicing::Invoice to a Chorus Pro SoumettreFacture payload.
+      #
+      # @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)
+        {
+          idStructureCPP:   id_structure_cpp,
+          codeService:      code_service,
+          numeroEngagement: numero_engagement,
+          cadreFacturation: {
+            codeCadreFacturation: "FACTURE_FOURNISSEUR",
+            codeServiceValideur:  nil
+          },
+          identifiantFactureFournisseur: invoice.invoice_number,
+          dateFacture:             invoice.issue_date.strftime("%Y-%m-%dT00:00:00.000+01:00"),
+          dateEcheancePaiement:    invoice.due_date&.strftime("%Y-%m-%dT00:00:00.000+01:00"),
+          montantHT:               invoice.net_total.to_f,
+          montantTVA:              invoice.tax_total.to_f,
+          montantTTC:              invoice.gross_total.to_f,
+          devise:                  invoice.currency || "EUR",
+          siretFournisseur:        invoice.seller.siret,
+          siretDestinataire:       invoice.buyer.siret,
+          typeFacture:             "FACTURE",
+          lignesPoste:             invoice.lines.map.with_index(1) { |line, i| line_to_chorus(line, i) },
+          modePaiement:            chorus_payment_mode(invoice)
+        }.compact
+      end
+
+      private_class_method def self.line_to_chorus(line, index)
+        {
+          numeroLigne:    index,
+          designation:    line.description,
+          quantite:       line.quantity.to_f,
+          unite:          "U",
+          prixUnitaireHT: line.unit_price.to_f,
+          montantHT:      line.net_amount.to_f,
+          tauxTVA:        (line.vat_rate * 100).to_f,
+          montantTVA:     (line.net_amount * line.vat_rate).to_f.round(2)
+        }
+      end
+
+      private_class_method def self.chorus_payment_mode(invoice)
+        return nil unless invoice.respond_to?(:payment_means_code) && invoice.payment_means_code
+
+        code_map = { 30 => "VIREMENT", 42 => "VIREMENT", 58 => "VIREMENT" }
+        mode     = code_map[invoice.payment_means_code] || "VIREMENT"
+        result   = { modePaiement: mode }
+        result[:iban] = invoice.iban if invoice.respond_to?(:iban) && invoice.iban
+        result[:bic]  = invoice.bic  if invoice.respond_to?(:bic)  && invoice.bic
+        result
+      end
+    end
+  end
+end

data/lib/einvoicing/ppf/submitter.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Einvoicing
+  module PPF
+    class Submitter
+      def initialize(client)
+        @client = client
+      end
+
+      # Submit an invoice to Chorus Pro / PPF.
+      # Returns the submission result hash from the API.
+      #
+      # @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)
+        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
+        )
+
+        @client.submit_invoice(payload)
+      end
+    end
+  end
+end

data/lib/einvoicing/ppf.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "ppf/errors"
+require_relative "ppf/client"
+require_relative "ppf/invoice_adapter"
+require_relative "ppf/submitter"

data/lib/einvoicing/rails/concern.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Redirect: Invoiceable has moved to lib/einvoicing/invoiceable.rb.
+require_relative "../invoiceable"

data/lib/einvoicing/rails/engine.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Einvoicing
+  module Rails
+    # Rails engine entry point. Automatically extends ActiveRecord::Base with
+    # the Invoiceable concern when loaded inside a Rails application.
+    class Engine < ::Rails::Engine
+      isolate_namespace Einvoicing
+
+      initializer "einvoicing.i18n" do
+        config.i18n.load_path += Dir[File.expand_path("../../../config/locales/*.yml", __dir__)]
+      end
+
+      initializer "einvoicing.active_record" do
+        ActiveSupport.on_load(:active_record) do
+          # Models opt-in via `include Einvoicing::Invoiceable`
+        end
+      end
+    end
+  end
+end

data/lib/einvoicing/tax.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "bigdecimal/util"
+
+module Einvoicing
+  # VAT breakdown entry for a single tax rate.
+  Tax = Data.define(:rate, :taxable_amount, :tax_amount, :category) do
+    # @param rate [Numeric] e.g. 0.20 for 20% VAT; 0 for zero-rated or reverse charge
+    # @param taxable_amount [Numeric] net amount subject to this rate
+    # @param tax_amount [Numeric] VAT amount for this rate
+    # @param category [Symbol, nil] nil for standard/zero, :reverse_charge for AE
+    def initialize(rate:, taxable_amount:, tax_amount:, category: nil)
+      raise ArgumentError, "rate must be >= 0, got #{rate}" if rate.to_f.negative?
+
+      super
+    end
+
+    # Shared lookup used by both Tax and LineItem.
+    def self.category_code_for(rate:, category: nil)
+      if rate.to_f == 0.0
+        category == :reverse_charge ? "AE" : "Z"
+      else
+        "S"
+      end
+    end
+
+    def category_code
+      Tax.category_code_for(rate: rate, category: category)
+    end
+
+    def rate_percent
+      return BigDecimal("0") if category == :reverse_charge
+
+      (BigDecimal(rate.to_s) * 100).round(2)
+    end
+  end
+end

data/lib/einvoicing/validators/base.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Einvoicing
+  module Validators
+    # Shared validation helpers for country-specific validators.
+    # Each validator exposes a `.validate(invoice)` class method that returns
+    # an array of error hashes (empty = valid).
+    # Each error hash has the shape:
+    #   { field: Symbol, error: Symbol, message: String }
+    module Base
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # Validate an invoice and raise if any errors exist.
+        def validate!(invoice)
+          errors = validate(invoice)
+          raise ValidationError, errors.map { |e| e[:message] }.join("; ") unless errors.empty?
+
+          true
+        end
+      end
+
+      # Luhn algorithm for SIREN (9 digits) and SIRET (14 digits).
+      # Returns true if the number passes the Luhn check.
+      def self.luhn_valid?(number_string)
+        digits = number_string.chars.map(&:to_i)
+        sum = 0
+        digits.reverse.each_with_index do |d, i|
+          d = i.odd? ? d * 2 : d
+          d -= 9 if d > 9
+          sum += d
+        end
+        (sum % 10).zero?
+      end
+
+      # Presence check — returns an error hash or nil.
+      def self.presence(value, field, message, error: :blank)
+        { field: field, error: error, message: message } if value.nil? || value.to_s.strip.empty?
+      end
+
+      # Format check via regex — returns an error hash or nil.
+      def self.format(value, field, pattern, message)
+        { field: field, error: :invalid, message: message } unless value.to_s.match?(pattern)
+      end
+    end
+
+    # Raised when `.validate!` finds errors.
+    class ValidationError < StandardError; end
+  end
+end

data/lib/einvoicing/validators/fr.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module Einvoicing
+  module Validators
+    # French invoice validator.
+    # Checks SIREN, SIRET, TVA (VAT) number format and Luhn checksum, plus
+    # mandatory invoice fields for French B2B compliance.
+    #
+    # @example
+    #   errors = Einvoicing::Validators::FR.validate(invoice)
+    #   errors.empty? # => true if valid
+    #
+    #   Einvoicing::Validators::FR.validate!(invoice) # raises on failure
+    module FR
+      SIREN_RE   = /\A\d{9}\z/
+      SIRET_RE   = /\A\d{14}\z/
+      # FR VAT: "FR" + 2 alphanumeric chars + 9-digit SIREN
+      VAT_RE     = /\AFR[A-Z0-9]{2}\d{9}\z/
+      INV_NUM_RE = /\A[\w\-\/]{1,35}\z/
+      # IBAN: country code (2 alpha) + 2 check digits + BBAN (11-30 alphanumeric) = 15-34 total
+      IBAN_RE    = /\A[A-Z]{2}[0-9]{2}[A-Z0-9]{11,30}\z/
+      # BIC: 4 alpha (institution) + 2 alpha (country) + 2 alphanumeric (location) + optional 3 alphanumeric (branch)
+      BIC_RE     = /\A[A-Z]{4}[A-Z]{2}[A-Z0-9]{2}([A-Z0-9]{3})?\z/
+
+      # @param invoice [Einvoicing::Invoice]
+      # @return [Array<Hash>] list of error hashes ({ field:, error:, message: }); empty if valid
+      def self.validate(invoice)
+        [
+          *validate_invoice_fields(invoice),
+          *validate_party(invoice.seller, :seller),
+          *validate_party(invoice.buyer,  :buyer),
+          *validate_lines(invoice.lines)
+        ]
+      end
+
+      # @raise [Einvoicing::Validators::ValidationError] if invalid
+      def self.validate!(invoice)
+        errors = validate(invoice)
+        raise ValidationError, errors.map { |e| e[:message] }.join("; ") unless errors.empty?
+
+        true
+      end
+
+      # Validate a single SIREN number.
+      # @param siren [String]
+      # @return [Boolean]
+      def self.valid_siren?(siren)
+        return false unless siren.to_s.match?(SIREN_RE)
+
+        Base.luhn_valid?(siren.to_s)
+      end
+
+      # Validate a single SIRET number.
+      # @param siret [String]
+      # @return [Boolean]
+      def self.valid_siret?(siret)
+        return false unless siret.to_s.match?(SIRET_RE)
+
+        Base.luhn_valid?(siret.to_s)
+      end
+
+      # Validate a French VAT number format.
+      # @param vat [String] e.g. "FR12123456789"
+      # @return [Boolean]
+      def self.valid_vat_number?(vat)
+        vat.to_s.match?(VAT_RE)
+      end
+
+      # Validate an invoice number format (alphanumeric, dashes, slashes, 1-35 chars).
+      # @param number [String]
+      # @return [Boolean]
+      def self.valid_invoice_number?(number)
+        number.to_s.match?(INV_NUM_RE)
+      end
+
+      # Validate an IBAN (ISO 13616 format + mod-97 checksum).
+      # @param iban [String]
+      # @return [Boolean]
+      def self.valid_iban?(iban)
+        str = iban.to_s.gsub(/\s/, "").upcase
+        return false unless str.match?(IBAN_RE)
+
+        # Move first 4 chars to end, replace each letter with its numeric value (A=10..Z=35)
+        rearranged = str[4..] + str[0..3]
+        numeric = rearranged.chars.map { |c| c =~ /[A-Z]/ ? (c.ord - 55).to_s : c }.join
+        numeric.to_i % 97 == 1
+      end
+
+      # Validate a BIC (ISO 9362) — 8 or 11 chars.
+      # @param bic [String]
+      # @return [Boolean]
+      def self.valid_bic?(bic)
+        bic.to_s.match?(BIC_RE)
+      end
+
+      # -- Private helpers ---------------------------------------------------
+
+      def self.validate_invoice_fields(invoice)
+        errors = [
+          Base.presence(invoice.invoice_number, :invoice_number,
+                        Einvoicing::I18n.t("errors.invoice.number_missing"),
+                        error: :number_missing),
+          Base.presence(invoice.issue_date, :issue_date,
+                        Einvoicing::I18n.t("errors.invoice.issue_date_missing"),
+                        error: :issue_date_missing),
+          Base.presence(invoice.currency, :currency,
+                        Einvoicing::I18n.t("errors.invoice.currency_missing"),
+                        error: :currency_missing)
+        ].compact
+        unless valid_invoice_number?(invoice.invoice_number.to_s)
+          errors << { field: :invoice_number, error: :number_invalid,
+                      message: Einvoicing::I18n.t("errors.invoice.number_invalid") }
+        end
+        if invoice.document_type == :credit_note &&
+           invoice.original_invoice_number.to_s.strip.empty?
+          errors << { field: :original_invoice_number, error: :original_invoice_number_missing,
+                      message: Einvoicing::I18n.t("errors.invoice.original_invoice_number_missing") }
+        end
+        if invoice.iban && !valid_iban?(invoice.iban)
+          errors << { field: :iban, error: :iban_invalid,
+                      message: Einvoicing::I18n.t("errors.invoice.iban_invalid") }
+        end
+        if invoice.bic && !valid_bic?(invoice.bic)
+          errors << { field: :bic, error: :bic_invalid,
+                      message: Einvoicing::I18n.t("errors.invoice.bic_invalid") }
+        end
+        errors
+      end
+      private_class_method :validate_invoice_fields
+
+      def self.validate_party(party, role)
+        name_field = :"#{role}_name"
+        errors = [
+          Base.presence(party&.name, name_field,
+                        Einvoicing::I18n.t("errors.#{role}.name_missing"),
+                        error: :name_missing)
+        ].compact
+        return errors if party.nil?
+
+        siren = party.siren_number
+        if siren && !valid_siren?(siren)
+          errors << { field: :"#{role}_siren", error: :siren_invalid,
+                      message: Einvoicing::I18n.t("errors.#{role}.siren_invalid") }
+        end
+
+        if party.siret && !valid_siret?(party.siret)
+          errors << { field: :"#{role}_siret", error: :siret_invalid,
+                      message: Einvoicing::I18n.t("errors.#{role}.siret_invalid") }
+        end
+
+        if party.vat_number && !valid_vat_number?(party.vat_number)
+          errors << { field: :"#{role}_vat_number", error: :vat_number_invalid,
+                      message: Einvoicing::I18n.t("errors.#{role}.vat_number_invalid") }
+        end
+
+        errors
+      end
+      private_class_method :validate_party
+
+      def self.validate_lines(lines)
+        if lines.nil? || lines.empty?
+          return [{ field: :lines, error: :lines_empty,
+                    message: Einvoicing::I18n.t("errors.invoice.lines_empty") }]
+        end
+
+        lines.each_with_index.flat_map do |line, idx|
+          n = idx + 1
+          [
+            (if line.description.to_s.strip.empty?
+               { field: :"line_#{n}_description", error: :description_missing,
+                 message: Einvoicing::I18n.t("errors.line.description_missing", index: n) }
+             end),
+            (unless line.quantity.to_f.positive?
+               { field: :"line_#{n}_quantity", error: :quantity_invalid,
+                 message: Einvoicing::I18n.t("errors.line.quantity_invalid", index: n) }
+             end),
+            (if line.unit_price.to_f.negative?
+               { field: :"line_#{n}_unit_price", error: :unit_price_invalid,
+                 message: Einvoicing::I18n.t("errors.line.unit_price_invalid", index: n) }
+             end),
+            (unless [0.0, 0.055, 0.10, 0.20].include?(line.vat_rate.to_f.round(3))
+               { field: :"line_#{n}_vat_rate", error: :vat_rate_invalid,
+                 message: Einvoicing::I18n.t("errors.line.vat_rate_invalid", index: n) }
+             end)
+          ]
+        end.compact
+      end
+      private_class_method :validate_lines
+    end
+  end
+end

data/lib/einvoicing/version.rb

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