cpro-client 0.1.0

data/lib/cpro/entities/base.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "date"
+require "time"
+
+module Cpro
+  module Entities
+    class Base
+      attr_reader :payload
+
+      def initialize(payload = nil)
+        @payload = payload.is_a?(Hash) ? payload : {}
+      end
+
+      def to_h
+        payload
+      end
+
+      def ==(other)
+        other.instance_of?(self.class) && other.payload == payload
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, payload].hash
+      end
+
+      private
+
+      def dig_payload(*keys)
+        keys.reduce(payload) { |value, key| value.is_a?(Hash) ? value[key] : nil }
+      end
+
+      SANS_FUSEAU = /\A\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(\.\d+)?\z/.freeze
+      private_constant :SANS_FUSEAU
+
+      # Les API G2B datent en UTC mais omettent le marqueur de fuseau. Sans ce rattrapage,
+      # Time.parse lirait la valeur comme une heure locale et le même payload donnerait un instant
+      # différent selon le fuseau du serveur hôte. Vérifié en sandbox : un dépôt à 20:25:41 UTC est
+      # daté « 2026-08-14T20:26:02.125919 » par l'API.
+      def parse_time(value)
+        return nil if value.nil? || value.to_s.empty?
+
+        texte = value.to_s
+        texte = "#{texte}Z" if texte.match?(SANS_FUSEAU)
+        Time.parse(texte)
+      rescue ArgumentError
+        nil
+      end
+
+      def parse_date(value)
+        return nil if value.nil? || value.to_s.empty?
+
+        Date.parse(value.to_s)
+      rescue ArgumentError
+        nil
+      end
+
+      # Les montants arrivent en nombres JSON : on repasse par leur représentation textuelle pour
+      # éviter de traîner les approximations du flottant sur des sommes d'argent.
+      def parse_montant(value)
+        return nil if value.nil?
+
+        BigDecimal(value.to_s)
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/cpro/entities/changement_statut.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Cpro
+  module Entities
+    class ChangementStatut < Base
+      def statut
+        payload["statut"]
+      end
+
+      def date
+        @date ||= parse_time(payload["dateEtHeureMiseAJourStatut"])
+      end
+
+      def motifs_rejet
+        @motifs_rejet ||= Array(payload["detailStatut"]).map { |detail| MotifRejet.new(detail) }
+      end
+
+      def rejet?
+        !motifs_rejet.empty?
+      end
+
+      def to_s
+        statut.to_s
+      end
+    end
+  end
+end

data/lib/cpro/entities/depot_flux.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Cpro
+  module Entities
+    class DepotFlux < Base
+      def uid
+        payload["uidFlux"]
+      end
+      alias uid_flux uid
+
+      def to_s
+        uid.to_s
+      end
+    end
+  end
+end

data/lib/cpro/entities/etablissement.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Cpro
+  module Entities
+    class Etablissement < Base
+      ETABLISSEMENT_PRINCIPAL = "P"
+      ETAT_ACTIF = "A"
+
+      def siret
+        payload["siret"]
+      end
+
+      def siren
+        payload["siren"]
+      end
+
+      def denomination
+        payload["denomination"]
+      end
+
+      def type_etablissement
+        payload["typeEtablissement"]
+      end
+
+      def principal?
+        type_etablissement == ETABLISSEMENT_PRINCIPAL
+      end
+
+      def etat_administratif
+        payload["etatAdministratif"]
+      end
+
+      def actif?
+        etat_administratif == ETAT_ACTIF
+      end
+
+      def diffusible
+        payload["diffusible"]
+      end
+
+      def adresse
+        payload["adresse"] || {}
+      end
+
+      def code_postal
+        adresse["codePostal"]
+      end
+
+      def localite
+        adresse["localite"]
+      end
+
+      def unite_legale
+        return nil unless payload["uniteLegale"]
+
+        @unite_legale ||= UniteLegale.new(payload["uniteLegale"])
+      end
+
+      def publique?
+        unite_legale&.publique?
+      end
+
+      def donnees_b2g
+        payload["donneesB2gComplementaires"] || {}
+      end
+
+      def moa?
+        donnees_b2g["moa"]
+      end
+
+      def moa_uniquement?
+        donnees_b2g["moaUniquement"]
+      end
+
+      def gestion_engagement_juridique?
+        donnees_b2g["gestionEngagementJuridique"]
+      end
+
+      def gestion_engagement_juridique_ou_service?
+        donnees_b2g["gestionEngagementJuridiqueOuService"]
+      end
+
+      def gestion_code_service?
+        donnees_b2g["gestionCodeService"]
+      end
+
+      def gestion_statut_mise_en_paiement?
+        donnees_b2g["gestionStatutMiseEnPaiement"]
+      end
+
+      def lignes_annuaire
+        @lignes_annuaire ||= LignesAnnuaire.new(payload["lignesAnnuaire"])
+      end
+    end
+  end
+end

data/lib/cpro/entities/facture.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Cpro
+  module Entities
+    class Facture < Base
+      STATUTS = %w[
+        DEPOSEE RECUE_DE_LA_PLATEFORME REFUSEE PAIEMENT_TRANSMIS ENCAISSEE REJETEE ANNULEE
+        EMISE_PAR_LA_PLATEFORME MISE_A_DISPOSITION PRISE_EN_CHARGE APPROUVEE APPROUVEE_PARTIELLEMENT
+        EN_LITIGE SUSPENDUE COMPLETEE VISEE ERREUR_ROUTAGE DEMANDE_DE_PAIEMENT_DIRECT
+        CHANGEMENT_DE_COMPTE_A_PAYER NON_AFFACTUREE AFFACTUREE AFFACTUREE_CONFIDENTIEL
+      ].freeze
+
+      CHAMPS = {
+        uid: "uidFacture",
+        numero: "numeroFacture",
+        code_type: "codeTypeFacture",
+        devise: "codeDeviseFacture",
+        objet: "idObjetFacture",
+        type_processus_metier: "typeProcessusMetier",
+        numero_facture_anterieure: "numeroFactureAnterieure",
+        raison_sociale_vendeur: "raisonSocialeVendeur",
+        siren_vendeur: "sirenVendeur",
+        siret_vendeur: "siretVendeur",
+        raison_sociale_agent_vendeur: "raisonSocialeAgentVendeur",
+        siren_agent_vendeur: "sirenAgentVendeur",
+        siret_agent_vendeur: "siretAgentVendeur",
+        raison_sociale_acheteur: "raisonSocialeAcheteur",
+        siren_acheteur: "sirenAcheteur",
+        siret_acheteur: "siretAcheteur",
+        id_adressage_acheteur: "idAdressageAcheteur",
+        siren_tiers_facturant: "sirenTiersFacturant",
+        siret_tiers_facturant: "siretTiersFacturant",
+        statut: "statutFacture",
+        nom_flux: "nomFlux",
+        uid_facture_principale: "uidFacturePrincipale"
+      }.freeze
+
+      MONTANTS = {
+        montant_total: "montantTotal",
+        montant_total_hors_tva: "montantTotalHorsTVA",
+        montant_tva: "montantTVA",
+        montant_paye: "montantPaye",
+        montant_a_payer: "montantAPayer"
+      }.freeze
+
+      CHAMPS.each { |name, key| define_method(name) { payload[key] } }
+      MONTANTS.each { |name, key| define_method(name) { parse_montant(payload[key]) } }
+      STATUTS.each { |valeur| define_method(:"#{valeur.downcase}?") { statut == valeur } }
+
+      def initialize(payload = nil, historique: nil)
+        super(payload)
+        @historique_payload = historique
+      end
+
+      def date_emission
+        @date_emission ||= parse_date(payload["dateEmissionFacture"])
+      end
+
+      def date_echeance
+        @date_echeance ||= parse_date(payload["dateEcheanceFacture"])
+      end
+
+      def date_statut
+        @date_statut ||= parse_time(payload["dateStatutFacture"])
+      end
+
+      def multivendeurs?
+        payload["factureMultivendeurs"]
+      end
+
+      # Renseigné par `Factures#find` seulement : la recherche ne retourne pas l'historique.
+      def historique
+        @historique ||= Array(@historique_payload).map { |changement| ChangementStatut.new(changement) }
+      end
+
+      def motifs_rejet
+        historique.flat_map(&:motifs_rejet)
+      end
+
+      def to_s
+        [numero, statut].compact.join(" ")
+      end
+    end
+  end
+end

data/lib/cpro/entities/ligne_annuaire.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Cpro
+  module Entities
+    class LigneAnnuaire < Base
+      PLATEFORME_ACTIVE = "Plateforme active"
+      PLATEFORME_EN_ATTENTE = "Plateforme en attente d'activation"
+
+      def identifiant_adressage
+        payload["identifiantAdressage"]
+      end
+
+      def siren
+        payload["siren"]
+      end
+
+      def siret
+        payload["siret"]
+      end
+
+      def identifiant_routage
+        payload["identifiantRoutage"]
+      end
+
+      def suffixe_adressage
+        payload["suffixeAdressage"]
+      end
+
+      def statut_plateforme
+        payload["statutPlateforme"]
+      end
+
+      def plateforme_active?
+        statut_plateforme == PLATEFORME_ACTIVE
+      end
+
+      def plateforme_en_attente?
+        statut_plateforme == PLATEFORME_EN_ATTENTE
+      end
+    end
+  end
+end

data/lib/cpro/entities/lignes_annuaire.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Cpro
+  module Entities
+    class LignesAnnuaire < Base
+      include Enumerable
+
+      def items
+        @items ||= Array(payload["items"]).map { |item| LigneAnnuaire.new(item) }
+      end
+
+      def each(&block)
+        items.each(&block)
+      end
+
+      def nombre_total
+        payload["nombreTotal"]
+      end
+
+      def limite
+        payload["limite"]
+      end
+
+      def ignorer
+        payload["ignorer"]
+      end
+
+      def size
+        items.size
+      end
+      alias length size
+
+      def empty?
+        items.empty?
+      end
+
+      # Vrai tant que la page courante ne couvre pas la totalité des lignes rattachées.
+      def suite?
+        return false if nombre_total.nil?
+
+        (ignorer.to_i + size) < nombre_total
+      end
+    end
+  end
+end

data/lib/cpro/entities/motif_rejet.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Cpro
+  module Entities
+    class MotifRejet < Base
+      # Code du motif de rejet du CDV, selon la norme AFNOR.
+      def code
+        payload["codeMotifRejet"]
+      end
+
+      def libelle
+        payload["libelleMotifRejet"]
+      end
+
+      def notes
+        @notes ||= Array(payload["noteStatut"]).map { |note| NoteStatut.new(note) }
+      end
+
+      def to_s
+        [code, libelle].compact.join(" — ")
+      end
+    end
+  end
+end

data/lib/cpro/entities/note_statut.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Cpro
+  module Entities
+    class NoteStatut < Base
+      def code
+        payload["codeContenu"]
+      end
+
+      def contenu
+        payload["contenu"]
+      end
+
+      # Nom du fichier ayant provoqué l'irrecevabilité, lorsque la note porte sur un flux.
+      def sujet
+        payload["sujet"]
+      end
+
+      def to_s
+        [code, contenu].compact.join(" — ")
+      end
+    end
+  end
+end

data/lib/cpro/entities/resultat_recherche.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Cpro
+  module Entities
+    class ResultatRecherche < Base
+      include Enumerable
+
+      # Les deux API ne nomment pas le total de la même façon — `nombre_total_resultats` pour
+      # l'Annuaire, `nombreTotalResultats` pour Recherche Factures — d'où la clé explicite.
+      attr_reader :item_class, :total_key
+
+      def initialize(payload, item_class:, total_key:)
+        super(payload)
+        @item_class = item_class
+        @total_key = total_key
+      end
+
+      def resultats
+        @resultats ||= Array(payload["resultats"]).map { |item| item_class.new(item) }
+      end
+
+      def each(&block)
+        resultats.each(&block)
+      end
+
+      def nombre_total
+        payload[total_key]
+      end
+
+      # Renseignés par Recherche Factures seulement : la recherche d'annuaire ne retourne pas ses
+      # paramètres de pagination. Combinés à `nombre_total`, ils permettent de paginer.
+      def limite
+        payload["limite"]
+      end
+
+      def ignores
+        payload["ignores"]
+      end
+
+      def size
+        resultats.size
+      end
+      alias length size
+
+      def empty?
+        resultats.empty?
+      end
+
+      def ==(other)
+        super && other.item_class == item_class
+      end
+      alias eql? ==
+    end
+  end
+end

data/lib/cpro/entities/statut_flux.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Cpro
+  module Entities
+    class StatutFlux < Base
+      RECEVABLE = "RECEVABLE"
+      IRRECEVABLE = "IRRECEVABLE"
+      EN_COURS = "ENTRANT_ENVELOPPE_VALIDE"
+
+      def statut
+        payload["statut"]
+      end
+
+      # 500 recevable, 501 irrecevable. Ajouté par Chorus Pro 5.2.2 (19/08/2026).
+      def code_statut
+        payload["codeStatut"]
+      end
+
+      def recevable?
+        statut == RECEVABLE
+      end
+
+      def irrecevable?
+        statut == IRRECEVABLE
+      end
+
+      def en_cours?
+        statut == EN_COURS
+      end
+
+      # Renseigné par le PPF uniquement lorsque le flux est recevable ; c'est cette valeur qui
+      # permet ensuite de retrouver la facture via l'API Recherche Factures G2B.
+      def nom_flux
+        payload["nomFlux"]
+      end
+
+      def date_maj_statut
+        @date_maj_statut ||= parse_time(payload["dateMajStatut"])
+      end
+
+      def motifs_rejet
+        @motifs_rejet ||= Array(payload["detailStatut"]).map { |detail| MotifRejet.new(detail) }
+      end
+
+      def rejet?
+        !motifs_rejet.empty?
+      end
+
+      def to_s
+        statut.to_s
+      end
+    end
+  end
+end

data/lib/cpro/entities/unite_legale.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Cpro
+  module Entities
+    class UniteLegale < Base
+      TYPE_PUBLIQUE = "Publique"
+      TYPE_PRIVEE = "Privée assujettie"
+      ETAT_ACTIF = "A"
+
+      def siren
+        payload["siren"]
+      end
+
+      def raison_sociale
+        payload["raisonSociale"]
+      end
+
+      def type_entite
+        payload["typeEntite"]
+      end
+
+      def publique?
+        type_entite == TYPE_PUBLIQUE
+      end
+
+      def privee?
+        type_entite == TYPE_PRIVEE
+      end
+
+      def etat_administratif
+        payload["etatAdministratif"]
+      end
+
+      def actif?
+        etat_administratif == ETAT_ACTIF
+      end
+
+      def diffusible
+        payload["diffusible"]
+      end
+
+      def lignes_annuaire
+        @lignes_annuaire ||= LignesAnnuaire.new(payload["lignesAnnuaire"])
+      end
+    end
+  end
+end

data/lib/cpro/enveloppe.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "base64"
+require "digest"
+
+module Cpro
+  class Enveloppe
+    # Codes interfaces acceptés par POST /flux. Le dépôt de CDV emprunte le même endpoint que
+    # la facture : émettre un statut, c'est déposer un flux.
+    CODES_INTERFACE = {
+      ubl: "FSO3110A",
+      facturx: "FSO3117A",
+      ereporting: "FSO6000A",
+      cdv: "FSO3300A"
+    }.freeze
+
+    attr_reader :content, :name, :code_interface
+
+    def self.from(source, code_interface:, name: nil)
+      if source.respond_to?(:read)
+        resolved = name || (File.basename(source.path) if source.respond_to?(:path))
+        new(content: source.read, name: resolved, code_interface: code_interface)
+      else
+        path = source.to_s
+        new(content: File.binread(path), name: name || File.basename(path),
+            code_interface: code_interface)
+      end
+    end
+
+    def initialize(content:, name:, code_interface:)
+      raise ArgumentError, "le contenu du flux est vide" if content.nil? || content.empty?
+      raise ArgumentError, "un nom de fichier est requis" if name.nil? || name.to_s.empty?
+
+      @content = content
+      @name = name.to_s
+      @code_interface = resolve_code_interface(code_interface)
+    end
+
+    def payload
+      {
+        "codeInterface" => code_interface,
+        "fichierFlux" => fichier_flux,
+        "checksum" => checksum
+      }
+    end
+
+    def archive
+      @archive ||= Archive.gzip([{ name: name, content: content }])
+    end
+
+    def fichier_flux
+      @fichier_flux ||= Base64.strict_encode64(archive)
+    end
+
+    # Le swagger Dépôt flux G2B définit le checksum comme le sha256 « du fichier encodé », donc
+    # de la chaîne base64 et non des octets de l'archive. Confirmé en sandbox : un flux dont le
+    # checksum est calculé ainsi ressort RECEVABLE.
+    def checksum
+      @checksum ||= Digest::SHA256.hexdigest(fichier_flux)
+    end
+
+    private
+
+    def resolve_code_interface(value)
+      return CODES_INTERFACE.fetch(value) if CODES_INTERFACE.key?(value)
+      return value if CODES_INTERFACE.value?(value)
+
+      raise ArgumentError,
+            "code interface inconnu : #{value.inspect} " \
+            "(attendus : #{CODES_INTERFACE.keys.join(", ")})"
+    end
+  end
+end

data/lib/cpro/errors.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Cpro
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+
+  class ApiError < Error
+    attr_reader :status, :body, :correlation_id
+
+    def initialize(message, status: nil, body: nil, correlation_id: nil)
+      @status = status
+      @body = body
+      @correlation_id = correlation_id
+      super(message)
+    end
+  end
+
+  class RequestError < ApiError; end
+  class AuthenticationError < ApiError; end
+  class AuthorizationError < ApiError; end
+  class NotFoundError < ApiError; end
+  class RateLimitError < ApiError; end
+  class ServerError < ApiError; end
+end