cpro-client 0.2.7 → 0.2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56e12349c80b29ebc7190354cefea789a6a9114d42260bc40e2851529255a043
-  data.tar.gz: 35ec2d79aace35593b9493dd6e07b3ede842726ba9b2cc9b63491ca269844272
+  metadata.gz: 629795027a48606736ffd0273cd3bf2b1e457237508f428978a4bdbce3245f56
+  data.tar.gz: 5a3a218220129860479c710a68aaf4eb612ab74f2f6c8a812a7aa65e2f90f7a0
 SHA512:
-  metadata.gz: e3372fac6b533cb8b24b08dbae14c2dce8f495a93d4b53161d553b874ab208bee3099f53efa0af7159e4690cd5aea8414c9da2fef33a38c8cd875796aff99d60
-  data.tar.gz: fae64931447cd4708e173bca2790890bad33ed65bbc370ad49dc40e60a1f12185af579d947eec2a766fbb79f1dd5da07f77e1c99d18a54678532866b664ae206
+  metadata.gz: 23cc35215eb0530f66b71677d35948c1da2896c626a400018901de87c1e2ed8d517ffcb3eefe5f02d5978a7e1f966c513fd8cb1c114aa3950294fb0805915f21
+  data.tar.gz: 89a63f46184b02fb02ce615a964148f3ee3997899855312bacd77f3c41d5a7da6cd1b0ee255040fcf2304d3fa05541b13fbb57915ebca9b0c5187b7c07a20b80

data/CHANGELOG.md

@@ -1,6 +1,28 @@
 ## [Unreleased]
 
 
+## [0.2.8] - 2026-09-25
+
+### Ajouté
+- `Cpro::Resources::Factures#search` refuse une pagination hors bornes avant tout appel réseau :
+  `limite` au-delà de 50 — le maximum déclaré par le swagger — ou `ignorer` négatif lèvent une
+  `ArgumentError`. Relevé en production : au-delà de la borne, la plateforme répond `500 Erreur
+  interne` et non un 400, ce qui laisse croire à une panne alors que la requête est en cause.
+
+- `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.
+
+  `: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
+  un `NON_TRANSMISE` devenu caduc, dont l'appelant a déjà fait ce qu'il fallait.
+
+
 ## [0.2.7] - 2026-09-07
 
 ### Ajouté

data/CHORUS_PRO.md

@@ -0,0 +1,302 @@
+# Comportements observés de Chorus Pro G2B
+
+Ce que la plateforme répond vraiment, scénario par scénario. Les swaggers décrivent les champs, pas
+les enchaînements ; ce fichier comble l'écart, et sert à reconnaître une situation sans avoir à la
+reproduire.
+
+Chaque ligne porte sa provenance :
+
+- **mesuré** — relevé sur la sandbox PISTE, avec sa date. C'est la source la plus fiable ;
+- **documenté** — tiré du *Dossier de spécifications externes FE — Chorus Pro v1.1* ou de l'annexe
+  *Correspondance codes interfaces / CDV / statuts v1.2*, sans avoir été observé.
+
+Un comportement documenté mais non mesuré n'est pas une certitude : le swagger de l'Annuaire
+déclarait `contient` là où le serveur exige `strict`, et la consultation d'un code routage ne sert
+pas les champs que sa recherche renvoie.
+
+## Deux niveaux qu'il ne faut pas confondre
+
+Un dépôt est jugé **deux fois**, et les deux verdicts vivent dans des API différentes.
+
+| | Le flux | La facture |
+| --- | --- | --- |
+| Ce qui est jugé | l'enveloppe : archive, checksum, syntaxe des fichiers | le contenu métier : adressage, unicité, conformité |
+| Où le lire | `GET /flux/{uid}` → `Cpro::Entities::StatutFlux` | Recherche Factures → `Cpro::Entities::Facture` |
+| Statuts | `RECEVABLE` (500), `IRRECEVABLE` (501) | les 22 statuts du cycle de vie |
+| Motifs | `StatutFlux#motifs_rejet` | `Facture#historique` → `ChangementStatut#motifs_rejet` |
+
+**`RECEVABLE` ne dit rien du sort de la facture.** Un flux dont la facture référence un vendeur
+inconnu ressort quand même recevable *(mesuré le 2026-08-14)*. `Cpro::Client#suivi` enchaîne les
+deux niveaux et rassemble leurs motifs.
+
+## Tout verdict est asynchrone
+
+`POST /flux` ne valide que la requête : un 400 ou un 403 lève immédiatement, un 200 rend un
+`uidFlux` et ne dit rien d'autre. **Aucun statut n'accompagne le dépôt**, pas même l'irrecevabilité —
+contrôler la syntaxe des fichiers suppose d'ouvrir l'archive, ce que le PPF ne fait pas dans le
+temps de la requête.
+
+Le verdict se lit ensuite par `GET /flux/{uid}`, documenté `404 Flux non trouvé **ou non traité**` :
+la même réponse pour un flux inexistant et pour un flux en attente de jugement.
+
+Écarts relevés entre le moment où la plateforme pose le statut (`dateMajStatut`) et celui où il est
+lisible, d'après les cassettes sandbox :
+
+| Cassette | Statut posé | Lu à | Écart |
+| --- | --- | --- | --- |
+| `flux_statut` | 14/08 20:26:02 | 14/08 20:36:58 | ~11 min |
+| `flux_statut_cdv` | 15/08 15:40:11 | 15/08 15:43:31 | ~3 min |
+
+Le test sandbox `test_a_processed_flux_is_recevable` interroge d'ailleurs un flux déposé lors d'une
+session antérieure, et non celui que `test_depositing_a_facturx_invoice_returns_a_flux_uid` vient de
+déposer : un flux tout juste déposé n'est pas consultable.
+
+Compter en minutes pour le verdict d'enveloppe, davantage pour que la facture apparaisse dans
+Recherche Factures. `Cpro::Client#suivi` rend `:flux_en_attente` pendant toute cette période, au
+coût d'un seul appel réseau.
+
+## Les scénarios
+
+Le `→` sépare les étapes successives. Un motif entre crochets est porté par le statut qui le
+précède.
+
+| Scénario | Flux | Facture | Issue |
+| --- | --- | --- | --- |
+| **Enveloppe invalide** *(mesuré 15/08)* | `IRRECEVABLE` (501) [`IRR_SYNTAX`] | jamais créée, Recherche Factures répond 204 | terminal — corriger le fichier et redéposer |
+| **Adressage introuvable** *(mesuré 30/08)* | `RECEVABLE` (500) | `REJETEE` [`REJ_ADR`] — seule entrée de l'historique | terminal — la facture existe, son numéro est consommé |
+| **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é |
+| **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 |
+
+Les deux cas `NON_TRANSMISE` portent le **même statut et le même motif** : seule la note les
+distingue, et seul l'annuaire permet de les anticiper.
+
+| `statutPlateforme` de la ligne d'annuaire | Note du motif | Ce que fait Chorus Pro |
+| --- | --- | --- |
+| `Plateforme active` | — | transmet |
+| `Plateforme en attente d'activation` | « La plateforme agréée de votre client n'est pas raccordée à CHORUS PRO » | transmettra au raccordement |
+| `Pas de plateforme` | « Le destinataire n'a pas choisi de plateforme agréée » | ne transmettra jamais |
+
+C'est pourquoi `Annuaire#find_identifiant_adressage` rend l'adresse **même sans plateforme active**,
+en signalant le cas par `plateforme_active?` : la facture reste déposable, et l'obligation
+réglementaire remplie.
+
+## Le piège du statut porteur
+
+Les motifs sont accrochés au statut sous lequel l'incident survient, qui n'a pas à être alarmant.
+Une facture non transmise est `DEPOSEE` :
+
+```ruby
+facture.statut     # => "DEPOSEE"
+facture.rejetee?   # => false      ← et pourtant elle n'arrivera jamais
+facture.en_echec?  # => true
+```
+
+Se fier au statut seul fait manquer le cas. `Facture#en_echec?` couvre les statuts d'échec **et**
+tout motif présent dans l'historique ; `#dernier_incident` isole le plus récent, avec ses motifs.
+
+Un même changement de statut porte plusieurs motifs — `NON_TRANSMISE` et `REJ_UNI` ont été relevés
+ensemble le 04/09.
+
+## Orienter une facture vers son traitement
+
+Le statut seul ne suffit pas : deux couples de cas partagent le même. L'orientation se fait sur le
+couple **statut × motif**.
+
+| Cas | Statut | Motif | Comment le distinguer |
+| --- | --- | --- | --- |
+| **En cours** | `DEPOSEE` | aucun | rien à faire, 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 |
+| **Transmission différée** | `DEPOSEE` | `NON_TRANSMISE` | note « La plateforme agréée de votre client n'est pas raccordée » |
+| **Jamais transmise** | `DEPOSEE` | `NON_TRANSMISE` | note « Le destinataire n'a pas choisi de plateforme agréée » |
+| **Transmise** | voir liste ci-dessous | — | un statut que seul l'aval peut poser |
+
+**La note distingue les deux `NON_TRANSMISE`**, faute de mieux. Plus sûr : interroger l'annuaire
+*avant* le dépôt — `find_identifiant_adressage(siret).statut_plateforme` vaut
+`Plateforme en attente d'activation` dans le premier cas, `Pas de plateforme` dans le second.
+
+### Statuts qui prouvent l'acheminement
+
+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.
+
+```ruby
+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
+```
+
+`APPROUVEE`, `REFUSEE` et `VISEE` circulent **dans les deux sens** : reçus, ils prouvent
+l'acheminement ; émis par vous via `Flux#emettre_statut`, ils ne prouvent rien. Ils figurent quand
+même dans la liste, parce que les recevoir est le cas courant et que les omettre ferait retomber
+une facture refusée par l'acheteur sur « en cours » — ce qui serait faux. Si votre application émet
+l'un d'eux, elle le sait et peut l'écarter.
+
+`COMPLETEE`, `ENCAISSEE`, `ANNULEE` et `CHANGEMENT_DE_COMPTE_A_PAYER`, que seul le vendeur pose, ne
+sont en revanche jamais des preuves d'acheminement.
+
+### Mise en œuvre
+
+`Cpro::Suivi#orientation` aplatit l'étape du suivi et l'état de la facture en une valeur :
+
+| Orientation | Origine | Traitement |
+| --- | --- | --- |
+| `: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 |
+| `: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 |
+| `:non_transmise` | motif `NON_TRANSMISE` sur l'incident courant | préparer un duplicata |
+| `:erreur_routage` | statut `ERREUR_ROUTAGE` | terminal |
+| `:transmise` | statut de `Suivi::STATUTS_TRANSMISE` | rien |
+
+```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
+```
+
+L'ordre d'évaluation compte : les statuts passent avant les motifs, si bien qu'un acheminement
+avéré ou un encaissement l'emportent sur un `NON_TRANSMISE` devenu caduc, dont l'appelant a déjà
+fait ce qu'il fallait. Et c'est l'**incident courant** qui décide, non le cumul de l'historique :
+une facture déposée sans être transmise, puis mise à disposition, puis refusée, ressort
+`:transmise`.
+
+`:cycle_de_vie` couvre `ENCAISSEE`, `COMPLETEE`, `ANNULEE` et `CHANGEMENT_DE_COMPTE_A_PAYER` — les
+statuts que seul le vendeur pose. Ils ne prouvent pas l'acheminement : on encaisse très bien une
+facture jamais transmise, après remise d'un duplicata.
+
+`:en_cours` ne garde que les statuts sur lesquels nous n'avons ni mesure ni lecture —
+`DEMANDE_DE_PAIEMENT_DIRECT` et les trois d'affacturage. Ce n'est pas un fourre-tout : tout autre
+statut a sa place ailleurs.
+
+### Ce que l'orientation ne tranche pas
+
+Deux distinctions restent à l'appelant, parce que les porter dans la gem serait fragile.
+
+**Les deux `NON_TRANSMISE`.** Seul le texte de la note les sépare, et il est rédigé par l'AIFE :
+une reformulation casserait la classification sans que rien ne le signale. Le moyen sûr est en
+amont — `Annuaire#find_identifiant_adressage(siret).statut_plateforme` vaut
+`Plateforme en attente d'activation` pour le différé, `Pas de plateforme` pour le définitif.
+
+**Rejet corrigeable ou définitif.** La distinction 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é. `suivi.motifs` permet de trancher chez soi :
+
+```ruby
+definitif = suivi.motifs.any? { |motif| motif.code == "REJ_ADR" }
+```
+
+`REJ_UNI` se superpose aux autres motifs sans les remplacer : il signale que le triptyque était déjà
+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.
+
+## Motifs rencontrés
+
+| Code | Libellé | Où | Signification |
+| --- | --- | --- | --- |
+| `IRR_SYNTAX` | Contrôle syntaxique des fichiers du flux | flux | un fichier de l'archive est mal formé ; la note nomme le fichier fautif |
+| `REJ_ADR` | Rejet sur Contrôle d'adressage | facture | BT-49 ne correspond à aucune adresse de l'annuaire |
+| `NON_TRANSMISE` | Destinataire non connecté | facture | adresse valide, destinataire non raccordé |
+| `REJ_UNI` | Contrôle de l'unicité du fichier de facture | facture | le triptyque est déjà utilisé |
+| `ROUTAGE_ERR` | Erreur de routage | facture | destinataire **public** adressé par le code interface G2B |
+| `ADR_ERR` | *(documenté)* | facture | l'adresse électronique est absente de la facture |
+
+## L'unicité, et ce qu'elle implique
+
+> le triptyque permettant d'assurer l'unicité de la facture est le suivant : **année d'émission
+> (BT-2)**, **SIREN de l'émetteur (BT-30)**, **numéro de facture (BT-1)**.
+
+Le libellé du motif parle du « fichier », mais le contrôle porte sur ces trois valeurs : deux dépôts
+dont seuls la date d'émission et BT-49 différaient ont bien été jugés doublons *(mesuré 04/09)*.
+
+**Un numéro est consommé au premier dépôt, quel que soit le sort de celui-ci.** Une facture rejetée
+sur l'adressage occupe son numéro : la corriger et la redéposer sous le même numéro échoue.
+
+La spécification prévoit pourtant qu'une facture rejetée pour **non-conformité** peut être
+retransmise après correction — elle précise que dans ce cas « la facture n'est pas intégrée dans la
+solution Chorus Pro ». La lecture cohérente avec nos mesures est donc qu'un rejet de conformité
+n'intègre pas la facture et ne consomme pas son numéro, alors qu'un rejet d'adressage l'intègre et
+le consomme. Nous n'avons mesuré que le second cas.
+
+## Qui émet quoi
+
+D'après l'annexe *Correspondance codes interfaces / CDV / statuts*, feuillet G2B. En mode API il n'y
+a **aucune notification** : tout ce qui vient de la plateforme se lit par interrogation.
+
+**Émis par nous** (interface `FSO3300A`, via `Flux#emettre_statut`) — les sept statuts du catalogue
+`Cpro::Cdv::Statut`, dont deux obligatoires : `Refusée` (210) et `Encaissée` (212).
+
+**Reçus** (interface `FEN4000A` ou `CSO311xA`) — `Déposée` (200), `Émise par la plateforme` (201),
+`Reçue de la plateforme` (202), `Mise à disposition` (203), `Prise en charge` (204), `Approuvée
+partiellement` (206), `En litige` (207), `Suspendue` (208), `Paiement transmis` (211), `Rejetée`
+(213), `Erreur routage` (221). `Approuvée` (205), `Refusée` (210) et `Visée` (214) circulent dans
+les deux sens.
+
+Un CDV déposé peut lui-même être rejeté — statut `601`, interface `FEN4002A`. Par quel appel API ce
+rejet se lit reste à déterminer.
+
+## Points pratiques
+
+**Lier la facture à ses statuts.** BT-18 (identifiant d'objet facturé) qualifié `AJW` est repris par
+Chorus Pro dans chaque cycle de vie en MDT-92, avec le même qualifiant. C'est un lien plus stable
+que le `nomFlux`, dont le format doit changer.
+
+**Allotir.** La spécification recommande un maximum de 500 factures par flux.
+
+**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
+> code interface »
+
+Le G2B (`FSO3117A`) va du public vers le privé. Une facture destinée à une autre entité publique
+relève du circuit **G2G**, que cette gem ne couvre pas. L'annuaire ne le signale pas à l'adressage :
+`find_identifiant_adressage` rend l'adresse d'une structure publique comme de n'importe quelle
+autre. La nature du destinataire se lit par `search_siren(filtres: { siren: … }).first.type_entite`,
+qui vaut `Publique` ou `Privée assujettie` — et seule la **recherche** la sert, la consultation
+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.
+
+**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.
+
+**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.
+Le même comportement a été relevé sur l'Annuaire, où un filtre `siret` privé de son opérateur
+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.
+
+**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.
+
+**Les dates.** L'API Flux date en UTC **sans marqueur de fuseau** (`2026-09-04T16:38:00.731094`),
+Recherche Factures avec un `Z` depuis fin août. `Entities::Base#parse_time` absorbe les deux formes.
+
+## Sources
+
+- *Dossier de spécifications externes FE — Chorus Pro v1.1*
+- *Annexe Chorus Pro — Correspondance codes interfaces / CDV / statuts v1.2*, feuillet G2B
+- Relevés sandbox PISTE, du 2026-08-14 au 2026-09-04

data/Gemfile.lock

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

data/lib/cpro/resources/factures.rb

@@ -14,6 +14,10 @@ module Cpro
 
       TOTAL_KEY = "nombreTotalResultats"
 
+      # Le swagger plafonne `limite` à 50. Au-delà, la plateforme répond 500 et non 400 : mieux
+      # vaut refuser localement que d'aller chercher une erreur serveur qui n'explique rien.
+      LIMITE_MAX = 50
+
       def search(filtres:, **options)
         payload = post("facture/recherche", search_body(filtres, options))
         Entities::ResultatRecherche.new(payload, item_class: Entities::Facture, total_key: TOTAL_KEY)
@@ -39,6 +43,7 @@ module Cpro
       private
 
       def search_body(filtres, options)
+        verifier_pagination!(options)
         compact_body(
           "filtres" => build_filtres(filtres),
           "champs" => Array(options[:champs]).map(&:to_s),
@@ -48,6 +53,18 @@ module Cpro
         )
       end
 
+      def verifier_pagination!(options)
+        limite = options[:limite]
+        if !limite.nil? && (limite.to_i.negative? || limite.to_i > LIMITE_MAX)
+          raise ArgumentError, "limite hors bornes : #{limite.inspect} (0 à #{LIMITE_MAX})"
+        end
+
+        ignorer = options[:ignorer]
+        return if ignorer.nil? || !ignorer.to_i.negative?
+
+        raise ArgumentError, "ignorer ne peut pas être négatif : #{ignorer.inspect}"
+      end
+
       def build_filtres(filtres)
         raise ArgumentError, "au moins un filtre est requis" if filtres.nil? || filtres.empty?
 

data/lib/cpro/suivi.rb

@@ -10,8 +10,8 @@ module Cpro
   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
+    ORIENTATIONS = %i[en_attente enveloppe_irrecevable facture_introuvable deposee en_cours
+                      rejetee non_transmise erreur_routage cycle_de_vie 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
@@ -25,8 +25,14 @@ module Cpro
       APPROUVEE APPROUVEE_PARTIELLEMENT EN_LITIGE SUSPENDUE PAIEMENT_TRANSMIS REFUSEE VISEE
     ].freeze
 
+    # Statuts que seul le vendeur pose, via `Flux#emettre_statut`. La facture vit sa vie
+    # commerciale — mais ils ne prouvent pas l'acheminement : on peut encaisser une facture jamais
+    # transmise, après remise d'un duplicata. C'est même le parcours que décrit la spécification.
+    STATUTS_CYCLE_DE_VIE = %w[ENCAISSEE COMPLETEE ANNULEE CHANGEMENT_DE_COMPTE_A_PAYER].freeze
+
     MOTIF_NON_TRANSMISE = "NON_TRANSMISE"
     STATUT_ERREUR_ROUTAGE = "ERREUR_ROUTAGE"
+    STATUT_DEPOSEE = "DEPOSEE"
 
     attr_reader :etape, :statut_flux, :facture
 
@@ -99,7 +105,10 @@ module Cpro
     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.
+    # 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.
+    #
+    # 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 :
@@ -133,13 +142,19 @@ module Cpro
 
     private
 
-    # L'ordre compte : un statut d'acheminement l'emporte sur un NON_TRANSMISE devenu caduc, et
+    # L'ordre compte. Les statuts passent avant les motifs : un acheminement avéré ou un encaissement
+    # l'emportent sur un NON_TRANSMISE devenu caduc, dont l'hôte a déjà fait ce qu'il fallait. Et
     # c'est l'incident courant — non le cumul de l'historique — qui décrit la situation présente.
+    #
+    # `:en_cours` ne reste que pour les statuts sur lesquels nous n'avons ni mesure ni lecture :
+    # les trois d'affacturage et DEMANDE_DE_PAIEMENT_DIRECT. Ce n'est pas un fourre-tout.
     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 :cycle_de_vie if STATUTS_CYCLE_DE_VIE.include?(facture.statut)
       return :non_transmise if non_transmise?
+      return :deposee if facture.statut == STATUT_DEPOSEE
 
       :en_cours
     end

data/lib/cpro/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cpro-client
 version: !ruby/object:Gem::Version
-  version: 0.2.7
+  version: 0.2.8
 platform: ruby
 authors:
 - Hôtentic
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-07 00:00:00.000000000 Z
+date: 2026-09-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -41,6 +41,7 @@ files:
 - ".gitignore"
 - ".rubocop.yml"
 - CHANGELOG.md
+- CHORUS_PRO.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - Gemfile.lock