cpro-client 0.2.4 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eed2218b6135210909bb231938a2adf3d8f9b432a19468576b232ffd2f352d7a
-  data.tar.gz: 95739510c05be2fdc248b2f001e4b53e08b3487162dbb29f50bc26606d929e06
+  metadata.gz: 1f1452657739318ca5d2a71a6673d046dea03e4f5e3b00befc41ae210fcf3ee4
+  data.tar.gz: b36804bf664635e9d5f510fe8a8ed2e52a6aeb1753b9de3bc3b919475d3e51cb
 SHA512:
-  metadata.gz: 7208819c95be0220d40498c3d09c5df5479619c652c6103aac41903ce1cac6054f47b53a7c87638fd7b474e99581a61b6924ab1d0f17b633bb18a72d431e8a94
-  data.tar.gz: 4c292e8c13863bdff0fe54ab567e42880c4d25e5d928ca70fb6c1a83284198912cc14b5dd787f0733763e181a7923f08ab7768a0ee5007b5b4e52b3719c4b7f0
+  metadata.gz: 918adeba480ffaaec7508e21e68c31799708e568fb4dc5f2678072ab9f10971f31a03c8af893e57548cce0d5c93b9ad2b9d5387a50a7d629f40f945dfb16b93a
+  data.tar.gz: 299ffdbbc8b8c9f25b24c09d1577fdd4e0d1f3b9bc9f3b0eed7c6d607f428e86e87d1a1978bb55c10ab6e450bdb24c996b5909673113031cfb375bb65ab30255

data/CHANGELOG.md

@@ -1,6 +1,48 @@
 ## [Unreleased]
 
 
+## [0.2.6] - 2026-09-05
+
+### Modifié
+- `Cpro::Resources::Annuaire#find_identifiant_actif` devient **`#find_identifiant_adressage`**, et
+  ne filtre plus sur le statut de plateforme : il le fait départager. À proximité égale une adresse
+  active l'emporte, mais faute d'adresse active la plus proche est rendue quand même.
+
+  L'ancien comportement interdisait de facturer un destinataire non raccordé, alors que le dossier
+  de spécifications externes pose l'inverse : une telle facture est *déposée*, avec le motif
+  `NON_TRANSMISE`, et ce statut « permet à l'entité publique de justifier qu'elle a bien émis une
+  facture électronique et qu'elle a donc respecté ses obligations réglementaires ». L'émetteur doit
+  remettre un duplicata à son client, mais l'obligation réglementaire est remplie — la gem n'a pas
+  à s'y opposer.
+
+  L'appelant lit `plateforme_active?` sur la ligne rendue pour distinguer les deux cas, et `nil` ne
+  signifie plus qu'une chose : aucune adresse à aucun niveau.
+
+
+## [0.2.5] - 2026-09-05
+
+### Ajouté
+- `Cpro::Client#suivi` enchaîne les appels de suivi d'un dépôt — statut du flux, recherche de la
+  facture, consultation avec son historique — et rend un `Cpro::Suivi` qui nomme l'étape atteinte :
+  `:flux_en_attente` (404 du PPF, cas nominal juste après un dépôt), `:flux_irrecevable`,
+  `:facture_introuvable` (204, ambigu par nature) ou `:facture_connue`. Il court-circuite dès
+  qu'un palier interdit d'aller plus loin : un appel tant que le flux n'est pas traité, trois au
+  plus. Il n'attend jamais — la cadence d'interrogation appartient à l'appelant — et laisse
+  `statut_flux` et `facture` accessibles pour ce qu'il n'interprète pas.
+- `Cpro::Entities::Facture#dernier_incident`, relayé par `Cpro::Suivi#dernier_incident`, isole le
+  dernier changement de statut porteur de motifs — l'incident en cours — là où `motifs_rejet`
+  cumule tout l'historique. Il rend le changement et non le motif : un même changement en porte
+  plusieurs, une facture « Déposée » pouvant cumuler `NON_TRANSMISE` et `REJ_UNI`.
+- `Cpro::Suivi#motifs` rassemble les motifs de rejet, qu'ils viennent du flux ou de l'historique de
+  la facture : l'appelant n'a plus à savoir où le dépôt s'est arrêté pour aller les chercher.
+- `Cpro::Entities::Facture#en_echec?` — vrai dès qu'une facture demande une intervention, que son
+  statut l'annonce ou non. Chorus Pro accroche ses motifs de rejet au statut porteur, qui peut
+  être anodin : une facture « Déposée » assortie de `NON_TRANSMISE` ne parviendra pas à son
+  destinataire alors que `rejetee?` répond faux. Le prédicat couvre les statuts `REJETEE` et
+  `ERREUR_ROUTAGE` ainsi que tout motif présent dans l'historique — lequel n'est renseigné que
+  par `Factures#find`.
+
+
 ## [0.2.3] - 2026-08-31
 
 ### Ajouté

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    cpro-client (0.2.4)
+    cpro-client (0.2.6)
       faraday (>= 0.9, < 3.0)
 
 GEM

data/README.md

@@ -142,27 +142,40 @@ BT-49, l'adresse électronique de l'acheteur, ne se transmet pas à l'API : elle
 Factur-X, et c'est d'elle que le PPF déduit l'acheminement. Une facture qui la porte mal est
 rejetée `REJ_ADR` — « le destinataire n'est pas trouvable » — plusieurs minutes après le dépôt.
 
-`find_identifiant_actif` fait la résolution en un appel. Il accepte les quatre formes d'une valeur
-d'adressage — SIREN, SIRET, SIRET_SERVICE, SIREN_SIRET_SERVICE — et remonte la hiérarchie
-SIREN → SIRET → service jusqu'à trouver une ligne dont la plateforme est active :
+`find_identifiant_adressage` fait la résolution en un appel. Il accepte les quatre formes d'une
+valeur d'adressage — SIREN, SIRET, SIRET_SERVICE, SIREN_SIRET_SERVICE — et remonte la hiérarchie
+SIREN → SIRET → service pour rendre l'adresse la plus proche que l'annuaire connaisse :
 
 ```ruby
-ligne = client.annuaire.find_identifiant_actif("71915767420316")
+ligne = client.annuaire.find_identifiant_adressage("71915767420316")
 ligne.to_s                  # => "719157674_71915767420316", à porter en BT-49
-ligne.identifiant_routage   # => "" — l'adresse de base de l'établissement
+ligne.plateforme_active?    # => la facture sera-t-elle transmise ?
 
-client.annuaire.find_identifiant_actif("71915767420316_SERVICE_INEXISTANT").to_s
+client.annuaire.find_identifiant_adressage("71915767420316_SERVICE_INEXISTANT").to_s
 # => "719157674_71915767420316" — service inconnu, on retombe sur son parent
 ```
 
-`nil` signifie qu'aucun niveau n'est adressable, donc qu'on ne peut pas facturer. Pour savoir
-*pourquoi*, `find_lignes_adressage` rend les mêmes lignes sans filtrer : une unité légale inconnue
-lève une `Cpro::NotFoundError`, tandis qu'une unité connue mais non raccordée rend ses lignes avec
-`plateforme_active?` à faux.
+**Le statut de plateforme départage, il n'exclut pas.** À égalité de proximité, une adresse dont la
+plateforme est active l'emporte ; mais si aucune ne l'est, l'adresse est rendue quand même. Elle
+reste la bonne : une facture destinée à un non-raccordé est bien *déposée*, avec le motif
+`NON_TRANSMISE`, et ce statut « permet à l'entité publique de justifier qu'elle a bien émis une
+facture électronique et qu'elle a donc respecté ses obligations réglementaires ». L'émetteur devra
+remettre un duplicata à son client, mais l'obligation est remplie.
 
-Deux limites à connaître. La résolution ne redescend jamais vers les enfants : un SIREN nu ne
-remonte rien si la structure n'a d'adresses qu'au niveau SIRET. Et une adresse active n'est pas une
-promesse d'acheminement — elle garantit que le destinataire est identifiable, pas qu'il recevra.
+L'appelant lit donc `plateforme_active?` sur la ligne rendue pour savoir dans quel cas il est :
+
+| Résultat | Ce qui se passera |
+| --- | --- |
+| ligne, `plateforme_active?` vrai | la facture est transmise au destinataire |
+| ligne, `plateforme_active?` faux | déposée et conforme, mais non transmise — duplicata à prévoir |
+| `nil` | aucune adresse à aucun niveau : on ne peut pas facturer |
+
+Pour distinguer « unité légale inconnue » de « connue mais sans adresse exploitable »,
+`find_lignes_adressage` rend les mêmes lignes sans les départager et laisse remonter la
+`Cpro::NotFoundError`.
+
+Une limite à connaître : la résolution ne redescend jamais vers les enfants. Un SIREN nu ne remonte
+rien si la structure n'a d'adresses qu'au niveau SIRET.
 
 ## Transmission d'une facture Factur-X
 
@@ -254,6 +267,48 @@ aucune facture ne correspond que lorsque le compte technique n'est rattaché ni
 callback, et les statuts des factures G2B ne sont pas consultables sur le portail Chorus Pro : le
 suivi passe nécessairement par une interrogation périodique de cette API.
 
+## Suivre un dépôt en un appel
+
+Les quatre étapes du suivi — statut du flux, recherche par `nomFlux`, consultation, lecture des
+motifs — se réduisent à une méthode, qui nomme l'étape atteinte plutôt que de lever ou de rendre
+`nil` :
+
+```ruby
+suivi = client.suivi(depot)
+
+suivi.etape        # :flux_en_attente, :flux_irrecevable, :facture_introuvable, :facture_connue
+suivi.en_echec?    # au niveau de l'enveloppe comme à celui de la facture
+suivi.motifs       # les motifs, d'où qu'ils viennent
+suivi.facture      # la facture et son historique, à l'étape :facture_connue
+suivi.statut_flux  # le statut brut du flux, dès qu'il est connu
+```
+
+`motifs` cumule tout l'historique — un incident réglé y côtoie l'incident courant. Pour n'avoir que
+le plus récent, avec le statut qui le portait et sa date :
+
+```ruby
+incident = suivi.dernier_incident      # un ChangementStatut, ou nil
+
+incident.statut                        # "DEPOSEE"
+incident.date                          # 2026-09-04 19:18:31 UTC
+incident.motifs_rejet.map(&:code)      # ["NON_TRANSMISE", "REJ_UNI"]
+```
+
+Il rend le changement et non le motif : un même changement en porte plusieurs, et n'en exposer
+qu'un les masquerait. Il vaut `nil` à l'étape `:flux_irrecevable`, où il n'y a pas encore de
+facture — `motifs` reste alors l'accès uniforme.
+
+| Étape | Ce qui s'est passé | Appels | Suite |
+| --- | --- | :-: | --- |
+| `:flux_en_attente` | 404 sur le flux — cas nominal | 1 | réinterroger |
+| `:flux_irrecevable` | enveloppe refusée, motifs sur le flux | 1 | terminal |
+| `:facture_introuvable` | flux recevable, recherche vide | 2 | réinterroger, puis vérifier le rattachement du compte |
+| `:facture_connue` | facture et historique disponibles | 3 | lire `en_echec?` et les motifs |
+
+La méthode **n'attend pas** : c'est une photographie, la cadence d'interrogation reste à l'appelant.
+Seuls le 404 du flux et la recherche vide deviennent des étapes ; un 401, un 403 ou un 5xx
+continuent de lever.
+
 ## Servir plusieurs entités
 
 L'AIFE distingue trois types de raccordement API. Celui qui s'applique détermine le modèle à

data/lib/cpro/client.rb

@@ -19,6 +19,12 @@ module Cpro
       self.class.new(configuration, account: account, token_provider: token_provider, connections: connections)
     end
 
+    # Enchaîne les appels de suivi d'un dépôt et rend une synthèse. Traverse deux ressources,
+    # d'où sa place ici plutôt que sur l'une d'elles.
+    def suivi(depot)
+      Suivi.pour(self, depot)
+    end
+
     def annuaire
       @annuaire ||= Resources::Annuaire.new(self, connection_for(ANNUAIRE_PATH))
     end

data/lib/cpro/entities/facture.rb

@@ -10,6 +10,11 @@ module Cpro
         CHANGEMENT_DE_COMPTE_A_PAYER NON_AFFACTUREE AFFACTUREE AFFACTUREE_CONFIDENTIEL
       ].freeze
 
+      EPOQUE = Time.at(0).utc
+
+      # Statuts qui constatent par eux-mêmes qu'une facture n'arrivera pas.
+      STATUTS_EN_ECHEC = %w[REJETEE ERREUR_ROUTAGE].freeze
+
       CHAMPS = {
         uid: "uidFacture",
         numero: "numeroFacture",
@@ -77,6 +82,36 @@ module Cpro
         historique.flat_map(&:motifs_rejet)
       end
 
+      # Le dernier changement de statut porteur de motifs — celui qui décrit l'incident en cours,
+      # là où `motifs_rejet` cumule tout l'historique, motifs devenus caducs compris.
+      #
+      # Rend le changement et non le motif : un même changement en porte plusieurs — une facture
+      # « Déposée » peut cumuler NON_TRANSMISE et REJ_UNI — et n'en exposer qu'un les masquerait.
+      # Le rang départage deux changements de même date, le plus récent l'emportant.
+      def dernier_incident
+        incidents = historique.select(&:rejet?)
+        incidents.each_with_index.max_by { |changement, rang| [changement.date || EPOQUE, rang] }&.first
+      end
+
+      # Vrai dès qu'une facture demande une intervention, que son statut l'annonce ou non : un
+      # motif de rejet peut être porté par un statut anodin. Une facture « Déposée » accompagnée
+      # de NON_TRANSMISE en est le cas type — `rejetee?` répond faux, et pourtant le destinataire
+      # ne la recevra pas par la plateforme.
+      #
+      # Attention au mot « échec » : NON_TRANSMISE n'invalide pas la facture. Le dossier de
+      # spécifications externes est explicite — ce statut « permet à l'entité publique de
+      # justifier qu'elle a bien émis une facture électronique et qu'elle a donc respecté ses
+      # obligations réglementaires ». Il n'y a donc rien à redéposer ; il y a à livrer autrement.
+      #
+      # Le refus de l'acheteur (REFUSEE) n'en fait pas partie : c'est une décision métier, une
+      # étape normale du cycle de vie, pas un incident. Elle se lit par `refusee?`.
+      #
+      # L'historique n'étant renseigné que par `Factures#find`, une facture issue d'une recherche
+      # ne peut être jugée que sur son statut.
+      def en_echec?
+        STATUTS_EN_ECHEC.include?(statut) || historique.any?(&:rejet?)
+      end
+
       def to_s
         [numero, statut].compact.join(" ")
       end

data/lib/cpro/resources/annuaire.rb

@@ -77,23 +77,25 @@ module Cpro
         Entities::ResultatRecherche.new(payload, item_class: Entities::CodeRoutage, total_key: TOTAL_KEY)
       end
 
-      # Adresse active la plus proche d'une valeur d'adressage : la valeur elle-même si elle porte
-      # une plateforme active, sinon son parent le plus proche, et ainsi de suite jusqu'au SIREN.
-      # Rend la ligne d'annuaire, dont `to_s` donne l'identifiant à porter en BT-49.
+      # Adresse à porter en BT-49 pour une valeur d'adressage : la plus proche que l'annuaire
+      # connaisse, en privilégiant celles dont la plateforme est active. Rend la ligne d'annuaire,
+      # dont `to_s` donne l'identifiant.
       #
-      # `nil` a un sens unique — aucun niveau n'est adressable, donc on ne peut pas facturer. Pour
-      # distinguer « SIREN inconnu » de « connu mais sans plateforme active », voir
-      # `#find_lignes_adressage`, qui ne filtre pas et laisse remonter le 404.
+      # Le statut de plateforme départage, il n'exclut pas. Une adresse sans plateforme reste
+      # utilisable : le dossier de spécifications externes pose qu'une facture destinée à un
+      # destinataire non raccordé prend le statut « Déposée » avec le motif NON_TRANSMISE, et que
+      # ce statut « permet à l'entité publique de justifier qu'elle a bien émis une facture
+      # électronique et qu'elle a donc respecté ses obligations réglementaires ». L'émetteur devra
+      # remettre un duplicata à son client, mais la facture est valide et l'obligation remplie.
+      #
+      # L'appelant lit `plateforme_active?` sur la ligne rendue pour savoir dans lequel des deux
+      # cas il se trouve. `nil` ne signifie plus qu'une chose : aucune adresse, à aucun niveau.
       #
       # Un seul appel réseau : `GET /siren/code-insee:` retourne aussi les lignes SIRET et service.
-      def find_identifiant_actif(valeur)
+      def find_identifiant_adressage(valeur)
         adressage = Adressage.parse(valeur)
-        actives = find_lignes_adressage(adressage).select(&:plateforme_active?)
-        adressage.paliers.each do |palier|
-          ligne = actives.find { |active| palier.correspond?(active) }
-          return ligne if ligne
-        end
-        nil
+        lignes = find_lignes_adressage(adressage)
+        plus_proche(adressage, lignes.select(&:plateforme_active?)) || plus_proche(adressage, lignes)
       rescue NotFoundError
         nil
       end
@@ -110,6 +112,16 @@ module Cpro
 
       private
 
+      # Descend les paliers du plus précis au plus général et rend la première ligne qui
+      # corresponde. Appelée deux fois : sur les adresses actives d'abord, sur toutes ensuite.
+      def plus_proche(adressage, lignes)
+        adressage.paliers.each do |palier|
+          ligne = lignes.find { |candidate| palier.correspond?(candidate) }
+          return ligne if ligne
+        end
+        nil
+      end
+
       def normalize(value, length, label)
         digits = value.to_s.gsub(/\s+/, "")
         return digits if digits.match?(/\A\d{#{length}}\z/)

data/lib/cpro/suivi.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Cpro
+  # Photographie du parcours d'un dépôt, à un instant donné. Elle enchaîne les appels que l'hôte
+  # devrait sinon écrire lui-même — statut du flux, recherche de la facture, consultation avec son
+  # historique — et s'arrête dès qu'un palier ne permet pas d'aller plus loin.
+  #
+  # Elle n'attend pas : la cadence d'interrogation appartient à l'appelant. Et elle n'avale rien,
+  # `statut_flux` et `facture` restant accessibles pour ce qu'elle n'interprète pas.
+  class Suivi
+    ETAPES = %i[flux_en_attente flux_irrecevable facture_introuvable facture_connue].freeze
+
+    attr_reader :etape, :statut_flux, :facture
+
+    # Un 404 sur le flux et une recherche vide sont des états du parcours, pas des erreurs : ils
+    # deviennent des étapes. Tout le reste — 401, 403, 5xx — continue de lever.
+    def self.pour(client, depot)
+      statut = client.flux.status(depot)
+      return new(etape: :flux_en_attente) if statut.nil?
+      return new(etape: :flux_irrecevable, statut_flux: statut) unless statut.recevable?
+
+      facture = premiere_facture(client, statut)
+      return new(etape: :facture_introuvable, statut_flux: statut) if facture.nil?
+
+      new(etape: :facture_connue, statut_flux: statut, facture: facture)
+    end
+
+    # `find` seul renseigne l'historique, et c'est lui qui porte les motifs.
+    def self.premiere_facture(client, statut)
+      return nil if statut.nom_flux.nil? || statut.nom_flux.empty?
+
+      resultat = client.factures.search_by_nom_flux(statut).first
+      resultat && client.factures.find(resultat)
+    end
+    private_class_method :premiere_facture
+
+    def initialize(etape:, statut_flux: nil, facture: nil)
+      raise ArgumentError, "étape inconnue : #{etape.inspect}" unless ETAPES.include?(etape)
+
+      @etape = etape
+      @statut_flux = statut_flux
+      @facture = facture
+    end
+
+    def en_attente?
+      etape == :flux_en_attente
+    end
+
+    def irrecevable?
+      etape == :flux_irrecevable
+    end
+
+    # Ambigu par nature : l'API répond 204 aussi bien parce que la facture n'est pas encore
+    # indexée que parce que le compte technique n'est rattaché à aucune des deux structures.
+    def introuvable?
+      etape == :facture_introuvable
+    end
+
+    def connue?
+      etape == :facture_connue
+    end
+
+    # Vrai que l'incident soit survenu au niveau de l'enveloppe ou à celui de la facture.
+    def en_echec?
+      irrecevable? || facture&.en_echec? || false
+    end
+
+    # Les motifs vivent à deux endroits selon l'endroit où le dépôt s'est arrêté : l'appelant n'a
+    # pas à savoir lequel.
+    def motifs
+      return statut_flux.motifs_rejet if irrecevable?
+
+      facture ? facture.motifs_rejet : []
+    end
+
+    # Le dernier changement de statut porteur de motifs. Nil à l'étape `:flux_irrecevable` : il
+    # n'y a alors pas de facture, et les motifs sont portés par le flux — `motifs` reste l'accès
+    # uniforme, quelle que soit l'étape atteinte.
+    def dernier_incident
+      facture&.dernier_incident
+    end
+
+    def nom_flux
+      statut_flux&.nom_flux
+    end
+
+    def to_s
+      [etape, facture&.statut, motifs.map(&:code).join(", ")].reject { |v| v.nil? || v.to_s.empty? }
+                                                             .join(" — ")
+    end
+  end
+end

data/lib/cpro/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cpro
-  VERSION = "0.2.4"
+  VERSION = "0.2.6"
 end

data/lib/cpro.rb

@@ -35,6 +35,7 @@ require_relative "cpro/resources/base"
 require_relative "cpro/resources/annuaire"
 require_relative "cpro/resources/flux"
 require_relative "cpro/resources/factures"
+require_relative "cpro/suivi"
 require_relative "cpro/client"
 
 module Cpro

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cpro-client
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.2.6
 platform: ruby
 authors:
 - Hôtentic
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-04 00:00:00.000000000 Z
+date: 2026-09-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -85,6 +85,7 @@ files:
 - lib/cpro/resources/base.rb
 - lib/cpro/resources/factures.rb
 - lib/cpro/resources/flux.rb
+- lib/cpro/suivi.rb
 - lib/cpro/version.rb
 homepage: https://hotentic.com
 licenses: