cpro-client 0.2.8 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 629795027a48606736ffd0273cd3bf2b1e457237508f428978a4bdbce3245f56
-  data.tar.gz: 5a3a218220129860479c710a68aaf4eb612ab74f2f6c8a812a7aa65e2f90f7a0
+  metadata.gz: 2f8a0732008b70f7a94ea7689d1ecd6675d6a8f6203330ada88e66976baf3d0c
+  data.tar.gz: 0fbef1fe26a7ea78cbfe8b5e472dbe5daa6ebb09ce166d00f9133932f7f03c79
 SHA512:
-  metadata.gz: 23cc35215eb0530f66b71677d35948c1da2896c626a400018901de87c1e2ed8d517ffcb3eefe5f02d5978a7e1f966c513fd8cb1c114aa3950294fb0805915f21
-  data.tar.gz: 89a63f46184b02fb02ce615a964148f3ee3997899855312bacd77f3c41d5a7da6cd1b0ee255040fcf2304d3fa05541b13fbb57915ebca9b0c5187b7c07a20b80
+  metadata.gz: 555fc82d332aa7a0c17a679fc87f405cffcfb0c97589f0266b01056a20ef53237809c4a17e09149b24121efe045fb6fa8d8b18f0b7753550bf01c74b3e1b75f0
+  data.tar.gz: 13b6e6d2fa7a66b87d30fae3e03e9561f6666d6f019e0e3918d1d7dce8e43e6a063042de58e72984aebfc873f62ae36d6d4f243defcde3a82390d3f2f797cb4f

data/CHANGELOG.md

@@ -1,6 +1,60 @@
 ## [Unreleased]
 
 
+## [0.3.0] - 2026-10-12
+
+### Ajouté
+- `Cpro::Resources::Flux#deposit_facturx` confronte l'adresse de l'acheteur (BT-49) à l'annuaire
+  avant de déposer, et lève une `Cpro::AdressageError` si elle est absente, hors schemeID `0225`,
+  privée de SIREN, ou inconnue. Chorus Pro ne la contrôle qu'au traitement, plusieurs minutes après
+  le dépôt : la facture est alors rejetée `ADR_ERR` ou `REJ_ADR`, et son numéro consommé — mesuré
+  le 30/08/2026. Le message dit ce qui bloque et que faire ; `motif` permet de brancher, et
+  `adresses_connues` liste les adresses de l'annuaire pour régénérer la facture. Toutes les pages de
+  lignes sont parcourues, et la comparaison se fait mot pour mot, forme SIREN_SUFFIXE comprise.
+
+  **Le contrôle est actif par défaut** et coûte un appel à l'Annuaire par dépôt ;
+  `verifier_adressage: false` s'en dispense. Une erreur de l'annuaire remonte telle quelle et
+  empêche le dépôt.
+- `Cpro::Facturx.adresse_acheteur` lit BT-49 et son schemeID dans le XML embarqué, quel que soit le
+  préfixe d'espace de noms, en ignorant l'adresse du vendeur et le courriel du contact acheteur.
+
+### Modifié
+- `Cpro::Resources::Annuaire#find_identifiant_adressage` suit l'ordre que recommande le dossier de
+  spécifications externes (§3.1.2) pour adresser un SIRET. Un établissement sans adresse propre
+  (`SIREN_SIRET`) est désormais adressé à son premier code routage par ordre alphanumérique
+  (`SIREN_SIRET_CodeRoutage`) avant de remonter au SIREN ; la résolution ne faisait jusqu'ici que
+  remonter. Seuls les codes routage de l'établissement visé comptent, et un SIREN nu ne descend
+  toujours pas vers ses établissements. **L'adresse rendue change** pour un SIRET qui n'a que des
+  codes routage.
+
+### Corrigé
+- `Cpro::Resources::Annuaire#find_identifiant_adressage` pouvait rendre une adresse SIREN_SUFFIXE
+  au palier SIREN : sans SIRET ni code routage, elle ressemblait à la ligne SIREN nue, et
+  l'emportait si l'annuaire la listait en premier. Les adresses à suffixe sortent de la hiérarchie
+  SIREN → SIRET → service et ne servent plus qu'en dernier recours, la première par ordre
+  alphanumérique, comme le recommande le dossier de spécifications externes (§3.1.2). Une ligne
+  est reconnue à suffixe par son champ `suffixeAdressage`, ou à défaut par sa forme
+  (`Cpro::Entities::LigneAnnuaire#suffixe?`).
+- `Cpro::Client#suivi` classait en `:flux_irrecevable` tout flux qui n'était pas `RECEVABLE` — y
+  compris `ENTRANT_ENVELOPPE_VALIDE`, le statut intermédiaire que déclare le swagger, sans aucun
+  motif à l'appui. L'appelant, invité à corriger et redéposer, aurait vu son second dépôt refusé
+  en doublon. Seul `IRRECEVABLE` mène désormais à `:flux_irrecevable` ; tout autre statut laisse le
+  flux en `:flux_en_attente`, le statut brut restant lisible par `statut_flux`.
+
+### Modifié
+- Le message des erreurs d'API nomme la requête qui a échoué, méthode et chemin sans la requête :
+  `400 Unexpected value 'EN_COURS_TRAITEMENT' (GET /g2b/flux/v1/flux/…)`. Relevé en production :
+  `suivi` enchaîne trois appels, et l'erreur lue dans les journaux de l'hôte ne disait pas lequel
+  avait levé. Un message vide ne laisse plus d'espace final.
+
+### Documentation
+- `:deposee` ne veut plus dire que « l'acheminement n'a pas encore eu lieu », comme l'annonçait la
+  0.2.8. D'après la spécification, une facture `DEPOSEE` sans motif est émise vers la plateforme
+  du destinataire, et l'annexe des statuts déclare facultatifs tous ceux qui le confirmeraient —
+  `EMISE_PAR_LA_PLATEFORME`, `RECUE_DE_LA_PLATEFORME`, `MISE_A_DISPOSITION`, `PRISE_EN_CHARGE`.
+  L'acheminement n'est donc ni prouvé ni exclu. `Suivi#orientation` ne change pas de comportement.
+
+
 ## [0.2.8] - 2026-09-25
 
 ### Ajouté
@@ -12,11 +66,11 @@
 - `Cpro::Suivi#orientation` cesse de traiter `:en_cours` comme un fourre-tout, qui absorbait neuf
   statuts sur vingt-deux — dont `ENCAISSEE`, une facture payée ressortant « en cours ». Deux
   valeurs s'ajoutent :
-- **`:deposee`** — `DEPOSEE` sans aucun motif. Le dépôt a réussi, la plateforme n'a rien à
-  signaler, l'acheminement n'a pas encore eu lieu ;
-- **`:cycle_de_vie`** — `ENCAISSEE`, `COMPLETEE`, `ANNULEE`, `CHANGEMENT_DE_COMPTE_A_PAYER`, les
-  statuts que seul le vendeur pose. Ils ne prouvent pas l'acheminement : on encaisse une facture
-  jamais transmise après remise d'un duplicata.
+  - **`:deposee`** — `DEPOSEE` sans aucun motif. Le dépôt a réussi, la plateforme n'a rien à
+    signaler, l'acheminement n'a pas encore eu lieu ;
+  - **`:cycle_de_vie`** — `ENCAISSEE`, `COMPLETEE`, `ANNULEE`, `CHANGEMENT_DE_COMPTE_A_PAYER`, les
+    statuts que seul le vendeur pose. Ils ne prouvent pas l'acheminement : on encaisse une facture
+    jamais transmise après remise d'un duplicata.
 
   `:en_cours` ne garde que `DEMANDE_DE_PAIEMENT_DIRECT` et les trois statuts d'affacturage, sur
   lesquels nous n'avons ni mesure ni lecture. Un statut posé par le vendeur l'emporte désormais sur
@@ -81,6 +135,12 @@
   par `Factures#find`.
 
 
+## [0.2.4] - 2026-09-04
+
+### Corrigé
+- Republication de la 0.2.3, dont le paquet publié était incomplet. Aucun changement de code.
+
+
 ## [0.2.3] - 2026-08-31
 
 ### Ajouté

data/CHORUS_PRO.md

@@ -67,7 +67,7 @@ précède.
 | **Destinataire sans plateforme** *(mesuré 04/09)* | `RECEVABLE` (500) | `DEPOSEE` [`NON_TRANSMISE`] | **conforme** — jamais transmise, duplicata à la charge de l'émetteur |
 | **Plateforme non raccordée** *(mesuré 04/09)* | `RECEVABLE` (500) | `DEPOSEE` [`NON_TRANSMISE`] | **conforme** — sera transmise au raccordement de la plateforme |
 | **Doublon** *(mesuré 04/09)* | `RECEVABLE` (500) | `DEPOSEE` [`REJ_UNI`] | le triptyque est déjà pris |
-| **Transmise** *(documenté)* | `RECEVABLE` (500) | `DEPOSEE`, puis les statuts que la plateforme et le destinataire posent | nominal — **jamais observé en sandbox**, et l'ordre exact n'est pas documenté |
+| **Transmise** *(documenté)* | `RECEVABLE` (500) | `DEPOSEE` sans motif, puis éventuellement les statuts que la plateforme et le destinataire posent — tous facultatifs | nominal — émise vers la plateforme du destinataire, sans accusé obligatoire ; **acheminement jamais vérifié** |
 | **Non-conformité** *(documenté)* | `RECEVABLE` (500) | `REJETEE` | la facture n'est pas intégrée ; retransmission après correction possible |
 | **Routage impossible** *(documenté)* | `RECEVABLE` (500) | `ERREUR_ROUTAGE` (221) | terminal |
 
@@ -108,7 +108,7 @@ couple **statut × motif**.
 
 | Cas | Statut | Motif | Comment le distinguer |
 | --- | --- | --- | --- |
-| **En cours** | `DEPOSEE` | aucun | rien à faire, réinterroger |
+| **Déposée sans incident** | `DEPOSEE` | aucun | émise vers le destinataire d'après la spécification, sans que rien le confirme ; réinterroger |
 | **Rejet corrigeable** | `REJETEE` | conformité *(documenté)* | la facture n'est pas intégrée : corriger et redéposer sous le même numéro |
 | **Rejet définitif** | `REJETEE` | `REJ_ADR` *(mesuré)* | la facture est intégrée, son numéro est consommé : avoir + nouvelle facture |
 | | `ERREUR_ROUTAGE` | — | acheminée mais non routable chez le destinataire |
@@ -125,6 +125,11 @@ couple **statut × motif**.
 D'après la colonne « Sens flux » de l'annexe, ces statuts proviennent de la plateforme du
 destinataire ou constatent l'émission par Chorus Pro. Les recevoir prouve que la facture est partie.
 
+**La réciproque est fausse.** Hormis `REFUSEE` (210), l'annexe les déclare tous **facultatifs** : ni
+Chorus Pro ni la plateforme du destinataire ne sont tenus de les poser. Une facture qui n'en reçoit
+aucun peut très bien être arrivée — la spécification (§3.2.3.3.2) prévoit qu'en cas nominal Chorus
+Pro appose `DEPOSEE` puis émet la facture, sans autre statut.
+
 ```ruby
 TRANSMISE = %w[
   EMISE_PAR_LA_PLATEFORME RECUE_DE_LA_PLATEFORME MISE_A_DISPOSITION PRISE_EN_CHARGE
@@ -150,7 +155,7 @@ sont en revanche jamais des preuves d'acheminement.
 | `:en_attente` | flux non encore jugé | réinterroger |
 | `:enveloppe_irrecevable` | flux `IRRECEVABLE` | corriger le fichier, redéposer |
 | `:facture_introuvable` | recherche vide | réinterroger, puis vérifier le rattachement du compte |
-| `:deposee` | `DEPOSEE` sans motif | réinterroger — dépôt réussi, acheminement en attente |
+| `:deposee` | `DEPOSEE` sans motif | réinterroger — dépôt réussi, acheminement ni prouvé ni exclu |
 | `:cycle_de_vie` | statut posé par le vendeur | la facture vit sa vie commerciale |
 | `:en_cours` | statut non classé | ne rien en déduire |
 | `:rejetee` | statut `REJETEE` | lire les motifs |
@@ -160,11 +165,11 @@ sont en revanche jamais des preuves d'acheminement.
 
 ```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
+when :en_attente, :facture_introuvable, :deposee, :en_cours 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, :cycle_de_vie                             then classer
 end
 ```
 
@@ -205,7 +210,8 @@ pris, ce qui se traite indépendamment de l'orientation.
 **Ce qui est mesuré et ce qui ne l'est pas.** Seuls `REJETEE`/`REJ_ADR`, `DEPOSEE`/`NON_TRANSMISE`
 dans ses deux variantes et `DEPOSEE`/`REJ_UNI` ont été observés. Le rejet de conformité,
 `ERREUR_ROUTAGE` et l'ensemble des statuts d'acheminement sont déduits de l'annexe et de la
-spécification, jamais vus en sandbox.
+spécification, jamais vus en sandbox. `DEPOSEE` sans motif a été relevé en production, sans que
+l'on sache encore si les factures concernées sont parvenues à leur destinataire.
 
 ## Motifs rencontrés
 
@@ -260,6 +266,12 @@ que le `nomFlux`, dont le format doit changer.
 
 **Allotir.** La spécification recommande un maximum de 500 factures par flux.
 
+**BT-23 ne dépend pas du circuit.** La lettre dit ce qui est facturé, pas par quel circuit :
+le swagger Recherche Factures énumère `B1 S1 M1 B2 S2 M2 B4 S4 M4 S5 S6 B7 S7` pour
+`typeProcessusMetier` — **B**iens, **S**ervices, **M**ixte, déclinés par numéro de processus. `S1`
+est donc valide en G2B, et l'exemple d'AIFE porte `B1` parce que sa facture de test concerne des
+biens.
+
 **Un destinataire public ne se facture pas en G2B.** Relevé en production le 25/09 :
 
 > `ROUTAGE_ERR` — « Il n'est pas possible de transmettre des factures intra sphère publique par ce
@@ -273,15 +285,18 @@ qui vaut `Publique` ou `Privée assujettie` — et seule la **recherche** la ser
 laissant le champ nul.
 
 **Un rejet n'est pas une étape plus avancée qu'un dépôt.** `REJETEE` et `ERREUR_ROUTAGE` prouvent
-que la plateforme a traité la facture, jamais qu'elle l'a transmise. Pour mesurer si un circuit
-fonctionne, ne comptez que les statuts de `Suivi::STATUTS_TRANSMISE` — tout le reste, y compris les
-échecs, laisse la question ouverte.
+que la plateforme a traité la facture, jamais qu'elle l'a transmise. Seuls les statuts de
+`Suivi::STATUTS_TRANSMISE` prouvent l'acheminement, mais ils sont facultatifs : les compter donne un
+minimum, pas une mesure du circuit. Leur absence ne permet de rien conclure.
 
 **Une facture peut rester `DEPOSEE` indéfiniment, sans aucun motif.** Relevé en production : une
 facture déposée le 18/09 était encore `DEPOSEE` avec un `detailStatut` vide une semaine plus tard.
-Chorus Pro n'a alors rien à dire, et aucune API ne donne de raison. La seule piste est l'annuaire :
-si le destinataire n'a pas de plateforme active, la facture n'ira nulle part — même sans motif
-`NON_TRANSMISE` pour le signaler. `local/sonde_bloquees.rb` automatise ce recoupement.
+C'est ce que la spécification décrit pour le cas nominal — `DEPOSEE`, puis émission vers la
+plateforme du destinataire, les statuts suivants étant facultatifs. Ce n'est donc pas en soi le
+signe d'un blocage, mais aucune API ne permet de vérifier l'arrivée : seul le destinataire le peut.
+L'annuaire sert à écarter les autres cas : face à un destinataire sans plateforme active, la
+spécification prévoit le motif `NON_TRANSMISE`, et son absence serait une anomalie.
+`local/sonde_bloquees.rb` automatise ce recoupement.
 
 **Une requête hors bornes donne un 500, pas un 400.** `limite` est plafonné à 50 sur
 `POST /facture/recherche` ; au-delà, la plateforme répond `500 Erreur interne` sans rien expliquer.
@@ -289,6 +304,18 @@ Le même comportement a été relevé sur l'Annuaire, où un filtre `siret` priv
 donne également un 500. **Ne lisez pas un 500 comme une panne avant d'avoir vérifié votre requête
 contre le swagger.** `Factures#search` refuse désormais localement une pagination hors bornes.
 
+**L'Annuaire G2B peut ignorer une entreprise que l'annuaire en ligne connaît.** Relevé en
+production le 12/10 : pour une SAS active et diffusible, dont l'annuaire en ligne de Chorus Pro
+affiche une adresse, `GET /siren/code-insee:` et `GET /siret/code-insee:` répondent tous deux 404
+— l'unité légale entière est absente de la vue G2B, pas seulement l'établissement. L'API Super PDP
+voit au même moment une seule ligne, au niveau SIREN, inactive. L'explication la plus probable,
+non confirmée : l'API ne rend que « les lignes courantes et celles étant en attente d'activation
+sous un délai de 7 jours » (Annexe API V6.1, §3.2.1), et cette ligne n'entre pas encore dans cette
+fenêtre. `find_identifiant_adressage` rend alors `nil`, et le contrôle d'adresse de
+`deposit_facturx` bloque en `:siren_inconnu` — c'est voulu : Chorus Pro contrôlera l'adresse au
+traitement. Une facture générée sur le SIREN de l'acheteur pourra partir quand la ligne entrera
+dans la vue G2B.
+
 **Le 204 de Recherche Factures est ambigu** : aucune facture correspondante, ou compte technique
 rattaché ni à la structure émettrice ni à la destinataire. Rien ne permet de les distinguer.
 

data/Gemfile.lock

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

data/README.md

@@ -140,11 +140,22 @@ Filtrez sur `siret`, faute de quoi la réponse balaie tout l'annuaire.
 
 BT-49, l'adresse électronique de l'acheteur, ne se transmet pas à l'API : elle voyage dans le XML
 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.
+rejetée `REJ_ADR` — « le destinataire n'est pas trouvable » — plusieurs minutes après le dépôt, et
+son numéro est consommé. `deposit_facturx` le vérifie donc avant d'envoyer quoi que ce soit (voir
+[plus bas](#contrôle-de-ladresse-avant-dépôt)).
 
 `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 :
+valeur d'adressage — SIREN, SIRET, SIRET_SERVICE, SIREN_SIRET_SERVICE — et rend l'adresse la plus
+proche que l'annuaire connaisse, dans l'ordre que recommande le dossier de spécifications externes
+(§3.1.2) pour adresser un SIRET :
+
+| Ordre | Adresse retenue |
+| :-: | --- |
+| 1 | le service demandé, si la valeur en porte un : `SIREN_SIRET_SERVICE` |
+| 2 | l'adresse propre de l'établissement : `SIREN_SIRET` |
+| 3 | à défaut, son premier code routage par ordre alphanumérique : `SIREN_SIRET_CodeRoutage` |
+| 4 | à défaut, l'entreprise : `SIREN` |
+| 5 | à défaut, la première adresse à suffixe par ordre alphanumérique : `SIREN_Suffixe` |
 
 ```ruby
 ligne = client.annuaire.find_identifiant_adressage("71915767420316")
@@ -155,8 +166,13 @@ client.annuaire.find_identifiant_adressage("71915767420316_SERVICE_INEXISTANT").
 # => "719157674_71915767420316" — service inconnu, on retombe sur son parent
 ```
 
-**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
+Les codes routage pris en compte à l'étape 3 sont ceux de l'établissement visé, jamais ceux d'un
+autre établissement de la même entreprise. Un SIREN nu, lui, ne descend pas vers ses
+établissements : il ne rend rien si l'entreprise n'a d'adresses qu'au niveau SIRET.
+
+**Le statut de plateforme départage, il n'exclut pas.** Une adresse dont la plateforme est active
+l'emporte, même plus éloignée dans l'ordre ci-dessus ; mais si aucune ne l'est, l'adresse la plus
+proche 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
@@ -174,9 +190,6 @@ Pour distinguer « unité légale inconnue » de « connue mais sans adresse exp
 `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
 
 ```ruby
@@ -198,6 +211,58 @@ attend :
 Cpro::Facturx.montant_total(File.binread("facture.pdf"))   # => BigDecimal("1910.40")
 ```
 
+### Contrôle de l'adresse avant dépôt
+
+Chorus Pro ne contrôle l'adresse de l'acheteur (BT-49) qu'au traitement, plusieurs minutes après le
+dépôt. Absente, la facture est rejetée `ADR_ERR` ; inconnue de l'annuaire, `REJ_ADR`. Dans les deux
+cas son **numéro est consommé** : la redéposer sous le même numéro échoue, il faut un avoir et une
+nouvelle facture.
+
+`deposit_facturx` lit donc BT-49 dans le XML embarqué et le confronte à l'annuaire avant de
+déposer, au prix d'un appel. La comparaison se fait mot pour mot sur toutes les lignes de l'unité
+légale, forme SIREN_SUFFIXE comprise. Si l'adresse ne passe pas, il lève une
+`Cpro::AdressageError` — rien n'est parti, le numéro reste disponible :
+
+```ruby
+begin
+  client.flux.deposit_facturx("facture.pdf")
+rescue Cpro::AdressageError => e
+  e.message           # "Dépôt bloqué : l'adresse électronique de l'acheteur (BT-49) « 474775418 »
+                      #  est inconnue de l'annuaire. Adresses connues pour le SIREN 474775418 : …"
+  e.motif             # :adresse_inconnue
+  e.identifiant       # "474775418" — l'adresse portée par la facture
+  e.adresses_connues  # ["474775418_47477541867167"] — de quoi régénérer la facture
+end
+```
+
+| `motif` | Cause | Suite |
+| --- | --- | --- |
+| `:adresse_absente` | la facture ne porte pas de BT-49 | régénérer la facture |
+| `:schema_invalide` | BT-49 n'est pas en schemeID `0225` (BR-FR-21) | régénérer la facture |
+| `:siren_absent` | BT-49 ne commence pas par un SIREN (BR-FR-21) | régénérer la facture |
+| `:siren_inconnu` | l'annuaire ne connaît pas ce SIREN | vérifier le SIREN, ou réessayer plus tard |
+| `:adresse_inconnue` | le SIREN est connu, pas cette adresse | régénérer avec `adresses_connues`, ou réessayer plus tard |
+
+Les deux derniers motifs peuvent se résoudre d'eux-mêmes, quand l'acheteur déclare son adresse :
+c'est ce qui permet de **générer une facture sur une adresse présumée** — le SIREN de l'acheteur,
+faute de mieux — et de retenter le dépôt à intervalle régulier sans jamais risquer son numéro.
+Une erreur de l'annuaire lui-même (401, 403, 5xx) remonte telle quelle : faute de pouvoir
+vérifier, on ne dépose pas.
+
+`verifier_adressage: false` dispense du contrôle, pour qui l'a déjà fait :
+
+```ruby
+client.flux.deposit_facturx("facture.pdf", verifier_adressage: false)
+```
+
+L'adresse se lit aussi hors dépôt :
+
+```ruby
+adresse = Cpro::Facturx.adresse_acheteur(File.binread("facture.pdf"))   # nil si la facture n'en porte pas
+adresse.identifiant   # => "474775418"
+adresse.schema        # => "0225"
+```
+
 Le même endpoint accepte trois autres types de flux, qui ne diffèrent que par leur code interface :
 
 ```ruby
@@ -288,11 +353,11 @@ Pour brancher directement sans reconstruire le même `if` dans chaque applicatio
 
 ```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
+when :en_attente, :facture_introuvable, :deposee, :en_cours 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, :cycle_de_vie                             then classer
 end
 ```
 
@@ -318,8 +383,8 @@ 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 |
+| `:flux_en_attente` | 404 sur le flux — cas nominal —, ou statut autre que `RECEVABLE` et `IRRECEVABLE` | 1 | réinterroger |
+| `:flux_irrecevable` | statut `IRRECEVABLE`, 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 |
 
@@ -327,6 +392,11 @@ La méthode **n'attend pas** : c'est une photographie, la cadence d'interrogatio
 Seuls le 404 du flux et la recherche vide deviennent des étapes ; un 401, un 403 ou un 5xx
 continuent de lever.
 
+Seul `IRRECEVABLE` vaut verdict d'échec. Le statut intermédiaire `ENTRANT_ENVELOPPE_VALIDE`, que
+déclare le swagger, et toute valeur que la plateforme ajouterait laissent le flux en attente :
+conclure au rejet inviterait à redéposer, et ce second dépôt serait refusé en doublon. Le statut
+brut reste lisible par `suivi.statut_flux`.
+
 ## Servir plusieurs entités
 
 L'AIFE distingue trois types de raccordement API. Celui qui s'applique détermine le modèle à
@@ -370,6 +440,7 @@ Toutes les erreurs dérivent de `Cpro::Error`.
 | Exception | Déclenchement |
 | --- | --- |
 | `Cpro::ConfigurationError` | configuration incomplète, compte technique manquant |
+| `Cpro::AdressageError` | dépôt bloqué avant envoi : adresse de l'acheteur absente ou inconnue de l'annuaire |
 | `Cpro::RequestError` | 400, 406, 415, 422 |
 | `Cpro::AuthenticationError` | 401, échec d'obtention du jeton |
 | `Cpro::AuthorizationError` | 403 — habilitations insuffisantes |
@@ -378,7 +449,12 @@ Toutes les erreurs dérivent de `Cpro::Error`.
 | `Cpro::ServerError` | 5xx |
 
 Les erreurs d'API exposent `#status`, `#body` et `#correlation_id` — ce dernier est l'identifiant
-PISTE à fournir au support en cas d'incident.
+PISTE à fournir au support en cas d'incident. Leur message nomme la requête qui a échoué, pour
+qu'une erreur lue dans un journal se situe d'elle-même :
+
+```ruby
+error.message   # => "400 Unexpected value 'EN_COURS_TRAITEMENT' (GET /g2b/flux/v1/flux/b18e3b6c-…)"
+```
 
 ## Développement
 

data/lib/cpro/adressage.rb

@@ -57,12 +57,20 @@ module Cpro
       ].compact
     end
 
-    # Une ligne d'annuaire correspond à ce palier si elle décrit le même niveau de précision.
+    # Une ligne d'annuaire correspond à ce palier si elle décrit le même niveau de précision. Une
+    # adresse à suffixe n'appartient à aucun palier : sans SIRET ni code routage, elle passerait
+    # sinon pour la ligne SIREN nue.
     def correspond?(ligne)
-      ligne.siret == siret && ligne.identifiant_routage.to_s.empty? == service.nil? &&
+      !ligne.suffixe? && ligne.siret == siret && ligne.identifiant_routage.to_s.empty? == service.nil? &&
         (service.nil? || ligne.identifiant_routage == service)
     end
 
+    # Une ligne de service de ce SIRET : le palier SIRET y descend faute d'adresse propre.
+    def service_de?(ligne)
+      !siret.nil? && service.nil? && !ligne.suffixe? && ligne.siret == siret &&
+        !ligne.identifiant_routage.to_s.empty?
+    end
+
     def to_s
       [siret ? "#{siren}_#{siret}" : siren, service].compact.join("_")
     end

data/lib/cpro/controle_adressage.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Cpro
+  # Confronte l'adresse de l'acheteur (BT-49) d'un Factur-X à l'annuaire, avant le dépôt.
+  #
+  # Chorus Pro ne la contrôle qu'au traitement, plusieurs minutes après le dépôt : absente, la
+  # facture est rejetée ADR_ERR ; inconnue de l'annuaire, REJ_ADR. Et son numéro est alors
+  # consommé — la redéposer sous le même numéro échoue (mesuré le 30/08/2026), il faut un avoir
+  # et une nouvelle facture. Un appel à l'annuaire avant le dépôt évite d'en arriver là.
+  #
+  # La comparaison se fait mot pour mot sur toutes les lignes de l'unité légale, et non par
+  # `Annuaire#find_identifiant_adressage` : la forme SIREN_SUFFIXE n'entre dans aucune de celles
+  # que lit `Adressage`, et la question n'est pas de trouver l'adresse la plus proche, mais de
+  # savoir si celle de la facture existe.
+  class ControleAdressage
+    SCHEMA_ANNUAIRE = "0225"
+    PREFIXE_SIREN = /\A\d{9}/.freeze
+    ADRESSES_CITEES = 10
+
+    CONSEQUENCE = "Chorus Pro rejetterait la facture et son numéro serait consommé."
+
+    def self.verifier!(annuaire, contenu)
+      new(annuaire).verifier!(contenu)
+    end
+
+    def initialize(annuaire)
+      @annuaire = annuaire
+    end
+
+    # Rend la ligne d'annuaire de l'adresse, ou lève une AdressageError sans rien avoir déposé.
+    def verifier!(contenu)
+      adresse = adresse_annuaire(contenu)
+      siren = adresse.identifiant[PREFIXE_SIREN]
+      lignes = lignes_de(siren) or bloquer(:siren_inconnu, message_siren_inconnu(adresse, siren), adresse)
+
+      lignes.find { |ligne| ligne.identifiant_adressage == adresse.identifiant } ||
+        bloquer(:adresse_inconnue, message_adresse_inconnue(adresse, siren, lignes), adresse, lignes.map(&:to_s))
+    end
+
+    private
+
+    attr_reader :annuaire
+
+    # L'adresse de la facture, pourvu qu'elle relève de l'annuaire : présente, en schemeID 0225, et
+    # ouverte par un SIREN. Ces trois défauts se voient sans appel réseau.
+    def adresse_annuaire(contenu)
+      adresse = Facturx.adresse_acheteur(contenu) or bloquer(:adresse_absente, message_absente)
+      bloquer(:schema_invalide, message_schema(adresse), adresse) unless adresse.schema == SCHEMA_ANNUAIRE
+      bloquer(:siren_absent, message_sans_siren(adresse), adresse) unless adresse.identifiant.match?(PREFIXE_SIREN)
+      adresse
+    end
+
+    # Toutes les pages : une grande entreprise porte plus de lignes qu'une page n'en rend. Nil si
+    # le SIREN est inconnu de l'annuaire.
+    def lignes_de(siren)
+      lignes = []
+      loop do
+        page = annuaire.find_by_siren(siren, **(lignes.empty? ? {} : { ignorer: lignes.size })).lignes_annuaire
+        lignes.concat(page.to_a)
+        return lignes if page.empty? || lignes.size >= page.nombre_total.to_i
+      end
+    rescue NotFoundError
+      nil
+    end
+
+    def bloquer(motif, message, adresse = nil, adresses_connues = [])
+      raise AdressageError.new("Dépôt bloqué : #{message}", motif: motif, identifiant: adresse&.identifiant,
+                                                            adresses_connues: adresses_connues)
+    end
+
+    def message_absente
+      "la facture ne porte pas d'adresse électronique d'acheteur (BT-49). Chorus Pro la rejetterait " \
+        "(ADR_ERR) et son numéro serait consommé. Régénérez-la avec l'adresse de l'acheteur relevée dans " \
+        "l'annuaire."
+    end
+
+    def message_schema(adresse)
+      "l'adresse électronique de l'acheteur (BT-49) « #{adresse} » est déclarée avec le schemeID " \
+        "« #{adresse.schema} », alors que le circuit G2B exige #{SCHEMA_ANNUAIRE}, celui de l'annuaire de la " \
+        "facturation électronique (règle BR-FR-21). #{CONSEQUENCE}"
+    end
+
+    def message_sans_siren(adresse)
+      "l'adresse électronique de l'acheteur (BT-49) « #{adresse} » ne commence pas par un SIREN, comme " \
+        "l'exige la règle BR-FR-21. #{CONSEQUENCE}"
+    end
+
+    def message_siren_inconnu(adresse, siren)
+      "le SIREN #{siren}, qui ouvre l'adresse électronique de l'acheteur (BT-49) « #{adresse} », est " \
+        "inconnu de l'annuaire de la facturation électronique. Chorus Pro rejetterait la facture (REJ_ADR) " \
+        "et son numéro serait consommé. Vérifiez le SIREN de l'acheteur. S'il est juste, son adresse n'est " \
+        "peut-être pas encore en vigueur — l'API ne rend que les lignes courantes ou activées sous 7 jours — : " \
+        "réessayez plus tard. Si le blocage persiste, l'acheteur n'est pas inscrit, ou n'est pas soumis à la " \
+        "facturation électronique."
+    end
+
+    def message_adresse_inconnue(adresse, siren, lignes)
+      "l'adresse électronique de l'acheteur (BT-49) « #{adresse} » est inconnue de l'annuaire. " \
+        "#{adresses_connues(siren, lignes)} Chorus Pro rejetterait la facture (REJ_ADR) et son numéro serait " \
+        "consommé : #{remede(lignes)}."
+    end
+
+    def adresses_connues(siren, lignes)
+      return "Aucune adresse n'est connue pour le SIREN #{siren}." if lignes.empty?
+
+      citees = lignes.first(ADRESSES_CITEES).join(", ")
+      suite = lignes.size > ADRESSES_CITEES ? ", … (#{lignes.size} au total)" : ""
+      "Adresses connues pour le SIREN #{siren} : #{citees}#{suite}."
+    end
+
+    def remede(lignes)
+      return "réessayez quand l'acheteur aura déclaré son adresse" if lignes.empty?
+
+      "régénérez-la avec l'une de ces adresses, ou réessayez plus tard si l'acheteur déclare la sienne"
+    end
+  end
+end

data/lib/cpro/entities/ligne_annuaire.rb

@@ -5,6 +5,7 @@ module Cpro
     class LigneAnnuaire < Base
       PLATEFORME_ACTIVE = "Plateforme active"
       PLATEFORME_EN_ATTENTE = "Plateforme en attente d'activation"
+      SIREN_NU = /\A\d{9}\z/.freeze
 
       def identifiant_adressage
         payload["identifiantAdressage"]
@@ -38,6 +39,15 @@ module Cpro
         statut_plateforme == PLATEFORME_EN_ATTENTE
       end
 
+      # Une adresse SIREN_SUFFIXE, hors de la hiérarchie SIREN → SIRET → service. Reconnue à son
+      # champ, ou à défaut à sa forme — sans SIRET, et autre chose qu'un SIREN nu — le champ
+      # n'ayant jamais été observé renseigné.
+      def suffixe?
+        return true unless suffixe_adressage.to_s.empty?
+
+        siret.to_s.empty? && !identifiant_adressage.to_s.match?(SIREN_NU)
+      end
+
       # L'identifiant d'adressage est ce qu'on porte en BT-49 : c'est la valeur utile de la ligne.
       def to_s
         identifiant_adressage.to_s

data/lib/cpro/errors.rb

@@ -5,6 +5,22 @@ module Cpro
 
   class ConfigurationError < Error; end
 
+  # Levée avant un dépôt dont l'adresse de l'acheteur (BT-49) ferait rejeter la facture. Rien n'est
+  # parti : le numéro de facture reste disponible.
+  #
+  # `motif` se prête au branchement : `:adresse_inconnue` et `:siren_inconnu` peuvent se résoudre
+  # d'eux-mêmes quand l'acheteur déclare son adresse, les autres demandent de régénérer la facture.
+  class AdressageError < Error
+    attr_reader :motif, :identifiant, :adresses_connues
+
+    def initialize(message, motif:, identifiant: nil, adresses_connues: [])
+      @motif = motif
+      @identifiant = identifiant
+      @adresses_connues = adresses_connues
+      super(message)
+    end
+  end
+
   class ApiError < Error
     attr_reader :status, :body, :correlation_id
 

data/lib/cpro/facturx.rb

@@ -10,6 +10,21 @@ module Cpro
     ENTETE_PDF = "%PDF"
     RACINE_CII = "CrossIndustryInvoice"
 
+    # Le bloc de l'acheteur est isolé d'abord : le vendeur porte la même balise (BT-34), et le
+    # contact de l'acheteur un courriel sous une balise voisine. Le préfixe d'espace de noms est
+    # libre en XML, d'où `(?:\w+:)?`.
+    BLOC_ACHETEUR = %r{<(?:\w+:)?BuyerTradeParty\b[^>]*>(.*?)</(?:\w+:)?BuyerTradeParty>}m.freeze
+    ADRESSE_ELECTRONIQUE =
+      %r{<(?:\w+:)?URIUniversalCommunication>\s*<(?:\w+:)?URIID\b([^>]*)>([^<]*)</(?:\w+:)?URIID>}m.freeze
+    SCHEMA = /schemeID\s*=\s*["']([^"']*)["']/.freeze
+
+    # BT-49 et son schéma, BT-49-1.
+    AdresseElectronique = Struct.new(:identifiant, :schema) do
+      def to_s
+        identifiant
+      end
+    end
+
     module_function
 
     def pdf?(contenu)
@@ -44,6 +59,16 @@ module Cpro
       nil
     end
 
+    # Adresse électronique de l'acheteur (BT-49), ou nil si le XML embarqué n'en porte pas.
+    def adresse_acheteur(contenu)
+      document = xml(contenu) or return nil
+      acheteur = document[BLOC_ACHETEUR, 1] or return nil
+      attributs, valeur = acheteur.match(ADRESSE_ELECTRONIQUE)&.captures
+      return nil if valeur.nil? || valeur.strip.empty?
+
+      AdresseElectronique.new(valeur.strip, attributs[SCHEMA, 1])
+    end
+
     def inflate(flux)
       Zlib::Inflate.inflate(flux)
     rescue Zlib::Error

data/lib/cpro/middleware/raise_error.rb

@@ -43,7 +43,15 @@ module Cpro
       # `reason_phrase` n'existe pas avant Faraday 1.0.
       def message_for(env)
         detail = detail_for(env.body) || (env.reason_phrase if env.respond_to?(:reason_phrase))
-        [env.status, detail].compact.join(" ")
+        detail = nil if detail.to_s.strip.empty?
+        [env.status, detail, requete(env)].compact.join(" ")
+      end
+
+      # Lue dans les journaux de l'hôte, sans pile d'appels, l'erreur doit dire quel appel a
+      # échoué : `Client#suivi`, par exemple, en enchaîne trois. Le chemin suffit à le situer ; la
+      # requête en est écartée pour garder un message stable d'un appel à l'autre.
+      def requete(env)
+        "(#{env.method.to_s.upcase} #{env.url.path})" if env.url
       end
 
       def detail_for(body)

data/lib/cpro/resources/annuaire.rb

@@ -91,6 +91,8 @@ module Cpro
       # 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.
       #
+      # L'ordre est celui du dossier de spécifications externes (§3.1.2), détaillé sur `plus_proche`.
+      #
       # Un seul appel réseau : `GET /siren/code-insee:` retourne aussi les lignes SIRET et service.
       def find_identifiant_adressage(valeur)
         adressage = Adressage.parse(valeur)
@@ -112,14 +114,21 @@ 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.
+      # Parcourt les paliers du plus précis au plus général, dans l'ordre que recommande le dossier
+      # de spécifications externes (§3.1.2) pour adresser un SIRET : son adresse propre, sinon son
+      # premier code routage par ordre alphanumérique, sinon le SIREN, sinon la première adresse à
+      # suffixe. 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) }
+          ligne = lignes.find { |candidate| palier.correspond?(candidate) } ||
+                  premiere(lignes.select { |candidate| palier.service_de?(candidate) })
           return ligne if ligne
         end
-        nil
+        premiere(lignes.select(&:suffixe?))
+      end
+
+      def premiere(lignes)
+        lignes.min_by(&:identifiant_adressage)
       end
 
       def normalize(value, length, label)

data/lib/cpro/resources/flux.rb

@@ -3,8 +3,14 @@
 module Cpro
   module Resources
     class Flux < Base
-      def deposit_facturx(source, name: nil)
-        depot(source, :facturx, name: name) { |contenu| verifier_facturx(contenu) }
+      # Avant de déposer, confronte l'adresse de l'acheteur (BT-49) à l'annuaire, au prix d'un appel :
+      # une adresse absente ou inconnue lève une AdressageError au lieu de faire rejeter la facture,
+      # et consommer son numéro, plusieurs minutes plus tard. `verifier_adressage: false` s'en passe.
+      def deposit_facturx(source, name: nil, verifier_adressage: true)
+        depot(source, :facturx, name: name) do |contenu|
+          verifier_facturx(contenu)
+          ControleAdressage.verifier!(client.annuaire, contenu) if verifier_adressage
+        end
       end
 
       def deposit_ubl(source, name: nil)

data/lib/cpro/suivi.rb

@@ -17,6 +17,9 @@ module Cpro
     # de l'annexe des statuts, ils proviennent de la plateforme du destinataire ou constatent
     # l'émission par la plateforme.
     #
+    # La réciproque est fausse. Hormis `REFUSEE`, l'annexe les déclare tous facultatifs : leur
+    # absence ne prouve pas que la facture n'est pas partie.
+    #
     # `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.
@@ -38,10 +41,16 @@ module Cpro
 
     # 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.
+    #
+    # Seul IRRECEVABLE est un verdict d'échec. Tout autre statut que RECEVABLE — l'intermédiaire
+    # ENTRANT_ENVELOPPE_VALIDE du swagger, ou une valeur que la plateforme ajouterait — laisse le
+    # flux en attente : conclure au rejet inviterait à redéposer, et le second dépôt serait refusé
+    # en doublon.
     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?
+      return new(etape: :flux_irrecevable, statut_flux: statut) if statut.irrecevable?
+      return new(etape: :flux_en_attente, statut_flux: statut) unless statut.recevable?
 
       facture = premiere_facture(client, statut)
       return new(etape: :facture_introuvable, statut_flux: statut) if facture.nil?
@@ -106,7 +115,8 @@ module Cpro
 
     # Nomme la situation en une valeur sur laquelle brancher, l'étape du suivi et l'état de la
     # facture étant aplatis ensemble. `:deposee` dit que la plateforme a pris la facture sans rien
-    # signaler — le dépôt a réussi, l'acheminement n'a pas encore eu lieu.
+    # signaler. D'après la spécification, elle l'émet alors vers la plateforme du destinataire,
+    # mais aucun statut obligatoire ne le confirme : l'acheminement n'est ni prouvé ni exclu.
     #
     # Ne repose que sur des codes : statut, code motif, étape.
     #

data/lib/cpro/version.rb

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

data/lib/cpro.rb

@@ -29,6 +29,7 @@ require_relative "cpro/entities/statut_flux"
 require_relative "cpro/cdv/statut"
 require_relative "cpro/cdv/message"
 require_relative "cpro/facturx"
+require_relative "cpro/controle_adressage"
 require_relative "cpro/archive"
 require_relative "cpro/enveloppe"
 require_relative "cpro/resources/base"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cpro-client
 version: !ruby/object:Gem::Version
-  version: 0.2.8
+  version: 0.3.0
 platform: ruby
 authors:
 - Hôtentic
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-25 00:00:00.000000000 Z
+date: 2026-10-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -63,6 +63,7 @@ files:
 - lib/cpro/client.rb
 - lib/cpro/configuration.rb
 - lib/cpro/connection.rb
+- lib/cpro/controle_adressage.rb
 - lib/cpro/entities/base.rb
 - lib/cpro/entities/changement_statut.rb
 - lib/cpro/entities/code_routage.rb