cpro-client 0.2.5 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fcf97fbee94114c1241fb76a3b3ec620dd7d8c2e40435bebfe146ce7b65a3e92
-  data.tar.gz: 0b3e4f80fe36110c60a46d7adc951cb0bd662093a30e39a0f19fb9e4c252096d
+  metadata.gz: 1f1452657739318ca5d2a71a6673d046dea03e4f5e3b00befc41ae210fcf3ee4
+  data.tar.gz: b36804bf664635e9d5f510fe8a8ed2e52a6aeb1753b9de3bc3b919475d3e51cb
 SHA512:
-  metadata.gz: 4f010893e86d5f3dec2742aca27ea56606f6facb294c23cc613f91073d4ebf3b3f56dc1fdea650121b76a706680a65bd4921c875230a0e00beb428d4306f7876
-  data.tar.gz: 65724ca9625aa0328e6d3b14f10005f087614e589587f73e706b17d515b1091f3633f960bf9036a8031e30abdab360814856d076de551eaa0f5a860759b3a0a9
+  metadata.gz: 918adeba480ffaaec7508e21e68c31799708e568fb4dc5f2678072ab9f10971f31a03c8af893e57548cce0d5c93b9ad2b9d5387a50a7d629f40f945dfb16b93a
+  data.tar.gz: 299ffdbbc8b8c9f25b24c09d1577fdd4e0d1f3b9bc9f3b0eed7c6d607f428e86e87d1a1978bb55c10ab6e450bdb24c996b5909673113031cfb375bb65ab30255

data/CHANGELOG.md

@@ -1,6 +1,24 @@
 ## [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é

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    cpro-client (0.2.5)
+    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
 

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.5"
+  VERSION = "0.2.6"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cpro-client
 version: !ruby/object:Gem::Version
-  version: 0.2.5
+  version: 0.2.6
 platform: ruby
 authors:
 - Hôtentic
@@ -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: