cpro-client 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a797bddcc8e42f168e7c6ac7e18f6a02de3f45b6dbe6bc03f4eb7f11a3854800
-  data.tar.gz: 25effc0a7fd95d27528d48c20d1289e236717ad7efbe3318d9a3284033ecf720
+  metadata.gz: 2bf1dbeeee478ffe838e25c8a2f7e08322fdd537a95fbe65aade589a212a9ce9
+  data.tar.gz: 60059eb5e04f2bc331bd8e17d17e891a24e4dfafa66c0fcfd3c4400f7f6d25cf
 SHA512:
-  metadata.gz: '095e98ac8c3752f4a117aab59f74bb77a15cd506bd5621637185e857261c8471d53850cbf5d42e2fcf72f054435ced5d060a26c659942224d80d3561813ea189'
-  data.tar.gz: e74b20cba8005d0d7b14b178d8e8e80e48b8f96a84f6c5cd859f7465abdaa1d1ed58d787c659a378b0896a592de9a61ee645266128d1241922a3665211992df2
+  metadata.gz: a420acaad23efa1b36a692ea7e29c74ea3039b3fab7b25e97c033e39b1e0e91d2eae2905fdf98dadf84bc61fd5d47e42e3ec5335c7c36246f1b7ee7311d77f05
+  data.tar.gz: 7e8ab7879a739be73e5b27cedbd8d57a47486c96ae7c8bb99e3abfad37743e8200115e6c5b561f5b851e42ae107b6bc06da44c09fe5a101705ab9d49d070110b

data/.gitignore

@@ -8,3 +8,4 @@
 /tmp/
 /.idea/
 /local/
+*.gem

data/.rubocop.yml

@@ -17,6 +17,11 @@ Style/Documentation:
 Layout/LineLength:
   Max: 120
 
+# Poser rubygems_mfa_required exigerait d'activer la MFA sur le compte RubyGems qui publie ;
+# ce n'est pas le mode de publication retenu ici.
+Gemspec/RequireMFA:
+  Enabled: false
+
 # Le fichier doit porter le nom de la gem pour que `require "cpro-client"` fonctionne.
 Naming/FileName:
   Exclude:

data/CHANGELOG.md

@@ -1,7 +1,33 @@
 ## [Unreleased]
 
+
+## [0.2.0] - 2026-08-27
+
+### Corrigé
+- Les filtres `siret` et `siren` des recherches d'annuaire partaient avec l'opérateur `contient`,
+  déclaré par le swagger mais refusé par la plateforme : tout appel les portant échouait en
+  `400 Failed to read HTTP message`. Ils utilisent désormais `strict`. `search_siret` et
+  `search_siren` étaient inutilisables sur ces critères en 0.1.0.
+
+### Ajouté
+- Recherche de codes routage : `Cpro::Resources::Annuaire#search_code_routage` et l'entité
+  `Cpro::Entities::CodeRoutage`. Seul accès au libellé lisible d'un code routage
+  (`libelleCodeRoutage`) et à son `gestionEngagementJuridique` — ni la consultation d'un
+  établissement ni celle d'un code routage ne les servent.
+- Tests sandbox couvrant les chemins de recherche de l'Annuaire, et garde-fou sautant un test
+  plutôt que de le faire échouer lorsque sa cassette est absente.
+
+### Documentation
+- README : la consultation et la recherche de l'Annuaire retournent des champs disjoints, ce qui
+  n'est pas une limite du jeu de données sandbox mais de la consultation. Adressage des structures
+  privées à la maille SIREN, et divergence d'opérateur avec le swagger.
+
+
+## [0.1.0] - 2026-08-27
+
+- Initial release
 - Authentification OAuth2 PISTE (`client_credentials`) avec cache du jeton, renouvellement anticipé
-  et rejeu unique d'un appel refusé en 401.
+    et rejeu unique d'un appel refusé en 401.
 - Compte technique `cpro-account` scopé par appel via `Cpro::Client#with_account`.
 - API Annuaire G2B : consultation par SIRET et par SIREN, recherche multi-critères, lignes
   d'annuaire paginées.
@@ -23,7 +49,3 @@
   enregistrement contre la vraie sandbox PISTE (`CPRO_RECORD=1`).
 - Hiérarchie d'erreurs `Cpro::Error` exposant statut HTTP, corps de réponse et identifiant de
   corrélation PISTE.
-
-## [0.1.0] - 2026-08-14
-
-- Initial release

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    cpro-client (0.1.0)
+    cpro-client (0.2.0)
       faraday (~> 2.0)
 
 GEM
@@ -25,6 +25,8 @@ GEM
     language_server-protocol (3.17.0.6)
     lint_roller (1.1.0)
     minitest (5.26.1)
+    nokogiri (1.15.7-arm64-darwin)
+      racc (~> 1.4)
     nokogiri (1.15.7-x86_64-darwin)
       racc (~> 1.4)
     parallel (1.28.0)
@@ -64,6 +66,7 @@ GEM
       hashdiff (>= 0.4.0, < 2.0.0)
 
 PLATFORMS
+  arm64-darwin-25
   x86_64-darwin-21
 
 DEPENDENCIES

data/README.md

@@ -52,11 +52,26 @@ Le compte technique doit être rattaché à une structure publique, faute de quo
 
 ## Annuaire
 
+**Consultation et recherche ne retournent pas les mêmes champs, et ne se remplacent pas.** C'est
+le point le moins intuitif de cette API :
+
+| | consultation (`find_by_…`) | recherche (`search_…`) |
+| --- | :-: | :-: |
+| identité — dénomination, adresse, état administratif | ✗ | ✓ |
+| `donneesB2gComplementaires` — engagement juridique, gestion du code service… | ✗ | ✓ |
+| `lignesAnnuaire` — les identifiants d'adressage | ✓ | ✗ |
+
+Il faut donc les deux appels pour avoir toute l'information d'une structure. La gem ne les
+enchaîne pas à votre place : c'est un état de la plateforme, pas une règle métier, et il changera.
+
+### Consultation
+
+Elle sert les lignes d'annuaire, c'est-à-dire les identifiants nécessaires à l'adressage d'une
+facture :
+
 ```ruby
 etablissement = client.annuaire.find_by_siret("70204275500240")
-etablissement.denomination
-etablissement.publique?
-etablissement.gestion_engagement_juridique?   # numéro d'engagement obligatoire ?
+etablissement.lignes_annuaire.map(&:identifiant_adressage)
 etablissement.lignes_annuaire.map(&:identifiant_routage)
 
 unite = client.annuaire.find_by_siren("702042755")
@@ -70,7 +85,13 @@ lignes.nombre_total
 lignes.suite?     # reste-t-il des lignes au-delà de cette page ?
 ```
 
-Recherche multi-critères — l'opérateur de comparaison (`contient` ou `strict`) est déduit du champ :
+Une structure sans ligne d'annuaire à la maille SIRET répond **404** en consultation par SIRET,
+tout en étant présente dans l'annuaire : c'est le cas des structures privées, dont l'adressage se
+fait à la maille SIREN. Cherchez-les alors par `search_siret`, ou consultez leur SIREN.
+
+### Recherche
+
+Elle sert l'identité et les données B2G :
 
 ```ruby
 resultat = client.annuaire.search_siret(
@@ -79,10 +100,37 @@ resultat = client.annuaire.search_siret(
   limite: 20
 )
 
-resultat.nombre_total
-resultat.map(&:siret)
+resultat.nombre_total     # nil si l'API ne le renseigne pas — ce n'est pas zéro
+resultat.first.denomination
+resultat.first.gestion_engagement_juridique?
+```
+
+L'opérateur de comparaison est déduit du champ. Les libellés se cherchent en `contient`, **les
+identifiants en `strict`** : le swagger déclare `contient` sur `siret` et `siren`, mais le serveur
+refuse cette forme par un `400 Failed to read HTTP message`. Un filtre inconnu lève une
+`ArgumentError` avant tout appel réseau.
+
+```ruby
+client.annuaire.search_siret(filtres: { siret: "70204275500240" })   # strict, implicitement
+```
+
+### Codes routage
+
+Un code routage est le troisième niveau de l'annuaire — le service, sous l'établissement. Sa
+recherche est le **seul** accès à son libellé lisible et à son engagement juridique : ni la
+consultation de l'établissement ni celle du code routage lui-même ne les servent.
+
+```ruby
+codes = client.annuaire.search_code_routage(filtres: { siret: "71915767420316" })
+
+codes.map(&:to_s)                          # => ["FACTURES_PUBLIQUES — Service des factures publiques", …]
+codes.first.libelle                        # "Service des factures publiques"
+codes.first.gestion_engagement_juridique?  # numéro d'engagement obligatoire pour ce service ?
+codes.first.actif?
 ```
 
+Filtrez sur `siret`, faute de quoi la réponse balaie tout l'annuaire.
+
 ## Transmission d'une facture Factur-X
 
 ```ruby
@@ -289,22 +337,50 @@ Chaîne complète validée le 14/08/2026 : dépôt d'un Factur-X accepté (`uidF
 - La **recevabilité porte sur l'enveloppe**, pas sur le contenu métier : un flux dont le vendeur est
   inconnu du destinataire ressort quand même `RECEVABLE`. Le sort de la facture elle-même se lit via
   l'API Recherche Factures G2B, à partir du `nomFlux`.
-
-### Limite actuelle de l'Annuaire
-
-En sandbox, `find_by_siret` et `find_by_siren` ne renvoient que le bloc `lignesAnnuaire` : `siret`,
+- Les filtres `siret` et `siren` des recherches d'annuaire n'acceptent que l'opérateur `strict`,
+  alors que le swagger déclare `contient` : cette forme est refusée par un
+  `400 Failed to read HTTP message`, une erreur de désérialisation levée avant tout traitement.
+- La **recherche d'annuaire est plus riche que la consultation**, et réciproquement : identité et
+  données B2G d'un côté, lignes d'annuaire de l'autre, sans recouvrement.
+- Le libellé d'un code routage et son `gestionEngagementJuridique` ne sont servis que par
+  `search_code_routage`. La consultation unitaire d'un code routage retourne moins que
+  `find_by_siret`, ce qui est la raison pour laquelle la gem ne l'expose pas.
+
+### Ce que la consultation ne dit pas
+
+`find_by_siret` et `find_by_siren` ne renvoient que le bloc `lignesAnnuaire` : `siret`,
 `denomination`, `adresse`, `uniteLegale` et `donneesB2gComplementaires` ressortent à `nil`, y
-compris pour la structure du compte appelant et même en précisant `champs`. Le mapping suit le
-swagger et se remplira si l'implémentation se complète ; en attendant, l'information exploitable est
-`lignes_annuaire`, qui porte les `identifiantAdressage` nécessaires à l'adressage de la facture.
+compris pour la structure du compte appelant et même en précisant `champs`.
+
+Ce n'est **pas** une limite du jeu de données : la recherche, elle, sert ces champs — mesuré sur la
+même structure, au même instant. C'est la consultation qui est incomplète. Passez donc par
+`search_siret` pour l'identité, et par la consultation pour les identifiants d'adressage :
 
 ```ruby
 client.annuaire.find_by_siret("71915767420316").lignes_annuaire.map(&:identifiant_adressage)
 # => ["719157674_71915767420316",
 #     "719157674_71915767420316_FACTURES_PUBLIQUES",
 #     "719157674_71915767420316_SERVICE_PUBLIQUE_1_71915767420316"]
+
+client.annuaire.search_siret(filtres: { siret: "71915767420316" }).first.denomination
+# => "Destinataire 71915767420316"
 ```
 
+### Adressage des structures privées
+
+En G2B, le destinataire est une entreprise privée. Sur le matelas de qualification, ces structures
+n'ont **aucune ligne d'annuaire à la maille SIRET** : leur seul identifiant d'adressage est le SIREN
+nu, et leur `statutPlateforme` vaut « Pas de plateforme ». Leur SIRET reste consultable par
+recherche, mais pas par `find_by_siret`, qui répond 404.
+
+```ruby
+client.annuaire.find_by_siren("474775418").lignes_annuaire.map(&:identifiant_adressage)
+# => ["474775418"]
+```
+
+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.
+
 ## Licence
 
 Disponible en open source sous les termes de la [licence MIT](https://opensource.org/licenses/MIT).

data/lib/cpro/entities/code_routage.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Cpro
+  module Entities
+    class CodeRoutage < Base
+      ETAT_ACTIF = "A"
+
+      def identifiant_routage
+        payload["identifiantRoutage"]
+      end
+
+      def libelle
+        payload["libelleCodeRoutage"]
+      end
+
+      def siret
+        payload["siret"]
+      end
+
+      def type_identifiant_routage
+        payload["typeIdentifiantRoutage"]
+      end
+
+      def etat_administratif
+        payload["etatAdministratif"]
+      end
+
+      def actif?
+        etat_administratif == ETAT_ACTIF
+      end
+
+      # La recherche de codes routage est le seul accès à cette information : ni la consultation
+      # d'un établissement ni celle d'un code routage ne la servent.
+      def gestion_engagement_juridique?
+        payload["gestionEngagementJuridique"]
+      end
+
+      def adresse
+        payload["adresse"] || {}
+      end
+
+      def code_postal
+        adresse["codePostal"]
+      end
+
+      def localite
+        adresse["localite"]
+      end
+
+      def etablissement
+        return nil unless payload["etablissement"]
+
+        @etablissement ||= Etablissement.new(payload["etablissement"])
+      end
+
+      def unite_legale
+        return nil unless payload["uniteLegale"]
+
+        @unite_legale ||= UniteLegale.new(payload["uniteLegale"])
+      end
+
+      def to_s
+        [identifiant_routage, libelle].compact.join(" — ")
+      end
+    end
+  end
+end

data/lib/cpro/resources/annuaire.rb

@@ -8,11 +8,17 @@ module Cpro
       SIRET_LENGTH = 14
       SIREN_LENGTH = 9
 
-      # Chaque champ filtrable n'admet qu'un seul opérateur dans le swagger : l'appelant fournit
-      # `siret: "702042755"` et l'opérateur attendu est déduit d'ici.
+      # Chaque champ filtrable n'admet qu'un seul opérateur : l'appelant fournit
+      # `siret: "70204275500240"` et l'opérateur attendu est déduit d'ici.
+      #
+      # `siret` et `siren` divergent du swagger, qui les déclare en `contient`. Le serveur refuse
+      # cette forme par un 400 « Failed to read HTTP message » — une erreur de désérialisation,
+      # levée avant tout traitement — et n'accepte que `strict`, sur les trois recherches de
+      # l'Annuaire. Vérifié en sandbox le 27/08/2026 ; ce sont des identifiants, une recherche
+      # partielle n'y a de toute façon pas de sens.
       OPERATEURS_SIRET = {
-        "siret" => "contient",
-        "siren" => "contient",
+        "siret" => "strict",
+        "siren" => "strict",
         "denomination" => "contient",
         "localite" => "contient",
         "codePostal" => "contient",
@@ -23,12 +29,22 @@ module Cpro
       }.freeze
 
       OPERATEURS_SIREN = {
-        "siren" => "contient",
+        "siren" => "strict",
         "raisonSociale" => "contient",
         "typeEntite" => "strict",
         "etatAdministratif" => "strict"
       }.freeze
 
+      OPERATEURS_CODE_ROUTAGE = {
+        "siret" => "strict",
+        "identifiantRoutage" => "contient",
+        "libelleCodeRoutage" => "contient",
+        "localite" => "contient",
+        "codePostal" => "contient",
+        "lignesAdresse" => "contient",
+        "etatAdministratif" => "strict"
+      }.freeze
+
       def find_by_siret(siret, **options)
         path = "siret/code-insee:#{normalize(siret, SIRET_LENGTH, "SIRET")}"
         Entities::Etablissement.new(get(path, query(options)))
@@ -52,6 +68,15 @@ module Cpro
         Entities::ResultatRecherche.new(payload, item_class: Entities::UniteLegale, total_key: TOTAL_KEY)
       end
 
+      # Seul accès au libellé d'un code routage et à son `gestionEngagementJuridique` : la
+      # consultation unitaire `GET /code-routage/siret:…/code:…` ne retourne que ses lignes
+      # d'annuaire, soit moins que `find_by_siret`. Filtrer sur `siret` pour se limiter à une
+      # structure, faute de quoi la réponse balaie tout l'annuaire.
+      def search_code_routage(filtres: {}, **options)
+        payload = post("code-routage/recherche", search_body(OPERATEURS_CODE_ROUTAGE, filtres, options))
+        Entities::ResultatRecherche.new(payload, item_class: Entities::CodeRoutage, total_key: TOTAL_KEY)
+      end
+
       def healthcheck
         get("healthcheck")
       end

data/lib/cpro/version.rb

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

data/lib/cpro.rb

@@ -16,6 +16,7 @@ require_relative "cpro/entities/ligne_annuaire"
 require_relative "cpro/entities/lignes_annuaire"
 require_relative "cpro/entities/unite_legale"
 require_relative "cpro/entities/etablissement"
+require_relative "cpro/entities/code_routage"
 require_relative "cpro/entities/note_statut"
 require_relative "cpro/entities/motif_rejet"
 require_relative "cpro/entities/changement_statut"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cpro-client
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Hôtentic
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-27 00:00:00.000000000 Z
+date: 2026-08-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -57,6 +57,7 @@ files:
 - lib/cpro/connection.rb
 - lib/cpro/entities/base.rb
 - lib/cpro/entities/changement_statut.rb
+- lib/cpro/entities/code_routage.rb
 - lib/cpro/entities/depot_flux.rb
 - lib/cpro/entities/etablissement.rb
 - lib/cpro/entities/facture.rb