cpro-client 0.2.3 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d6e3e9d0a4d4ff1848daa453f05afde782c62d4f17ee335981c7ff326cc9036
-  data.tar.gz: a9f2e83538efb36298ee64fd3df20ba04de571511c447ca4388e64295fa755f9
+  metadata.gz: fcf97fbee94114c1241fb76a3b3ec620dd7d8c2e40435bebfe146ce7b65a3e92
+  data.tar.gz: 0b3e4f80fe36110c60a46d7adc951cb0bd662093a30e39a0f19fb9e4c252096d
 SHA512:
-  metadata.gz: ad2b85661fc6009da13f5a44d284799d4149c9013ddc278a3350afd594c44ab830f7f010c1c0d8da3217da3af0fb259a08e22da568d876af09cf6665071c255b
-  data.tar.gz: 23f10b4ec03ac82f59a7e7be4dc7592e202ab05ee84beb1756c963055ef3c53b19a246006d8aa8f3920a7941723b4cdb86127de9be1597a358337b7f835932ca
+  metadata.gz: 4f010893e86d5f3dec2742aca27ea56606f6facb294c23cc613f91073d4ebf3b3f56dc1fdea650121b76a706680a65bd4921c875230a0e00beb428d4306f7876
+  data.tar.gz: 65724ca9625aa0328e6d3b14f10005f087614e589587f73e706b17d515b1091f3633f960bf9036a8031e30abdab360814856d076de551eaa0f5a860759b3a0a9

data/CHANGELOG.md

@@ -1,6 +1,30 @@
 ## [Unreleased]
 
 
+## [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.3)
+    cpro-client (0.2.5)
       faraday (>= 0.9, < 3.0)
 
 GEM

data/README.md

@@ -254,6 +254,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/adressage.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Cpro
+  # Situe une valeur d'adressage dans la hiérarchie de l'annuaire : SIREN → SIRET → service.
+  # Quatre formes sont acceptées — SIREN, SIRET, SIRET_SERVICE et SIREN_SIRET_SERVICE.
+  #
+  # Le service ne se lit jamais par découpage sur « _ » : il en contient lui-même
+  # (SERVICE_PUBLIQUE_1_71915767420316) et peut être purement numérique ("2026"). Il se lit comme
+  # tout ce qui suit le SIRET.
+  class Adressage
+    PREFIXE_SIREN = /\A(\d{9})_(?=\d{14})/.freeze
+    SIRET = /\A(\d{14})/.freeze
+    SIREN_SEUL = /\A(\d{9})\z/.freeze
+
+    attr_reader :siren, :siret, :service
+
+    def self.parse(valeur)
+      texte = valeur.to_s.strip
+      raise ArgumentError, "valeur d'adressage vide" if texte.empty?
+
+      prefixe = texte[PREFIXE_SIREN, 1]
+      reste = prefixe ? texte[10..] : texte
+      depuis_siret(prefixe, reste) || depuis_siren(reste) ||
+        raise(ArgumentError, "valeur d'adressage illisible : #{valeur.inspect} " \
+                             "(attendus : SIREN, SIRET, SIRET_SERVICE ou SIREN_SIRET_SERVICE)")
+    end
+
+    def self.depuis_siret(prefixe, reste)
+      siret = reste[SIRET, 1]
+      return nil if siret.nil?
+
+      raise ArgumentError, "SIREN #{prefixe} incohérent avec le SIRET #{siret}" if prefixe && prefixe != siret[0, 9]
+
+      new(siren: siret[0, 9], siret: siret, service: reste[14..].to_s.sub(/\A_/, ""))
+    end
+    private_class_method :depuis_siret
+
+    def self.depuis_siren(reste)
+      siren = reste[SIREN_SEUL, 1]
+      siren && new(siren: siren, siret: nil, service: nil)
+    end
+    private_class_method :depuis_siren
+
+    def initialize(siren:, siret: nil, service: nil)
+      @siren = siren
+      @siret = siret
+      @service = service.nil? || service.empty? ? nil : service
+    end
+
+    # Du plus précis au plus général : la valeur elle-même, puis ses parents successifs. C'est
+    # l'ordre dans lequel une adresse active est cherchée.
+    def paliers
+      [
+        (self.class.new(siren: siren, siret: siret, service: service) if service),
+        (self.class.new(siren: siren, siret: siret) if siret),
+        self.class.new(siren: siren)
+      ].compact
+    end
+
+    # Une ligne d'annuaire correspond à ce palier si elle décrit le même niveau de précision.
+    def correspond?(ligne)
+      ligne.siret == siret && ligne.identifiant_routage.to_s.empty? == service.nil? &&
+        (service.nil? || ligne.identifiant_routage == service)
+    end
+
+    def to_s
+      [siret ? "#{siren}_#{siret}" : siren, service].compact.join("_")
+    end
+  end
+end

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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cpro
-  VERSION = "0.2.3"
+  VERSION = "0.2.5"
 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.3
+  version: 0.2.5
 platform: ruby
 authors:
 - Hôtentic
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-03 00:00:00.000000000 Z
+date: 2026-09-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -53,6 +53,7 @@ files:
 - lib/cpro-client.rb
 - lib/cpro.rb
 - lib/cpro/account.rb
+- lib/cpro/adressage.rb
 - lib/cpro/archive.rb
 - lib/cpro/auth/token.rb
 - lib/cpro/auth/token_provider.rb