cpro-client 0.2.5 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fcf97fbee94114c1241fb76a3b3ec620dd7d8c2e40435bebfe146ce7b65a3e92
-  data.tar.gz: 0b3e4f80fe36110c60a46d7adc951cb0bd662093a30e39a0f19fb9e4c252096d
+  metadata.gz: 56e12349c80b29ebc7190354cefea789a6a9114d42260bc40e2851529255a043
+  data.tar.gz: 35ec2d79aace35593b9493dd6e07b3ede842726ba9b2cc9b63491ca269844272
 SHA512:
-  metadata.gz: 4f010893e86d5f3dec2742aca27ea56606f6facb294c23cc613f91073d4ebf3b3f56dc1fdea650121b76a706680a65bd4921c875230a0e00beb428d4306f7876
-  data.tar.gz: 65724ca9625aa0328e6d3b14f10005f087614e589587f73e706b17d515b1091f3633f960bf9036a8031e30abdab360814856d076de551eaa0f5a860759b3a0a9
+  metadata.gz: e3372fac6b533cb8b24b08dbae14c2dce8f495a93d4b53161d553b874ab208bee3099f53efa0af7159e4690cd5aea8414c9da2fef33a38c8cd875796aff99d60
+  data.tar.gz: fae64931447cd4708e173bca2790890bad33ed65bbc370ad49dc40e60a1f12185af579d947eec2a766fbb79f1dd5da07f77e1c99d18a54678532866b664ae206

data/CHANGELOG.md

@@ -1,6 +1,40 @@
 ## [Unreleased]
 
 
+## [0.2.7] - 2026-09-07
+
+### Ajouté
+- `Cpro::Suivi#orientation` nomme la situation d'un dépôt en une valeur sur laquelle brancher —
+  `:en_attente`, `:enveloppe_irrecevable`, `:facture_introuvable`, `:en_cours`, `:rejetee`,
+  `:non_transmise`, `:erreur_routage`, `:transmise` — en aplatissant l'étape du suivi et l'état de
+  la facture. Ne repose que sur des codes : statut, code motif, étape. Un statut d'acheminement
+  l'emporte sur un `NON_TRANSMISE` devenu caduc, et c'est l'incident courant qui décide.
+
+  Deux distinctions restent à l'appelant : séparer les deux `NON_TRANSMISE` supposerait de lire le
+  texte d'une note rédigée par l'AIFE, et séparer un rejet corrigeable d'un rejet définitif repose
+  sur une lecture de la spécification que nous n'avons pas mesurée.
+- `CHORUS_PRO.md` — les séquences de statuts et de motifs renvoyées par la plateforme, scénario par
+  scénario, en distinguant les relevés sandbox des comportements seulement documentés.
+
+
+## [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é

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    cpro-client (0.2.5)
+    cpro-client (0.2.7)
       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
 
@@ -270,6 +283,24 @@ 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
 ```
 
+Pour brancher directement sans reconstruire le même `if` dans chaque application,
+`orientation` aplatit l'étape et l'état de la facture en une valeur :
+
+```ruby
+case suivi.orientation
+when :en_attente, :en_cours, :facture_introuvable then reprogrammer_le_suivi
+when :enveloppe_irrecevable, :rejetee            then signaler(suivi.motifs)
+when :non_transmise                              then preparer_un_duplicata
+when :erreur_routage                             then alerter
+when :transmise                                  then classer
+end
+```
+
+Elle ne repose que sur des codes — statut, code motif, étape — jamais sur le texte d'une note.
+Deux distinctions restent donc à l'appelant, et [CHORUS_PRO.md](CHORUS_PRO.md) explique comment les
+obtenir : séparer les deux causes de `:non_transmise`, et distinguer un rejet corrigeable d'un rejet
+définitif.
+
 `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 :
 
@@ -456,6 +487,12 @@ client.annuaire.find_by_siren("474775418").lignes_annuaire.map(&:identifiant_adr
 C'est cet identifiant qui doit alimenter BT-49 sur la facture et MDT-73 sur le cycle de vie.
 Vérifiez `plateforme_active?` avant de compter sur un acheminement.
 
+## Comportements de la plateforme
+
+[CHORUS_PRO.md](CHORUS_PRO.md) rassemble, scénario par scénario, la séquence de statuts et de motifs
+que renvoie réellement la plateforme — enveloppe irrecevable, adressage introuvable, destinataire
+non raccordé, doublon — en distinguant ce qui a été mesuré en sandbox de ce qui n'est que documenté.
+
 ## Licence
 
 Disponible en open source sous les termes de la [licence MIT](https://opensource.org/licenses/MIT).

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,151 @@
+# 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
+
+    ORIENTATIONS = %i[en_attente enveloppe_irrecevable facture_introuvable en_cours
+                      rejetee non_transmise erreur_routage transmise].freeze
+
+    # Statuts qui prouvent que la facture a quitté Chorus Pro : d'après la colonne « Sens flux »
+    # de l'annexe des statuts, ils proviennent de la plateforme du destinataire ou constatent
+    # l'émission par la plateforme.
+    #
+    # `APPROUVEE`, `REFUSEE` et `VISEE` circulent dans les deux sens. Ils figurent ici parce que
+    # les recevoir est le cas courant, et que les omettre ferait passer une facture refusée par
+    # l'acheteur pour une facture encore en cours. Une application qui les émet elle-même le sait.
+    STATUTS_TRANSMISE = %w[
+      EMISE_PAR_LA_PLATEFORME RECUE_DE_LA_PLATEFORME MISE_A_DISPOSITION PRISE_EN_CHARGE
+      APPROUVEE APPROUVEE_PARTIELLEMENT EN_LITIGE SUSPENDUE PAIEMENT_TRANSMIS REFUSEE VISEE
+    ].freeze
+
+    MOTIF_NON_TRANSMISE = "NON_TRANSMISE"
+    STATUT_ERREUR_ROUTAGE = "ERREUR_ROUTAGE"
+
+    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
+
+    # Nomme la situation en une valeur sur laquelle brancher, l'étape du suivi et l'état de la
+    # facture étant aplatis ensemble. Ne repose que sur des codes — statut, code motif, étape.
+    #
+    # Deux distinctions sont délibérément laissées à l'appelant, parce que les porter ici serait
+    # fragile :
+    #
+    # - séparer les deux `NON_TRANSMISE` — destinataire sans plateforme, qui ne recevra jamais, ou
+    #   plateforme non encore raccordée, qui recevra plus tard — suppose de lire le texte d'une
+    #   note rédigée par l'AIFE. L'annuaire le dit plus sûrement avant le dépôt, par
+    #   `Annuaire#find_identifiant_adressage(siret).statut_plateforme` ;
+    # - séparer un rejet corrigeable d'un rejet définitif repose sur l'idée qu'un rejet de
+    #   conformité n'intègre pas la facture et ne consomme donc pas son numéro. La spécification
+    #   le laisse entendre, nous ne l'avons pas mesuré.
+    #
+    # `motifs` et `dernier_incident` restent disponibles pour qui veut trancher lui-même.
+    def orientation
+      case etape
+      when :flux_en_attente then :en_attente
+      when :flux_irrecevable then :enveloppe_irrecevable
+      when :facture_introuvable then :facture_introuvable
+      else orientation_facture
+      end
+    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
+
+    private
+
+    # L'ordre compte : un statut d'acheminement l'emporte sur un NON_TRANSMISE devenu caduc, et
+    # c'est l'incident courant — non le cumul de l'historique — qui décrit la situation présente.
+    def orientation_facture
+      return :erreur_routage if facture.statut == STATUT_ERREUR_ROUTAGE
+      return :rejetee if facture.rejetee?
+      return :transmise if STATUTS_TRANSMISE.include?(facture.statut)
+      return :non_transmise if non_transmise?
+
+      :en_cours
+    end
+
+    def non_transmise?
+      dernier_incident&.motifs_rejet.to_a.any? { |motif| motif.code == MOTIF_NON_TRANSMISE }
+    end
+  end
+end

data/lib/cpro/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cpro-client
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.2.7
 platform: ruby
 authors:
 - Hôtentic
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-05 00:00:00.000000000 Z
+date: 2026-09-07 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: