cpro-client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a797bddcc8e42f168e7c6ac7e18f6a02de3f45b6dbe6bc03f4eb7f11a3854800
+  data.tar.gz: 25effc0a7fd95d27528d48c20d1289e236717ad7efbe3318d9a3284033ecf720
+SHA512:
+  metadata.gz: '095e98ac8c3752f4a117aab59f74bb77a15cd506bd5621637185e857261c8471d53850cbf5d42e2fcf72f054435ced5d060a26c659942224d80d3561813ea189'
+  data.tar.gz: e74b20cba8005d0d7b14b178d8e8e80e48b8f96a84f6c5cd859f7465abdaa1d1ed58d787c659a378b0896a592de9a61ee645266128d1241922a3665211992df2

data/.gitignore

@@ -0,0 +1,10 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/.idea/
+/local/

data/.rubocop.yml

@@ -0,0 +1,42 @@
+AllCops:
+  TargetRubyVersion: 2.7
+  NewCops: enable
+  SuggestExtensions: false
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/Documentation:
+  Enabled: false
+
+Layout/LineLength:
+  Max: 120
+
+# Le fichier doit porter le nom de la gem pour que `require "cpro-client"` fonctionne.
+Naming/FileName:
+  Exclude:
+    - "lib/cpro-client.rb"
+
+# Un test lisible enchaîne les assertions : ces métriques n'y ont pas de sens.
+Metrics:
+  Exclude:
+    - "test/**/*"
+
+Metrics/AbcSize:
+  Max: 20
+
+# Les mots-clés sont auto-documentés : les compter revient à pénaliser une signature claire.
+Metrics/ParameterLists:
+  CountKeywordArgs: false
+
+# Une classe qui transpose une spécification champ à champ dépasse légitimement 100 lignes.
+Metrics/ClassLength:
+  Max: 180
+
+Metrics/MethodLength:
+  Max: 20

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+## [Unreleased]
+
+- Authentification OAuth2 PISTE (`client_credentials`) avec cache du jeton, renouvellement anticipé
+  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.
+- API Dépôt Flux G2B : transmission d'une facture Factur-X (archive tar.gz, base64, checksum
+  sha256) et consultation du statut du flux.
+- Émission de statuts de cycle de vie : génération d'un message CDAR D22B conforme à l'Annexe A de
+  XP Z12-012, validé contre le XSD et le Schematron BR-FR-CDV, et accepté en sandbox (RECEVABLE).
+  Les motifs de rejet et les données conditionnelles sont contrôlés avant tout appel réseau.
+- Motif d'irrecevabilité d'un flux exposé par `Cpro::Entities::StatutFlux#motifs_rejet` et
+  `#code_statut`, suivant l'évolution de l'API livrée en Chorus Pro 5.2.2.
+- Contrôle du fichier avant dépôt Factur-X (PDF et pièce jointe présents) et lecture du montant
+  TTC déclaré par le XML embarqué, via `Cpro::Facturx`.
+- Dépôt des quatre types de flux acceptés par `POST /flux` : Factur-X, UBL, cycle de vie (CDV) et
+  e-reporting. `Cpro::Facturx::Depot` devient `Cpro::Enveloppe`, paramétrée par code interface, et
+  `Cpro::Facturx::Archive` devient `Cpro::Archive`.
+- API Recherche Factures G2B : recherche multi-critères, consultation d'une facture avec
+  l'historique de ses statuts et les motifs de rejet AFNOR, montants en `BigDecimal`.
+- Tests sandbox rejouables hors ligne via cassettes VCR expurgées (`rake test:sandbox`), et mode
+  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/CODE_OF_CONDUCT.md

@@ -0,0 +1,84 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at jbvilain@gmail.com. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior,  harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0,
+available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at https://www.contributor-covenant.org/translations.

data/Gemfile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in cpro-client.gemspec
+gemspec
+
+gem "minitest", "~> 5.0"
+gem "nokogiri", "~> 1.13"
+gem "rake", "~> 13.0"
+gem "rubocop", "~> 1.7"
+gem "vcr", "~> 6.0"
+gem "webmock", "~> 3.0"

data/Gemfile.lock

@@ -0,0 +1,79 @@
+PATH
+  remote: .
+  specs:
+    cpro-client (0.1.0)
+      faraday (~> 2.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.9.0)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.3)
+    base64 (0.3.0)
+    bigdecimal (4.1.2)
+    crack (1.0.1)
+      bigdecimal
+      rexml
+    faraday (2.8.1)
+      base64
+      faraday-net_http (>= 2.0, < 3.1)
+      ruby2_keywords (>= 0.0.4)
+    faraday-net_http (3.0.2)
+    hashdiff (1.2.1)
+    json (2.21.2)
+    language_server-protocol (3.17.0.6)
+    lint_roller (1.1.0)
+    minitest (5.26.1)
+    nokogiri (1.15.7-x86_64-darwin)
+      racc (~> 1.4)
+    parallel (1.28.0)
+    parser (3.3.12.0)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    public_suffix (5.1.1)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.4.2)
+    regexp_parser (2.12.0)
+    rexml (3.4.4)
+    rubocop (1.89.0)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (>= 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.50.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    ruby-progressbar (1.13.0)
+    ruby2_keywords (0.0.5)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    vcr (6.4.0)
+    webmock (3.26.2)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+
+PLATFORMS
+  x86_64-darwin-21
+
+DEPENDENCIES
+  cpro-client!
+  minitest (~> 5.0)
+  nokogiri (~> 1.13)
+  rake (~> 13.0)
+  rubocop (~> 1.7)
+  vcr (~> 6.0)
+  webmock (~> 3.0)
+
+BUNDLED WITH
+   2.4.5

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Jean-Baptiste Vilain
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,310 @@
+# Cpro::Client
+
+Client Ruby des API **G2B** de Chorus Pro (Portail Public de Facturation), exposées via la
+plateforme [PISTE](https://piste.gouv.fr/). La gem couvre le raccordement en mode API ; la
+connexion EDI est hors périmètre.
+
+Scénario couvert :
+
+1. authentification OAuth2 auprès de PISTE ;
+2. recherche d'une structure dans l'annuaire par SIRET ou par SIREN ;
+3. transmission d'une facture Factur-X et suivi du flux.
+
+## Installation
+
+```ruby
+gem "cpro-client"
+```
+
+## Configuration
+
+Les identifiants PISTE identifient l'application et sont stables :
+
+```ruby
+Cpro.configure do |config|
+  config.environment   = :sandbox            # ou :production
+  config.client_id     = ENV["PISTE_CLIENT_ID"]
+  config.client_secret = ENV["PISTE_CLIENT_SECRET"]
+end
+```
+
+Le jeton OAuth est obtenu à la demande, renouvelé automatiquement, et **mis en cache sur la
+configuration** — pas sur le client. Construire un `Cpro.client` à chaque requête ne redemande donc
+pas de jeton. Un appel refusé en 401 est rejoué une fois avec un jeton neuf.
+
+## Compte technique
+
+Toutes les API G2B exigent, en plus du jeton OAuth, un **compte technique** Chorus Pro transmis
+dans l'en-tête `cpro-account`. Le swagger Annuaire ne le déclare pas, mais l'API le rejette en 400
+sans lui — vérifié en sandbox.
+
+Comme le compte peut varier d'un appel à l'autre, il se passe par `with_account` plutôt que d'être
+figé à la configuration. Un client sans compte lève une `Cpro::ConfigurationError` avant tout appel
+réseau.
+
+```ruby
+compte = Cpro::Account.new(login: "...", password: "...")
+client = Cpro.client.with_account(compte)
+```
+
+Le compte technique doit être rattaché à une structure publique, faute de quoi l'API répond
+`403 Aucune structure publique ou opérateur public associé au compte technique.`
+
+## Annuaire
+
+```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_routage)
+
+unite = client.annuaire.find_by_siren("702042755")
+```
+
+Les lignes d'annuaire sont paginées :
+
+```ruby
+lignes = client.annuaire.find_by_siret(siret, limite: 50, ignorer: 50).lignes_annuaire
+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 :
+
+```ruby
+resultat = client.annuaire.search_siret(
+  filtres: { denomination: "MINISTERE", etatAdministratif: "A" },
+  tris: { siret: :ascendant },
+  limite: 20
+)
+
+resultat.nombre_total
+resultat.map(&:siret)
+```
+
+## Transmission d'une facture Factur-X
+
+```ruby
+depot = client.flux.deposit_facturx("facture.pdf")
+depot.uid   # => "b18e3b6c-ccb7-4308-b527-35e5e6ee2145"
+```
+
+`deposit_facturx` accepte un chemin ou un objet IO, empaquette le PDF/A-3 dans l'archive `tar.gz`
+attendue par le PPF, l'encode en base64 et calcule le checksum sha256.
+
+La gem ne valide pas le contenu Factur-X : le fichier fourni doit déjà être conforme. Elle vérifie
+seulement, avant l'appel, qu'il s'agit bien d'un PDF et qu'un XML Factur-X y est joint — un
+garde-fou contre le mauvais fichier, dont le rejet ne serait connu que plusieurs minutes plus tard.
+
+Le montant TTC déclaré par le XML embarqué est exposé, à confronter à ce que le logiciel hôte
+attend :
+
+```ruby
+Cpro::Facturx.montant_total(File.binread("facture.pdf"))   # => BigDecimal("1910.40")
+```
+
+Le même endpoint accepte trois autres types de flux, qui ne diffèrent que par leur code interface :
+
+```ruby
+client.flux.deposit_ubl("facture.xml")          # FSO3110A — facture UBL 2.1
+client.flux.deposit_cdv("statut.xml")           # FSO3300A — cycle de vie (CDAR D22B)
+client.flux.deposit_ereporting("donnees.xml")   # FSO6000A — e-reporting
+```
+
+Émettre un statut de cycle de vie n'est donc pas un appel de mise à jour : c'est un dépôt de flux.
+Le fichier attendu est un CDAR D22B conforme à l'Annexe A de la norme AFNOR XP Z12-012 ; la gem le
+transporte sans le fabriquer.
+
+Le PPF répond 404 tant que le flux n'est pas traité. `status` renvoie donc `nil` dans ce cas, ce qui
+rend le polling naturel ; `status!` lève une `Cpro::NotFoundError` si vous préférez l'exception.
+
+```ruby
+statut = client.flux.status(depot)
+
+statut&.recevable?
+statut&.nom_flux          # renseigné uniquement si le flux est recevable
+statut&.date_maj_statut
+```
+
+Depuis Chorus Pro 5.2.2, un flux irrecevable expose son motif — auparavant le rejet était muet et
+ne pouvait se diagnostiquer que hors ligne :
+
+```ruby
+statut.motifs_rejet.each do |motif|
+  motif.code       # "IRR_SYNTAX"
+  motif.libelle    # "Contrôle syntaxique des fichiers du flux"
+  motif.notes.map { |note| [note.sujet, note.contenu] }
+end
+```
+
+## Suivre la facture après le dépôt
+
+Le statut du flux ne dit que la recevabilité de l'enveloppe. Le sort de la facture elle-même se lit
+via l'API Recherche Factures, en repartant du `nomFlux` :
+
+```ruby
+resultat = client.factures.search_by_nom_flux(statut)   # accepte un StatutFlux ou une chaîne
+facture  = client.factures.find(resultat.first)
+
+facture.statut              # "MISE_A_DISPOSITION"
+facture.encaissee?          # un prédicat par statut, sur les 22 de l'énumération
+facture.montant_total       # BigDecimal
+facture.historique.map { |changement| [changement.statut, changement.date] }
+facture.motifs_rejet.map(&:to_s)   # codes AFNOR et libellés, vides si aucun rejet
+```
+
+Les filtres de recherche sont **plats**, contrairement à ceux de l'Annuaire, et au moins un est
+obligatoire. Un filtre inconnu lève une `ArgumentError` avant tout appel réseau :
+
+```ruby
+client.factures.search(
+  filtres: { siretVendeur: "79614076743109", dateEmissionFactureDu: "2026-01-01" },
+  tris: { dateEmissionFacture: :descendant },
+  limite: 50, ignorer: 0
+)
+```
+
+L'historique n'est renseigné que par `find` ; la recherche ne le retourne pas.
+
+Deux points de vigilance. Un **résultat vide est ambigu** : l'API répond `204` aussi bien lorsque
+aucune facture ne correspond que lorsque le compte technique n'est rattaché ni à la structure
+émettrice ni à la destinataire. Et il **n'existe aucun mécanisme de notification** — ni webhook, ni
+callback, et les statuts des factures G2B ne sont pas consultables sur le portail Chorus Pro : le
+suivi passe nécessairement par une interrogation périodique de cette API.
+
+## Servir plusieurs entités
+
+L'AIFE distingue trois types de raccordement API. Celui qui s'applique détermine le modèle à
+adopter.
+
+**Concentrateur (éditeur clients légers)** — une solution web qui passe les appels pour le compte de
+ses clients. *« Seul le concentrateur a besoin d'une application sur PISTE ainsi que d'un
+raccordement Chorus Pro »*, et chaque entité cliente dispose de son propre compte technique. Une
+seule configuration suffit donc, et `with_account` porte l'entité — il partage le jeton OAuth et les
+connexions HTTP :
+
+```ruby
+client.with_account(compte_mairie).flux.deposit_facturx(facture_a)
+client.with_account(compte_departement).flux.deposit_facturx(facture_b)
+```
+
+**Éditeur clients lourds** — la solution est installée chez chaque client, qui appelle depuis ses
+propres serveurs. Chaque client a alors sa propre application PISTE et son propre raccordement : il
+lui faut sa configuration, donc son client. Conservez-les plutôt que de les reconstruire à chaque
+requête, le cache de jeton vivant sur la configuration.
+
+```ruby
+CLIENTS = entites.to_h do |entite|
+  configuration = Cpro::Configuration.new
+  configuration.client_id     = entite.piste_client_id
+  configuration.client_secret = entite.piste_client_secret
+  configuration.account       = Cpro::Account.new(login: entite.login, password: entite.password)
+
+  [entite.id, Cpro::Client.new(configuration)]
+end
+```
+
+Dans les deux cas, l'AIFE recommande que **chaque entité cliente crée elle-même son compte
+technique** et en transmette les identifiants, plutôt que l'éditeur ne se rattache aux structures de
+ses clients — pratique explicitement déconseillée pour des raisons de sécurité.
+
+## Erreurs
+
+Toutes les erreurs dérivent de `Cpro::Error`.
+
+| Exception | Déclenchement |
+| --- | --- |
+| `Cpro::ConfigurationError` | configuration incomplète, compte technique manquant |
+| `Cpro::RequestError` | 400, 406, 415, 422 |
+| `Cpro::AuthenticationError` | 401, échec d'obtention du jeton |
+| `Cpro::AuthorizationError` | 403 — habilitations insuffisantes |
+| `Cpro::NotFoundError` | 404 |
+| `Cpro::RateLimitError` | 429 |
+| `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.
+
+## Développement
+
+```bash
+bin/setup
+bundle exec rake      # tests unitaires + rubocop, aucun appel réseau
+```
+
+Les tests unitaires sont entièrement stubbés avec WebMock.
+
+### Conformité des messages CDAR
+
+Les cycles de vie produits par la gem sont confrontés au schéma de la norme CDAR D22B **et** au
+Schematron des règles françaises BR-FR-CDV. Les ressources sont versionnées dans
+[test/resources/cdar](test/resources/cdar) (Apache 2.0, dépôt FNFE France_RFE), donc ce contrôle
+tourne en CI sans installation ni accès réseau.
+
+La validation de schéma passe par Nokogiri. Le Schematron étant en XSLT 2.0, il demande Saxon : à
+défaut, cette moitié du test se saute au lieu d'échouer.
+
+```bash
+brew install saxon                    # macOS
+apt-get install -y libsaxonhe-java    # Debian/Ubuntu
+```
+
+### Tests sandbox
+
+`test/sandbox/` rejoue des échanges réellement enregistrés sur la sandbox PISTE, via des cassettes
+VCR commitées. Hors ligne, sans identifiants, exécutable en CI :
+
+```bash
+bundle exec rake test:sandbox
+```
+
+Toute requête absente des cassettes fait échouer le test plutôt que de partir sur le réseau. Pour
+ré-enregistrer après une évolution de l'API :
+
+```bash
+CPRO_RECORD=1 bundle exec rake test:sandbox
+```
+
+Le mode enregistrement exige `local/credentials.env` et **dépose réellement une facture** dans la
+sandbox. Les cassettes sont expurgées à l'écriture : identifiants PISTE et compte technique
+remplacés par des jetons de substitution, en-têtes `Authorization` et `cpro-account` supprimés,
+`access_token` écrasé. Un `CPRO_CREDENTIALS_FILE` permet de pointer un autre fichier d'identifiants.
+
+## Vérifié en sandbox
+
+Chaîne complète validée le 14/08/2026 : dépôt d'un Factur-X accepté (`uidFlux` retourné) puis flux
+`RECEVABLE`.
+
+- Le checksum est bien le **sha256 de la chaîne base64**, pas des octets de l'archive — confirmé par
+  un flux recevable, le PPF ayant validé l'intégrité.
+- Le nom de l'archive `tar.gz` n'est soumis à aucune règle ; celui du fichier qu'elle contient garde
+  son extension d'origine.
+- `cpro-account` est exigé par l'Annuaire aussi, contrairement à son swagger.
+- Chorus Pro 5.2.2 (19/08/2026) ajoute `codeStatut` et `detailStatut` à la consultation de flux, et
+  annonce un changement de format du `nomFlux` — n'écrivez donc rien qui présuppose son préfixe.
+- Les API datent en **UTC sans marquer le fuseau** (`2026-08-14T20:26:02.125919`). La gem le
+  rattrape : sans cela, la même réponse donnerait un instant différent selon le fuseau du serveur
+  hôte.
+- 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`,
+`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.
+
+```ruby
+client.annuaire.find_by_siret("71915767420316").lignes_annuaire.map(&:identifiant_adressage)
+# => ["719157674_71915767420316",
+#     "719157674_71915767420316_FACTURES_PUBLIQUES",
+#     "719157674_71915767420316_SERVICE_PUBLIQUE_1_71915767420316"]
+```
+
+## Licence
+
+Disponible en open source sous les termes de la [licence MIT](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"].exclude("test/sandbox/**/*_test.rb")
+end
+
+namespace :test do
+  desc "Rejoue les cassettes VCR de la sandbox PISTE (CPRO_RECORD=1 pour ré-enregistrer)"
+  Rake::TestTask.new(:sandbox) do |t|
+    t.libs << "test"
+    t.libs << "lib"
+    t.test_files = FileList["test/sandbox/**/*_test.rb"]
+  end
+end
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "cpro/client"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here