factpulse 1.0.0

data/lib/factpulse/configuration.rb

@@ -0,0 +1,308 @@
+=begin
+#API REST FactPulse
+
+# API REST pour la facturation électronique en France : Factur-X, AFNOR PDP/PA, signatures électroniques.  ## 🎯 Fonctionnalités principales  ### 📄 Génération de factures Factur-X - **Formats** : XML seul ou PDF/A-3 avec XML embarqué - **Profils** : MINIMUM, BASIC, EN16931, EXTENDED - **Normes** : EN 16931 (directive UE 2014/55), ISO 19005-3 (PDF/A-3), CII (UN/CEFACT) - **🆕 Format simplifié** : Génération à partir de SIRET + auto-enrichissement (API Chorus Pro + Recherche Entreprises)  ### ✅ Validation et conformité - **Validation XML** : Schematron (45 à 210+ règles selon profil) - **Validation PDF** : PDF/A-3, métadonnées XMP Factur-X, signatures électroniques - **VeraPDF** : Validation stricte PDF/A (146+ règles ISO 19005-3) - **Traitement asynchrone** : Support Celery pour validations lourdes (VeraPDF)  ### 📡 Intégration AFNOR PDP/PA (XP Z12-013) - **Soumission de flux** : Envoi de factures vers Plateformes de Dématérialisation Partenaires - **Recherche de flux** : Consultation des factures soumises - **Téléchargement** : Récupération des PDF/A-3 avec XML - **Directory Service** : Recherche d'entreprises (SIREN/SIRET) - **Multi-client** : Support de plusieurs configs PDP par utilisateur (stored credentials ou zero-storage)  ### ✍️ Signature électronique PDF - **Standards** : PAdES-B-B, PAdES-B-T (horodatage RFC 3161), PAdES-B-LT (archivage long terme) - **Niveaux eIDAS** : SES (auto-signé), AdES (CA commerciale), QES (PSCO) - **Validation** : Vérification intégrité cryptographique et certificats - **Génération de certificats** : Certificats X.509 auto-signés pour tests  ### 🔄 Traitement asynchrone - **Celery** : Génération, validation et signature asynchrones - **Polling** : Suivi d'état via `/taches/{id_tache}/statut` - **Pas de timeout** : Idéal pour gros fichiers ou validations lourdes  ## 🔒 Authentification  Toutes les requêtes nécessitent un **token JWT** dans le header Authorization : ``` Authorization: Bearer YOUR_JWT_TOKEN ```  ### Comment obtenir un token JWT ?  #### 🔑 Méthode 1 : API `/api/token/` (Recommandée)  **URL :** `https://www.factpulse.fr/api/token/`  Cette méthode est **recommandée** pour l'intégration dans vos applications et workflows CI/CD.  **Prérequis :** Avoir défini un mot de passe sur votre compte  **Pour les utilisateurs inscrits via email/password :** - Vous avez déjà un mot de passe, utilisez-le directement  **Pour les utilisateurs inscrits via OAuth (Google/GitHub) :** - Vous devez d'abord définir un mot de passe sur : https://www.factpulse.fr/accounts/password/set/ - Une fois le mot de passe créé, vous pourrez utiliser l'API  **Exemple de requête :** ```bash curl -X POST https://www.factpulse.fr/api/token/ \\   -H \"Content-Type: application/json\" \\   -d '{     \"username\": \"votre_email@example.com\",     \"password\": \"votre_mot_de_passe\"   }' ```  **Paramètre optionnel `client_uid` :**  Pour sélectionner les credentials d'un client spécifique (PA/PDP, Chorus Pro, certificats de signature), ajoutez `client_uid` :  ```bash curl -X POST https://www.factpulse.fr/api/token/ \\   -H \"Content-Type: application/json\" \\   -d '{     \"username\": \"votre_email@example.com\",     \"password\": \"votre_mot_de_passe\",     \"client_uid\": \"550e8400-e29b-41d4-a716-446655440000\"   }' ```  Le `client_uid` sera inclus dans le JWT et permettra à l'API d'utiliser automatiquement : - Les credentials AFNOR/PDP configurés pour ce client - Les credentials Chorus Pro configurés pour ce client - Les certificats de signature électronique configurés pour ce client  **Réponse :** ```json {   \"access\": \"eyJ0eXAiOiJKV1QiLCJhbGc...\",  // Token d'accès (validité: 30 min)   \"refresh\": \"eyJ0eXAiOiJKV1QiLCJhbGc...\"  // Token de rafraîchissement (validité: 7 jours) } ```  **Avantages :** - ✅ Automatisation complète (CI/CD, scripts) - ✅ Gestion programmatique des tokens - ✅ Support du refresh token pour renouveler automatiquement l'accès - ✅ Intégration facile dans n'importe quel langage/outil  #### 🖥️ Méthode 2 : Génération via Dashboard (Alternative)  **URL :** https://www.factpulse.fr/dashboard/  Cette méthode convient pour des tests rapides ou une utilisation occasionnelle via l'interface graphique.  **Fonctionnement :** - Connectez-vous au dashboard - Utilisez les boutons \"Generate Test Token\" ou \"Generate Production Token\" - Fonctionne pour **tous** les utilisateurs (OAuth et email/password), sans nécessiter de mot de passe  **Types de tokens :** - **Token Test** : Validité 24h, quota 1000 appels/jour (gratuit) - **Token Production** : Validité 7 jours, quota selon votre forfait  **Avantages :** - ✅ Rapide pour tester l'API - ✅ Aucun mot de passe requis - ✅ Interface visuelle simple  **Inconvénients :** - ❌ Nécessite une action manuelle - ❌ Pas de refresh token - ❌ Moins adapté pour l'automatisation  ### 📚 Documentation complète  Pour plus d'informations sur l'authentification et l'utilisation de l'API : https://www.factpulse.fr/documentation-api/     
+
+The version of the OpenAPI document: 1.0.0
+
+Generated by: https://openapi-generator.tech
+Generator version: 7.18.0-SNAPSHOT
+
+=end
+
+module FactPulse
+  class Configuration
+    # Defines url scheme
+    attr_accessor :scheme
+
+    # Defines url host
+    attr_accessor :host
+
+    # Defines url base path
+    attr_accessor :base_path
+
+    # Define server configuration index
+    attr_accessor :server_index
+
+    # Define server operation configuration index
+    attr_accessor :server_operation_index
+
+    # Default server variables
+    attr_accessor :server_variables
+
+    # Default server operation variables
+    attr_accessor :server_operation_variables
+
+    # Defines API keys used with API Key authentications.
+    #
+    # @return [Hash] key: parameter name, value: parameter value (API key)
+    #
+    # @example parameter name is "api_key", API key is "xxx" (e.g. "api_key=xxx" in query string)
+    #   config.api_key['api_key'] = 'xxx'
+    attr_accessor :api_key
+
+    # Defines API key prefixes used with API Key authentications.
+    #
+    # @return [Hash] key: parameter name, value: API key prefix
+    #
+    # @example parameter name is "Authorization", API key prefix is "Token" (e.g. "Authorization: Token xxx" in headers)
+    #   config.api_key_prefix['api_key'] = 'Token'
+    attr_accessor :api_key_prefix
+
+    # Defines the username used with HTTP basic authentication.
+    #
+    # @return [String]
+    attr_accessor :username
+
+    # Defines the password used with HTTP basic authentication.
+    #
+    # @return [String]
+    attr_accessor :password
+
+    # Defines the access token (Bearer) used with OAuth2.
+    attr_accessor :access_token
+
+    # Defines a Proc used to fetch or refresh access tokens (Bearer) used with OAuth2.
+    # Overrides the access_token if set
+    # @return [Proc]
+    attr_accessor :access_token_getter
+
+    # Set this to return data as binary instead of downloading a temp file. When enabled (set to true)
+    # HTTP responses with return type `File` will be returned as a stream of binary data.
+    # Default to false.
+    attr_accessor :return_binary_data
+
+    # Set this to enable/disable debugging. When enabled (set to true), HTTP request/response
+    # details will be logged with `logger.debug` (see the `logger` attribute).
+    # Default to false.
+    #
+    # @return [true, false]
+    attr_accessor :debugging
+
+    # Set this to ignore operation servers for the API client. This is useful when you need to
+    # send requests to a different server than the one specified in the OpenAPI document.
+    # Will default to the base url defined in the spec but can be overridden by setting
+    # `scheme`, `host`, `base_path` directly.
+    # Default to false.
+    # @return [true, false]
+    attr_accessor :ignore_operation_servers
+
+    # Defines the logger used for debugging.
+    # Default to `Rails.logger` (when in Rails) or logging to STDOUT.
+    #
+    # @return [#debug]
+    attr_accessor :logger
+
+    # Defines the temporary folder to store downloaded files
+    # (for API endpoints that have file response).
+    # Default to use `Tempfile`.
+    #
+    # @return [String]
+    attr_accessor :temp_folder_path
+
+    # The time limit for HTTP request in seconds.
+    # Default to 0 (never times out).
+    attr_accessor :timeout
+
+    # Set this to false to skip client side validation in the operation.
+    # Default to true.
+    # @return [true, false]
+    attr_accessor :client_side_validation
+
+    ### TLS/SSL setting
+    # Set this to false to skip verifying SSL certificate when calling API from https server.
+    # Default to true.
+    #
+    # @note Do NOT set it to false in production code, otherwise you would face multiple types of cryptographic attacks.
+    #
+    # @return [true, false]
+    attr_accessor :verify_ssl
+
+    ### TLS/SSL setting
+    # Set this to false to skip verifying SSL host name
+    # Default to true.
+    #
+    # @note Do NOT set it to false in production code, otherwise you would face multiple types of cryptographic attacks.
+    #
+    # @return [true, false]
+    attr_accessor :verify_ssl_host
+
+    ### TLS/SSL setting
+    # Set this to customize the certificate file to verify the peer.
+    #
+    # @return [String] the path to the certificate file
+    #
+    # @see The `cainfo` option of Typhoeus, `--cert` option of libcurl. Related source code:
+    # https://github.com/typhoeus/typhoeus/blob/master/lib/typhoeus/easy_factory.rb#L145
+    attr_accessor :ssl_ca_cert
+
+    ### TLS/SSL setting
+    # Client certificate file (for client certificate)
+    attr_accessor :cert_file
+
+    ### TLS/SSL setting
+    # Client private key file (for client certificate)
+    attr_accessor :key_file
+
+    # Set this to customize parameters encoding of array parameter with multi collectionFormat.
+    # Default to nil.
+    #
+    # @see The params_encoding option of Ethon. Related source code:
+    # https://github.com/typhoeus/ethon/blob/master/lib/ethon/easy/queryable.rb#L96
+    attr_accessor :params_encoding
+
+
+    attr_accessor :inject_format
+
+    attr_accessor :force_ending_format
+
+    def initialize
+      @scheme = 'http'
+      @host = 'localhost'
+      @base_path = ''
+      @server_index = nil
+      @server_operation_index = {}
+      @server_variables = {}
+      @server_operation_variables = {}
+      @api_key = {}
+      @api_key_prefix = {}
+      @client_side_validation = true
+      @verify_ssl = true
+      @verify_ssl_host = true
+      @cert_file = nil
+      @key_file = nil
+      @timeout = 0
+      @params_encoding = nil
+      @debugging = false
+      @ignore_operation_servers = false
+      @inject_format = false
+      @force_ending_format = false
+      @logger = defined?(Rails) ? Rails.logger : Logger.new(STDOUT)
+
+      yield(self) if block_given?
+    end
+
+    # The default Configuration object.
+    def self.default
+      @@default ||= Configuration.new
+    end
+
+    def configure
+      yield(self) if block_given?
+    end
+
+    def scheme=(scheme)
+      # remove :// from scheme
+      @scheme = scheme.sub(/:\/\//, '')
+    end
+
+    def host=(host)
+      # remove http(s):// and anything after a slash
+      @host = host.sub(/https?:\/\//, '').split('/').first
+    end
+
+    def base_path=(base_path)
+      # Add leading and trailing slashes to base_path
+      @base_path = "/#{base_path}".gsub(/\/+/, '/')
+      @base_path = '' if @base_path == '/'
+    end
+
+    # Returns base URL for specified operation based on server settings
+    def base_url(operation = nil)
+      return "#{scheme}://#{[host, base_path].join('/').gsub(/\/+/, '/')}".sub(/\/+\z/, '') if ignore_operation_servers
+      if operation_server_settings.key?(operation) then
+        index = server_operation_index.fetch(operation, server_index)
+        server_url(index.nil? ? 0 : index, server_operation_variables.fetch(operation, server_variables), operation_server_settings[operation])
+      else
+        server_index.nil? ? "#{scheme}://#{[host, base_path].join('/').gsub(/\/+/, '/')}".sub(/\/+\z/, '') : server_url(server_index, server_variables, nil)
+      end
+    end
+
+    # Gets API key (with prefix if set).
+    # @param [String] param_name the parameter name of API key auth
+    def api_key_with_prefix(param_name, param_alias = nil)
+      key = @api_key[param_name]
+      key = @api_key.fetch(param_alias, key) unless param_alias.nil?
+      if @api_key_prefix[param_name]
+        "#{@api_key_prefix[param_name]} #{key}"
+      else
+        key
+      end
+    end
+
+    # Gets access_token using access_token_getter or uses the static access_token
+    def access_token_with_refresh
+      return access_token if access_token_getter.nil?
+      access_token_getter.call
+    end
+
+    # Gets Basic Auth token string
+    def basic_auth_token
+      'Basic ' + ["#{username}:#{password}"].pack('m').delete("\r\n")
+    end
+
+    # Returns Auth Settings hash for api client.
+    def auth_settings
+      {
+        'HTTPBearer' =>
+          {
+            type: 'bearer',
+            in: 'header',
+            key: 'Authorization',
+            value: "Bearer #{access_token_with_refresh}"
+          },
+      }
+    end
+
+    # Returns an array of Server setting
+    def server_settings
+      [
+        {
+          url: "",
+          description: "No description provided",
+        }
+      ]
+    end
+
+    def operation_server_settings
+      {
+      }
+    end
+
+    # Returns URL based on server settings
+    #
+    # @param index array index of the server settings
+    # @param variables hash of variable and the corresponding value
+    def server_url(index, variables = {}, servers = nil)
+      servers = server_settings if servers == nil
+
+      # check array index out of bound
+      if (index.nil? || index < 0 || index >= servers.size)
+        fail ArgumentError, "Invalid index #{index} when selecting the server. Must not be nil and must be less than #{servers.size}"
+      end
+
+      server = servers[index]
+      url = server[:url]
+
+      return url unless server.key? :variables
+
+      # go through variable and assign a value
+      server[:variables].each do |name, variable|
+        if variables.key?(name)
+          if (!server[:variables][name].key?(:enum_values) || server[:variables][name][:enum_values].include?(variables[name]))
+            url.gsub! "{" + name.to_s + "}", variables[name]
+          else
+            fail ArgumentError, "The variable `#{name}` in the server URL has invalid value #{variables[name]}. Must be #{server[:variables][name][:enum_values]}."
+          end
+        else
+          # use default value
+          url.gsub! "{" + name.to_s + "}", server[:variables][name][:default_value]
+        end
+      end
+
+      url
+    end
+
+
+  end
+end

data/lib/factpulse/helpers/client.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+require 'net/http'; require 'json'; require 'base64'; require 'uri'; require 'securerandom'
+
+module FactPulse
+  module Helpers
+    # Credentials Chorus Pro pour le mode Zero-Trust.
+    # Ces credentials sont passés dans chaque requête et ne sont jamais stockés côté serveur.
+    class ChorusProCredentials
+      attr_reader :piste_client_id, :piste_client_secret, :chorus_pro_login, :chorus_pro_password, :sandbox
+      def initialize(piste_client_id:, piste_client_secret:, chorus_pro_login:, chorus_pro_password:, sandbox: true)
+        @piste_client_id, @piste_client_secret = piste_client_id, piste_client_secret
+        @chorus_pro_login, @chorus_pro_password, @sandbox = chorus_pro_login, chorus_pro_password, sandbox
+      end
+      def to_h
+        { 'piste_client_id' => @piste_client_id, 'piste_client_secret' => @piste_client_secret,
+          'chorus_pro_login' => @chorus_pro_login, 'chorus_pro_password' => @chorus_pro_password, 'sandbox' => @sandbox }
+      end
+    end
+
+    # Credentials AFNOR PDP pour le mode Zero-Trust.
+    # L'API FactPulse utilise ces credentials pour s'authentifier auprès de la PDP AFNOR.
+    class AFNORCredentials
+      attr_reader :flow_service_url, :token_url, :client_id, :client_secret, :directory_service_url
+      def initialize(flow_service_url:, token_url:, client_id:, client_secret:, directory_service_url: nil)
+        @flow_service_url, @token_url = flow_service_url, token_url
+        @client_id, @client_secret, @directory_service_url = client_id, client_secret, directory_service_url
+      end
+      def to_h
+        result = { 'flow_service_url' => @flow_service_url, 'token_url' => @token_url,
+                   'client_id' => @client_id, 'client_secret' => @client_secret }
+        result['directory_service_url'] = @directory_service_url if @directory_service_url
+        result
+      end
+    end
+
+    # Helpers pour créer des montants totaux simplifiés.
+    module MontantHelpers
+      def self.montant(value)
+        return '0.00' if value.nil?
+        return format('%.2f', value) if value.is_a?(Numeric)
+        value.is_a?(String) ? value : '0.00'
+      end
+
+      def self.montant_total(ht, tva, ttc, a_payer, remise_ttc: nil, motif_remise: nil, acompte: nil)
+        result = {
+          'montantHtTotal' => montant(ht), 'montantTva' => montant(tva),
+          'montantTtcTotal' => montant(ttc), 'montantAPayer' => montant(a_payer)
+        }
+        result['montantRemiseGlobaleTtc'] = montant(remise_ttc) if remise_ttc
+        result['motifRemiseGlobaleTtc'] = motif_remise if motif_remise
+        result['acompte'] = montant(acompte) if acompte
+        result
+      end
+
+      # Crée une ligne de poste (aligné sur LigneDePoste de models.py).
+      def self.ligne_de_poste(numero, denomination, quantite, montant_unitaire_ht, montant_total_ligne_ht,
+                              taux_tva: '20.00', categorie_tva: 'S', unite: 'FORFAIT', **options)
+        result = {
+          'numero' => numero, 'denomination' => denomination,
+          'quantite' => montant(quantite), 'montantUnitaireHt' => montant(montant_unitaire_ht),
+          'montantTotalLigneHt' => montant(montant_total_ligne_ht), 'tauxTva' => montant(taux_tva),
+          'categorieTva' => categorie_tva, 'unite' => unite
+        }
+        result['reference'] = options[:reference] if options[:reference]
+        result['montantRemiseHt'] = montant(options[:montant_remise_ht]) if options[:montant_remise_ht]
+        result['codeRaisonReduction'] = options[:code_raison_reduction] if options[:code_raison_reduction]
+        result['raisonReduction'] = options[:raison_reduction] if options[:raison_reduction]
+        result['dateDebutPeriode'] = options[:date_debut_periode] if options[:date_debut_periode]
+        result['dateFinPeriode'] = options[:date_fin_periode] if options[:date_fin_periode]
+        result
+      end
+
+      # Crée une ligne de TVA (aligné sur LigneDeTVA de models.py).
+      def self.ligne_de_tva(taux_manuel, montant_base_ht, montant_tva, categorie: 'S')
+        {
+          'tauxManuel' => montant(taux_manuel), 'montantBaseHt' => montant(montant_base_ht),
+          'montantTva' => montant(montant_tva), 'categorie' => categorie
+        }
+      end
+
+      # Crée une adresse postale pour l'API FactPulse.
+      def self.adresse_postale(ligne1, code_postal, ville, pays: 'FR', ligne2: nil, ligne3: nil)
+        result = { 'ligneUn' => ligne1, 'codePostal' => code_postal, 'nomVille' => ville, 'paysCodeIso' => pays }
+        result['ligneDeux'] = ligne2 if ligne2
+        result['ligneTrois'] = ligne3 if ligne3
+        result
+      end
+
+      # Crée une adresse électronique. scheme_id: "0009"=SIREN, "0225"=SIRET
+      def self.adresse_electronique(identifiant, scheme_id: '0009')
+        { 'identifiant' => identifiant, 'schemeId' => scheme_id }
+      end
+
+      # Calcule le numéro TVA intracommunautaire français depuis un SIREN.
+      def self.calculer_tva_intra(siren)
+        return nil if siren.nil? || siren.length != 9 || !siren.match?(/^\d+$/)
+        cle = (12 + 3 * (siren.to_i % 97)) % 97
+        format('FR%02d%s', cle, siren)
+      end
+
+      # Crée un fournisseur (émetteur) avec auto-calcul SIREN, TVA intracommunautaire et adresses.
+      def self.fournisseur(nom, siret, adresse_ligne1, code_postal, ville, **options)
+        siren = options[:siren] || (siret.length == 14 ? siret[0, 9] : nil)
+        numero_tva_intra = options[:numero_tva_intra] || (siren ? calculer_tva_intra(siren) : nil)
+        result = {
+          'nom' => nom, 'idFournisseur' => options[:id_fournisseur] || 0, 'siret' => siret,
+          'adresseElectronique' => adresse_electronique(siret, scheme_id: '0225'),
+          'adressePostale' => adresse_postale(adresse_ligne1, code_postal, ville, pays: options[:pays] || 'FR', ligne2: options[:adresse_ligne2])
+        }
+        result['siren'] = siren if siren
+        result['numeroTvaIntra'] = numero_tva_intra if numero_tva_intra
+        result['iban'] = options[:iban] if options[:iban]
+        result['idServiceFournisseur'] = options[:code_service] if options[:code_service]
+        result['codeCoordonnesBancairesFournisseur'] = options[:code_coordonnees_bancaires] if options[:code_coordonnees_bancaires]
+        result
+      end
+
+      # Crée un destinataire (client) avec auto-calcul SIREN et adresses.
+      def self.destinataire(nom, siret, adresse_ligne1, code_postal, ville, **options)
+        siren = options[:siren] || (siret.length == 14 ? siret[0, 9] : nil)
+        result = {
+          'nom' => nom, 'siret' => siret,
+          'adresseElectronique' => adresse_electronique(siret, scheme_id: '0225'),
+          'adressePostale' => adresse_postale(adresse_ligne1, code_postal, ville, pays: options[:pays] || 'FR', ligne2: options[:adresse_ligne2])
+        }
+        result['siren'] = siren if siren
+        result['codeServiceExecutant'] = options[:code_service_executant] if options[:code_service_executant]
+        result
+      end
+    end
+
+    class FactPulseClient
+      attr_reader :chorus_credentials, :afnor_credentials
+
+      def initialize(email:, password:, api_url: nil, client_uid: nil, chorus_credentials: nil, afnor_credentials: nil,
+                     polling_interval: nil, polling_timeout: nil, max_retries: nil)
+        @email, @password = email, password; @api_url = (api_url || 'https://factpulse.fr').chomp('/')
+        @client_uid, @polling_interval, @polling_timeout, @max_retries = client_uid, polling_interval || 2000, polling_timeout || 120000, max_retries || 1
+        @chorus_credentials, @afnor_credentials = chorus_credentials, afnor_credentials
+        @access_token = @refresh_token = @token_expires_at = nil
+      end
+
+      def chorus_credentials_for_api; @chorus_credentials&.to_h; end
+      def afnor_credentials_for_api; @afnor_credentials&.to_h; end
+      # Alias plus courts
+      def get_chorus_pro_credentials; chorus_credentials_for_api; end
+      def get_afnor_credentials; afnor_credentials_for_api; end
+
+      def ensure_authenticated(force_refresh: false)
+        now = (Time.now.to_f * 1000).to_i
+        if force_refresh || @access_token.nil? || (@token_expires_at && now >= @token_expires_at)
+          payload = { 'username' => @email, 'password' => @password }; payload['client_uid'] = @client_uid if @client_uid
+          response = http_post(URI("#{@api_url}/api/token/"), payload)
+          raise FactPulseAuthError, "Auth failed" unless response.is_a?(Net::HTTPSuccess)
+          tokens = JSON.parse(response.body); @access_token, @refresh_token = tokens['access'], tokens['refresh']
+          @token_expires_at = now + (28 * 60 * 1000)
+        end
+      end
+
+      def reset_auth; @access_token = @refresh_token = @token_expires_at = nil; end
+
+      def poll_task(task_id, timeout: nil, interval: nil)
+        timeout_ms, interval_ms = timeout || @polling_timeout, interval || @polling_interval
+        start_time, current_interval = (Time.now.to_f * 1000).to_i, interval_ms.to_f
+        loop do
+          raise FactPulsePollingTimeout.new(task_id, timeout_ms) if (Time.now.to_f * 1000).to_i - start_time > timeout_ms
+          ensure_authenticated; response = http_get(URI("#{@api_url}/api/v1/traitement/taches/#{task_id}/statut"))
+          reset_auth and next if response.code == '401'
+          data = JSON.parse(response.body)
+          return data['resultat'] || {} if data['statut'] == 'SUCCESS'
+          if data['statut'] == 'FAILURE'
+            r = data['resultat'] || {}
+            raise FactPulseValidationError.new("Task #{task_id} failed: #{r['message_erreur'] || '?'}", (r['erreurs'] || []).map { |e| ValidationErrorDetail.from_hash(e) })
+          end
+          sleep(current_interval / 1000.0); current_interval = [current_interval * 1.5, 10000].min
+        end
+      end
+
+      def self.format_montant(m); MontantHelpers.montant(m); end
+
+      # Génère une facture Factur-X à partir d'un dict/hash et d'un PDF source.
+      # Accepte un Hash, un String JSON, ou tout objet avec une méthode to_h/to_hash.
+      # @param facture_data [Hash, String, Object] Données de la facture
+      # @param pdf_source [String, File] Chemin vers le PDF source ou objet File
+      # @param profil [String] Profil Factur-X (MINIMUM, BASIC, EN16931, EXTENDED)
+      # @param format_sortie [String] Format de sortie (pdf, xml, both)
+      # @param sync [Boolean] Mode synchrone (true) ou asynchrone (false)
+      # @param timeout [Integer, nil] Timeout en ms pour le polling
+      # @return [String] Contenu binaire du PDF généré
+      def generer_facturx(facture_data, pdf_source, profil: 'EN16931', format_sortie: 'pdf', sync: true, timeout: nil)
+        # Conversion des données en JSON string
+        json_data = case facture_data
+                    when String then facture_data
+                    when Hash then JSON.generate(facture_data)
+                    else
+                      if facture_data.respond_to?(:to_h)
+                        JSON.generate(facture_data.to_h)
+                      elsif facture_data.respond_to?(:to_hash)
+                        JSON.generate(facture_data.to_hash)
+                      else
+                        raise FactPulseValidationError.new("Type de données non supporté: #{facture_data.class}")
+                      end
+                    end
+
+        # Lecture du PDF source
+        pdf_content = case pdf_source
+                      when String then File.binread(pdf_source)
+                      when File then pdf_source.read
+                      else
+                        if pdf_source.respond_to?(:read)
+                          pdf_source.read
+                        else
+                          raise FactPulseValidationError.new("Type de PDF non supporté: #{pdf_source.class}")
+                        end
+                      end
+        pdf_filename = pdf_source.is_a?(String) ? File.basename(pdf_source) : 'facture.pdf'
+
+        ensure_authenticated
+        uri = URI("#{@api_url}/api/v1/traitement/generer-facture")
+
+        # Construire la requête multipart
+        boundary = "----RubyFormBoundary#{SecureRandom.hex(16)}"
+        body = []
+
+        # Champ donnees_facture
+        body << "--#{boundary}\r\n"
+        body << "Content-Disposition: form-data; name=\"donnees_facture\"\r\n\r\n"
+        body << "#{json_data}\r\n"
+
+        # Champ profil
+        body << "--#{boundary}\r\n"
+        body << "Content-Disposition: form-data; name=\"profil\"\r\n\r\n"
+        body << "#{profil}\r\n"
+
+        # Champ format_sortie
+        body << "--#{boundary}\r\n"
+        body << "Content-Disposition: form-data; name=\"format_sortie\"\r\n\r\n"
+        body << "#{format_sortie}\r\n"
+
+        # Champ source_pdf (fichier)
+        body << "--#{boundary}\r\n"
+        body << "Content-Disposition: form-data; name=\"source_pdf\"; filename=\"#{pdf_filename}\"\r\n"
+        body << "Content-Type: application/pdf\r\n\r\n"
+        body << pdf_content
+        body << "\r\n"
+
+        body << "--#{boundary}--\r\n"
+        body_str = body.join
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == 'https'
+        http.read_timeout = 120
+
+        request = Net::HTTP::Post.new(uri)
+        request['Authorization'] = "Bearer #{@access_token}"
+        request['Content-Type'] = "multipart/form-data; boundary=#{boundary}"
+        request.body = body_str
+
+        response = http.request(request)
+
+        if response.code == '401'
+          reset_auth
+          ensure_authenticated
+          request['Authorization'] = "Bearer #{@access_token}"
+          response = http.request(request)
+        end
+
+        unless response.is_a?(Net::HTTPSuccess)
+          error_data = JSON.parse(response.body) rescue { 'detail' => response.body }
+          raise FactPulseValidationError.new("Erreur API: #{error_data['detail'] || response.body}")
+        end
+
+        data = JSON.parse(response.body)
+
+        if sync && data['id_tache']
+          result = poll_task(data['id_tache'], timeout: timeout)
+          if result['contenu_b64']
+            require 'base64'
+            return Base64.decode64(result['contenu_b64'])
+          elsif result['contenu_xml']
+            return result['contenu_xml']
+          end
+          raise FactPulseValidationError.new("Résultat inattendu: #{result.keys.join(', ')}")
+        end
+
+        data
+      end
+
+      private
+      def http_post(uri, payload)
+        Net::HTTP.new(uri.host, uri.port).tap { |h| h.use_ssl = uri.scheme == 'https'; h.read_timeout = 30 }
+          .request(Net::HTTP::Post.new(uri).tap { |r| r['Content-Type'] = 'application/json'; r.body = JSON.generate(payload) })
+      end
+      def http_get(uri)
+        Net::HTTP.new(uri.host, uri.port).tap { |h| h.use_ssl = uri.scheme == 'https'; h.read_timeout = 30 }
+          .request(Net::HTTP::Get.new(uri).tap { |r| r['Authorization'] = "Bearer #{@access_token}" })
+      end
+    end
+  end
+end

data/lib/factpulse/helpers/exceptions.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+module FactPulse
+  module Helpers
+    class FactPulseError < StandardError; end
+    class FactPulseAuthError < FactPulseError; end
+    class FactPulsePollingTimeout < FactPulseError
+      attr_reader :task_id, :timeout
+      def initialize(task_id, timeout); @task_id, @timeout = task_id, timeout; super("Timeout (#{timeout}ms) pour #{task_id}"); end
+    end
+    class ValidationErrorDetail
+      attr_accessor :level, :item, :reason, :source, :code
+      def initialize(level: '', item: '', reason: '', source: nil, code: nil); @level, @item, @reason, @source, @code = level, item, reason, source, code; end
+      def to_s; "[#{@item.to_s.empty? ? 'unknown' : @item}] #{@reason.to_s.empty? ? 'Unknown error' : @reason}"; end
+      def self.from_hash(h); new(level: h['level']||'', item: h['item']||'', reason: h['reason']||'', source: h['source'], code: h['code']); end
+    end
+    class FactPulseValidationError < FactPulseError
+      attr_reader :errors
+      def initialize(msg, errors = []); @errors = errors; super(errors.empty? ? msg : "#{msg}\n\nDétails:\n#{errors.map{|e| "  - #{e}"}.join("\n")}"); end
+    end
+  end
+end

data/lib/factpulse/helpers.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+require_relative 'helpers/exceptions'
+require_relative 'helpers/client'
+module FactPulse
+  module Helpers
+    def self.create_client(**opts); FactPulseClient.new(**opts); end
+    def self.format_montant(m); MontantHelpers.montant(m); end
+    def self.montant(m); MontantHelpers.montant(m); end
+    def self.montant_total(*args, **kwargs); MontantHelpers.montant_total(*args, **kwargs); end
+    def self.ligne_de_poste(*args, **kwargs); MontantHelpers.ligne_de_poste(*args, **kwargs); end
+    def self.ligne_de_tva(*args, **kwargs); MontantHelpers.ligne_de_tva(*args, **kwargs); end
+  end
+end