factpulse 2.0.29 → 2.0.30

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +3 -3
  3. data/Gemfile.lock +1 -1
  4. data/README.md +146 -133
  5. data/lib/factpulse/version.rb +1 -1
  6. metadata +2 -2
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 3b4230cb60b7f639cf36283a1a93fd182dc089c2ef0e362d0882610fe59bb7a9
4
- data.tar.gz: 88b51912bafaf2e0ca9e07c4a14308527af8535678821f519cab2e1aa0c0d407
3
+ metadata.gz: 78ca875881399d5d04602d4298a5fee55f3f7249fa347fe10e7aeb2fcb0dfd9d
4
+ data.tar.gz: b6ec7a089da11bc8b23e5aa4d181c027b7195f4e1c55c7ef9c5e7c06104831e4
5
5
  SHA512:
6
- metadata.gz: 613c3ac7e937bfb01e917c45f3c7b59d70355cda350a294dfbe2fc82d70629fe8d707dcd09d7aa80654c101ca7a7ad8fd1f74da76906ff271dfb4c1847a61f49
7
- data.tar.gz: 4a63439a540ab0304cf77d582ba291fdca9b84e715d05117b9a6be43c6ee8c878213ec5eb508ca39efb9600c1b2e61e8413d91c30f985ae9f2663ff72321bcc9
6
+ metadata.gz: 1c0ed4f46576b6b09ce2751926b947fad1a6200cb42c4c5f725df79984530b7c507761ed9fdef006671517749fce5f3f3bb327c4b0d67f1f244fb2d3f1787f93
7
+ data.tar.gz: e5ab5b82a5eb675daa30dbb8e129ba468616c41126ec5ee9aa17d7d907a4c17565472a86f513dfe456113de53b5adf005106200a7775348b52e045d69c74aadc
data/CHANGELOG.md CHANGED
@@ -7,7 +7,7 @@ et ce projet adhère au [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
- ## [2.0.29] - 2025-11-28
10
+ ## [2.0.30] - 2025-11-29
11
11
 
12
12
  ### Added
13
13
  - Version initiale du SDK ruby
@@ -24,5 +24,5 @@ et ce projet adhère au [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
24
24
  - Guide d'authentification JWT
25
25
  - Configuration avancée (timeout, proxy, debug)
26
26
 
27
- [Unreleased]: https://github.com/factpulse/sdk-ruby/compare/v2.0.29...HEAD
28
- [2.0.29]: https://github.com/factpulse/sdk-ruby/releases/tag/v2.0.29
27
+ [Unreleased]: https://github.com/factpulse/sdk-ruby/compare/v2.0.30...HEAD
28
+ [2.0.30]: https://github.com/factpulse/sdk-ruby/releases/tag/v2.0.30
data/Gemfile.lock CHANGED
@@ -1,7 +1,7 @@
1
1
  PATH
2
2
  remote: .
3
3
  specs:
4
- factpulse (2.0.29)
4
+ factpulse (2.0.30)
5
5
  typhoeus (~> 1.0, >= 1.0.1)
6
6
 
7
7
  GEM
data/README.md CHANGED
@@ -2,16 +2,15 @@
2
2
 
3
3
  Client Ruby officiel pour l'API FactPulse - Facturation électronique française.
4
4
 
5
- ## 🎯 Fonctionnalités
5
+ ## Fonctionnalités
6
6
 
7
7
  - **Factur-X** : Génération et validation de factures électroniques (profils MINIMUM, BASIC, EN16931, EXTENDED)
8
8
  - **Chorus Pro** : Intégration avec la plateforme de facturation publique française
9
9
  - **AFNOR PDP/PA** : Soumission de flux conformes à la norme XP Z12-013
10
10
  - **Signature électronique** : Signature PDF (PAdES-B-B, PAdES-B-T, PAdES-B-LT)
11
11
  - **Client simplifié** : Authentification JWT et polling intégrés via `helpers`
12
- - **Ruby 2.7+** : Compatible avec les versions modernes de Ruby
13
12
 
14
- ## 🚀 Installation
13
+ ## Installation
15
14
 
16
15
  ```bash
17
16
  gem install factpulse
@@ -23,9 +22,7 @@ Ou dans votre Gemfile :
23
22
  gem 'factpulse'
24
23
  ```
25
24
 
26
- ## 📖 Démarrage rapide
27
-
28
- ### Méthode recommandée : Client simplifié avec helpers
25
+ ## Démarrage rapide
29
26
 
30
27
  Le module `helpers` offre une API simplifiée avec authentification et polling automatiques :
31
28
 
@@ -33,175 +30,191 @@ Le module `helpers` offre une API simplifiée avec authentification et polling a
33
30
  require 'factpulse'
34
31
  require 'factpulse/helpers'
35
32
 
36
- # Créer le client (authentification automatique)
37
- client = Factpulse::Helpers::FactPulseClient.new(
38
- email: 'votre_email@example.com',
39
- password: 'votre_mot_de_passe'
33
+ include Factpulse::Helpers
34
+
35
+ # Créer le client
36
+ client = FactPulseClient.new(
37
+ 'votre_email@example.com',
38
+ 'votre_mot_de_passe'
40
39
  )
41
40
 
42
- # Données de la facture
41
+ # Construire la facture avec les helpers
43
42
  facture_data = {
44
- numero_facture: 'FAC-2025-001',
45
- date_facture: '2025-01-15',
46
- fournisseur: {
47
- nom: 'Mon Entreprise SAS',
48
- siret: '12345678901234',
49
- adresse_postale: {
50
- ligne_un: '123 Rue Example',
51
- code_postal: '75001',
52
- nom_ville: 'Paris',
53
- pays_code_iso: 'FR'
54
- }
55
- },
56
- destinataire: {
57
- nom: 'Client SARL',
58
- siret: '98765432109876',
59
- adresse_postale: {
60
- ligne_un: '456 Avenue Test',
61
- code_postal: '69001',
62
- nom_ville: 'Lyon',
63
- pays_code_iso: 'FR'
64
- }
65
- },
66
- montant_total: {
67
- montant_ht_total: '1000.00',
68
- montant_tva: '200.00',
69
- montant_ttc_total: '1200.00',
70
- montant_a_payer: '1200.00'
71
- },
72
- lignes_de_poste: [{
73
- numero: 1,
74
- denomination: 'Prestation de conseil',
75
- quantite: '10.00',
76
- unite: 'PIECE',
77
- montant_unitaire_ht: '100.00'
78
- }]
43
+ numeroFacture: 'FAC-2025-001',
44
+ dateFacture: '2025-01-15',
45
+ fournisseur: fournisseur(
46
+ 'Mon Entreprise SAS',
47
+ '12345678901234',
48
+ '123 Rue Example',
49
+ '75001',
50
+ 'Paris'
51
+ ),
52
+ destinataire: destinataire(
53
+ 'Client SARL',
54
+ '98765432109876',
55
+ '456 Avenue Test',
56
+ '69001',
57
+ 'Lyon'
58
+ ),
59
+ montantTotal: montant_total(1000.00, 200.00, 1200.00, 1200.00),
60
+ lignesDePoste: [
61
+ ligne_de_poste(1, 'Prestation de conseil', 10, 100.00, 1000.00)
62
+ ],
63
+ lignesDeTva: [
64
+ ligne_de_tva(1000.00, 200.00)
65
+ ]
79
66
  }
80
67
 
81
- # Lire le PDF source
82
- pdf_source = File.binread('facture_source.pdf')
83
-
84
- # Générer le PDF Factur-X (polling automatique)
85
- pdf_bytes = client.generer_facturx(
86
- facture_data,
87
- pdf_source,
88
- profil: 'EN16931',
89
- format_sortie: 'pdf',
90
- sync: true # Attend le résultat automatiquement
91
- )
68
+ # Générer le PDF Factur-X
69
+ pdf_bytes = client.generer_facturx(facture_data, 'facture_source.pdf', 'EN16931')
92
70
 
93
- # Sauvegarder
94
71
  File.binwrite('facture_facturx.pdf', pdf_bytes)
95
72
  ```
96
73
 
97
- ### Méthode alternative : SDK brut
74
+ ## Helpers disponibles (module Factpulse::Helpers)
98
75
 
99
- Pour un contrôle total, utilisez le SDK généré directement :
76
+ ### montant(value)
77
+
78
+ Convertit une valeur en string formaté pour les montants monétaires.
100
79
 
101
80
  ```ruby
102
- require 'factpulse'
103
- require 'net/http'
104
- require 'json'
105
-
106
- # 1. Obtenir le token JWT
107
- uri = URI('https://factpulse.fr/api/token/')
108
- http = Net::HTTP.new(uri.host, uri.port)
109
- http.use_ssl = true
110
-
111
- request = Net::HTTP::Post.new(uri.path, { 'Content-Type' => 'application/json' })
112
- request.body = {
113
- username: 'votre_email@example.com',
114
- password: 'votre_mot_de_passe'
115
- }.to_json
116
-
117
- response = http.request(request)
118
- token = JSON.parse(response.body)['access']
119
-
120
- # 2. Configurer le client
121
- Factpulse.configure do |config|
122
- config.host = 'https://factpulse.fr/api/facturation'
123
- config.access_token = token
124
- end
125
-
126
- # 3. Appeler l'API
127
- api = Factpulse::TraitementFactureApi.new
128
- response = api.generer_facture_api_v1_traitement_generer_facture_post(
129
- facture_data.to_json,
130
- 'EN16931',
131
- 'pdf',
132
- File.open('facture_source.pdf', 'rb')
81
+ include Factpulse::Helpers
82
+
83
+ montant(1234.5) # "1234.50"
84
+ montant('1234.56') # "1234.56"
85
+ montant(nil) # "0.00"
86
+ ```
87
+
88
+ ### montant_total(ht, tva, ttc, a_payer, ...)
89
+
90
+ Crée un objet MontantTotal complet.
91
+
92
+ ```ruby
93
+ total = montant_total(
94
+ 1000.00, # ht
95
+ 200.00, # tva
96
+ 1200.00, # ttc
97
+ 1200.00, # a_payer
98
+ 50.00, # remise_ttc (optionnel)
99
+ 'Fidélité', # motif_remise (optionnel)
100
+ 100.00 # acompte (optionnel)
133
101
  )
102
+ ```
103
+
104
+ ### ligne_de_poste(numero, denomination, quantite, montant_unitaire_ht, montant_total_ligne_ht, ...)
134
105
 
135
- # 4. Polling manuel pour récupérer le résultat
136
- task_id = response.id_tache
137
- # ... (implémenter le polling)
106
+ Crée une ligne de facturation.
107
+
108
+ ```ruby
109
+ ligne = ligne_de_poste(
110
+ 1,
111
+ 'Prestation de conseil',
112
+ 5,
113
+ 200.00,
114
+ 1000.00, # montant_total_ligne_ht requis
115
+ 'S', # categorie_tva: S, Z, E, AE, K
116
+ 'HEURE', # unite: FORFAIT, PIECE, HEURE, JOUR...
117
+ {
118
+ taux_tva: 'TVA20', # Ou taux_tva_manuel: '20.00'
119
+ reference: 'REF-001'
120
+ }
121
+ )
138
122
  ```
139
123
 
140
- ## 🔧 Avantages des helpers
124
+ ### ligne_de_tva(montant_base_ht, montant_tva, ...)
141
125
 
142
- | Fonctionnalité | SDK brut | helpers |
143
- |----------------|----------|---------|
144
- | Authentification | Manuelle | Automatique |
145
- | Refresh token | Manuel | Automatique |
146
- | Polling tâches async | Manuel | Automatique (backoff) |
147
- | Retry sur 401 | Manuel | Automatique |
126
+ Crée une ligne de ventilation TVA.
148
127
 
149
- ## 🔑 Options d'authentification
128
+ ```ruby
129
+ tva = ligne_de_tva(
130
+ 1000.00, # montant_base_ht
131
+ 200.00, # montant_tva
132
+ 'S', # categorie: S, Z, E, AE, K
133
+ { taux: 'TVA20' } # Ou taux_manuel: '20.00'
134
+ )
135
+ ```
150
136
 
151
- ### Client UID (multi-clients)
137
+ ### adresse_postale(ligne1, code_postal, ville, ...)
152
138
 
153
- Si vous gérez plusieurs clients :
139
+ Crée une adresse postale structurée.
154
140
 
155
141
  ```ruby
156
- client = Factpulse::Helpers::FactPulseClient.new(
157
- email: 'votre_email@example.com',
158
- password: 'votre_mot_de_passe',
159
- client_uid: 'identifiant_client' # UID du client cible
142
+ adresse = adresse_postale(
143
+ '123 Rue de la République',
144
+ '75001',
145
+ 'Paris',
146
+ 'FR', # pays (défaut: 'FR')
147
+ 'Bâtiment A' # ligne2 (optionnel)
160
148
  )
161
149
  ```
162
150
 
163
- ### Configuration avancée
151
+ ### fournisseur(nom, siret, adresse_ligne1, code_postal, ville, options)
152
+
153
+ Crée un fournisseur complet avec calcul automatique du SIREN et TVA intra.
164
154
 
165
155
  ```ruby
166
- client = Factpulse::Helpers::FactPulseClient.new(
167
- email: 'votre_email@example.com',
168
- password: 'votre_mot_de_passe',
169
- api_url: 'https://factpulse.fr', # URL personnalisée
170
- polling_interval: 2.0, # Intervalle de polling initial (secondes)
171
- polling_timeout: 120.0, # Timeout de polling (secondes)
172
- max_retries: 2 # Tentatives en cas de 401
156
+ f = fournisseur(
157
+ 'Ma Société SAS',
158
+ '12345678901234',
159
+ '123 Rue Example',
160
+ '75001',
161
+ 'Paris',
162
+ { iban: 'FR7630006000011234567890189' }
173
163
  )
164
+ # SIREN et TVA intracommunautaire calculés automatiquement
174
165
  ```
175
166
 
176
- ## 💡 Formats de montants acceptés
167
+ ### destinataire(nom, siret, adresse_ligne1, code_postal, ville, options)
177
168
 
178
- L'API accepte plusieurs formats pour les montants :
169
+ Crée un destinataire (client) avec calcul automatique du SIREN.
179
170
 
180
171
  ```ruby
181
- # String (recommandé pour la précision)
182
- montant = '1234.56'
172
+ d = destinataire(
173
+ 'Client SARL',
174
+ '98765432109876',
175
+ '456 Avenue Test',
176
+ '69001',
177
+ 'Lyon'
178
+ )
179
+ ```
183
180
 
184
- # Float
185
- montant = 1234.56
181
+ ## Mode Zero-Trust (Chorus Pro / AFNOR)
186
182
 
187
- # Integer
188
- montant = 1234
183
+ Pour passer vos propres credentials sans stockage côté serveur :
189
184
 
190
- # BigDecimal
191
- require 'bigdecimal'
192
- montant = BigDecimal('1234.56')
185
+ ```ruby
186
+ include Factpulse::Helpers
187
+
188
+ chorus_creds = ChorusProCredentials.new(
189
+ 'votre_client_id',
190
+ 'votre_client_secret',
191
+ 'votre_login',
192
+ 'votre_password',
193
+ true # sandbox
194
+ )
193
195
 
194
- # Helper de formatage
195
- montant_formate = Factpulse::Helpers::FactPulseClient.format_montant(1234.5) # => "1234.50"
196
+ afnor_creds = AFNORCredentials.new(
197
+ 'https://api.pdp.fr/flow/v1',
198
+ 'https://auth.pdp.fr/oauth/token',
199
+ 'votre_client_id',
200
+ 'votre_client_secret'
201
+ )
202
+
203
+ client = FactPulseClient.new(
204
+ 'votre_email@example.com',
205
+ 'votre_mot_de_passe',
206
+ nil, # api_url
207
+ nil, # client_uid
208
+ chorus_creds,
209
+ afnor_creds
210
+ )
196
211
  ```
197
212
 
198
- ## 📚 Ressources
213
+ ## Ressources
199
214
 
200
215
  - **Documentation API** : https://factpulse.fr/api/facturation/documentation
201
- - **Code source** : https://github.com/factpulse/sdk-ruby
202
- - **Issues** : https://github.com/factpulse/sdk-ruby/issues
203
216
  - **Support** : contact@factpulse.fr
204
217
 
205
- ## 📄 Licence
218
+ ## Licence
206
219
 
207
220
  MIT License - Copyright (c) 2025 FactPulse
data/lib/factpulse/version.rb CHANGED
@@ -11,5 +11,5 @@ Generator version: 7.18.0-SNAPSHOT
11
11
  =end
12
12
 
13
13
  module FactPulse
14
- VERSION = '2.0.29'
14
+ VERSION = '2.0.30'
15
15
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: factpulse
3
3
  version: !ruby/object:Gem::Version
4
- version: 2.0.29
4
+ version: 2.0.30
5
5
  platform: ruby
6
6
  authors:
7
7
  - OpenAPI-Generator
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2025-11-28 00:00:00.000000000 Z
11
+ date: 2025-11-29 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: typhoeus