factpulse 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 555565849759eba51afaa2f06f3e61aee4b41845b4c0199313382a74bc2d3173
-  data.tar.gz: ac9262699e7003ae0766c6270681cffbdd62a690499311f8aab320a75d95d68e
+  metadata.gz: 4b18d85cbff7b4e8aa1f678bc18acba5121fd4b5df4b160a86b785bf56f4ec35
+  data.tar.gz: a7205107926d1a7b97474851c10a6af637281168926dcecc037675a6d3783c2f
 SHA512:
-  metadata.gz: 4b2ab05ca8d3cb5f4cbe4621dd47f5f28e96af933bacf286d3ee153f52b89c733954c8f132f46061be0cbb0fe6e8de2992cdef602ae8e1c03466082d1225b646
-  data.tar.gz: 49bbc6f27eddfd7e24d798f90b45d48f8a89b6b05328864d341bf47b66a23dfb8df9cc73c9358a88e1b6289d36293ebf8f0f8f1765ce7de5e3aca1a428625a3a
+  metadata.gz: 43f8765a2cb63397a997f530c8d050faf120b7bd5be88acb8261f44f4dbfbda376f3dbc472b8194d6fee113246553165d4c19a329a919deae0af54580f96aa4e
+  data.tar.gz: 81cca817bfa1fdbc3d743f3feb49ab8ac19543aa8a2d4cd06f13f8866ebb1330f935e2870f9ee554effcaa548c80c348be98004189961a6e751deb7c044d06f7

data/CHANGELOG.md

@@ -7,11 +7,22 @@ et ce projet adhère au [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
-## [0.1.0] - 2026-02-02
+## [1.0.0] - 2025-11-27
 
 ### Added
-- Ajoute API gestion de clients
+- Version initiale du SDK ruby
+- Support complet de l'API FactPulse v1.0.0
+- Endpoints Factur-X (génération, validation)
+- Endpoints AFNOR PDP/PA (Flow Service, Directory Service)
+- Endpoints Chorus Pro (recherche entreprise, soumission factures)
+- Endpoints Signature électronique (PAdES-B-B, PAdES-B-T, PAdES-B-LT)
+- Support des deux modes d'authentification (stored credentials et zero-trust)
+- Documentation complète et exemples
 
+### Documentation
+- README.md avec quickstart et exemples
+- Guide d'authentification JWT
+- Configuration avancée (timeout, proxy, debug)
 
-[Unreleased]: https://github.com/factpulse/sdk-ruby/compare/v0.1.0...HEAD
-[0.1.0]: https://github.com/factpulse/sdk-ruby/releases/tag/v0.1.0
+[Unreleased]: https://github.com/factpulse/sdk-ruby/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/factpulse/sdk-ruby/releases/tag/v1.0.0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    factpulse (0.1.0)
+    factpulse (1.0.0)
       typhoeus (~> 1.0, >= 1.0.1)
 
 GEM
@@ -10,15 +10,15 @@ GEM
     ast (2.4.3)
     byebug (11.1.3)
     coderay (1.1.3)
-    date (3.5.1)
+    date (3.5.0)
     diff-lcs (1.6.2)
     ethon (0.15.0)
       ffi (>= 1.15.0)
-    ffi (1.17.3)
+    ffi (1.17.2)
     jaro_winkler (1.5.6)
     method_source (1.1.0)
     parallel (1.27.0)
-    parser (3.3.10.1)
+    parser (3.3.10.0)
       ast (~> 2.4.1)
       racc
     pry (0.14.2)
@@ -27,7 +27,7 @@ GEM
     pry-byebug (3.10.1)
       byebug (~> 11.0)
       pry (>= 0.13, < 0.15)
-    psych (5.3.1)
+    psych (5.2.6)
       date
       stringio
     racc (1.8.1)
@@ -45,7 +45,7 @@ GEM
     rspec-mocks (3.13.7)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.7)
+    rspec-support (3.13.6)
     rubocop (0.66.0)
       jaro_winkler (~> 1.5.1)
       parallel (~> 1.10)
@@ -55,7 +55,7 @@ GEM
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 1.4.0, < 1.6)
     ruby-progressbar (1.13.0)
-    stringio (3.2.0)
+    stringio (3.1.8)
     typhoeus (1.5.0)
       ethon (>= 0.9.0, < 0.16.0)
     unicode-display_width (1.5.0)

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 FactPulse
+Copyright (c) 2025 FactPulse
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,220 +1,207 @@
 # FactPulse SDK Ruby
 
-Official Ruby client for the FactPulse API - French electronic invoicing.
+Client Ruby officiel pour l'API FactPulse - Facturation électronique française.
 
-## Features
+## 🎯 Fonctionnalités
 
-- **Factur-X**: Generation and validation of electronic invoices (MINIMUM, BASIC, EN16931, EXTENDED profiles)
-- **Chorus Pro**: Integration with the French public invoicing platform
-- **AFNOR PDP/PA**: Submission of flows compliant with XP Z12-013 standard
-- **Electronic signature**: PDF signing (PAdES-B-B, PAdES-B-T, PAdES-B-LT)
-- **Thin HTTP wrapper**: Generic `post` and `get` methods with automatic JWT auth and polling
+- **Factur-X** : Génération et validation de factures électroniques (profils MINIMUM, BASIC, EN16931, EXTENDED)
+- **Chorus Pro** : Intégration avec la plateforme de facturation publique française
+- **AFNOR PDP/PA** : Soumission de flux conformes à la norme XP Z12-013
+- **Signature électronique** : Signature PDF (PAdES-B-B, PAdES-B-T, PAdES-B-LT)
+- **Client simplifié** : Authentification JWT et polling intégrés via `helpers`
+- **Ruby 2.7+** : Compatible avec les versions modernes de Ruby
 
-## Installation
+## 🚀 Installation
 
 ```bash
 gem install factpulse
 ```
 
-Or in your Gemfile:
+Ou dans votre Gemfile :
 
 ```ruby
 gem 'factpulse'
 ```
 
-## Quick Start
+## 📖 Démarrage rapide
+
+### Méthode recommandée : Client simplifié avec helpers
+
+Le module `helpers` offre une API simplifiée avec authentification et polling automatiques :
 
 ```ruby
 require 'factpulse'
-require 'base64'
+require 'factpulse/helpers'
 
-# Create the client
-client = FactPulse::Client.new(
-  email: 'your_email@example.com',
-  password: 'your_password',
-  client_uid: 'your-client-uuid'  # From dashboard: Configuration > Clients
+# Créer le client (authentification automatique)
+client = Factpulse::Helpers::FactPulseClient.new(
+  email: 'votre_email@example.com',
+  password: 'votre_mot_de_passe'
 )
 
-# Read your source PDF
-pdf_b64 = Base64.strict_encode64(File.binread('source_invoice.pdf'))
-
-# Generate Factur-X and submit to PDP in one call
-result = client.post('processing/invoices/submit-complete-async',
-  invoiceData: {
-    number: 'INV-2025-001',
-    supplier: {
-      name: 'ACME Corporation',
-      siret: '12345678901234',
-      iban: 'FR7630001007941234567890185',
-      routing_address: '12345678901234'
-    },
-    recipient: {
-      name: 'Client Company SA',
-      siret: '98765432109876',
-      routing_address: '98765432109876'
-    },
-    lines: [
-      {
-        description: 'Consulting services',
-        quantity: 10,
-        unitPrice: 100.0,
-        vatRate: 20.0
-      }
-    ]
+# Données de la facture
+facture_data = {
+  numero_facture: 'FAC-2025-001',
+  date_facture: '2025-01-15',
+  fournisseur: {
+    nom: 'Mon Entreprise SAS',
+    siret: '12345678901234',
+    adresse_postale: {
+      ligne_un: '123 Rue Example',
+      code_postal: '75001',
+      nom_ville: 'Paris',
+      pays_code_iso: 'FR'
+    }
+  },
+  destinataire: {
+    nom: 'Client SARL',
+    siret: '98765432109876',
+    adresse_postale: {
+      ligne_un: '456 Avenue Test',
+      code_postal: '69001',
+      nom_ville: 'Lyon',
+      pays_code_iso: 'FR'
+    }
+  },
+  montant_total: {
+    montant_ht_total: '1000.00',
+    montant_tva: '200.00',
+    montant_ttc_total: '1200.00',
+    montant_a_payer: '1200.00'
   },
-  sourcePdf: pdf_b64,
-  profile: 'EN16931',
-  destination: { type: 'afnor' }
+  lignes_de_poste: [{
+    numero: 1,
+    denomination: 'Prestation de conseil',
+    quantite: '10.00',
+    unite: 'PIECE',
+    montant_unitaire_ht: '100.00'
+  }]
+}
+
+# Lire le PDF source
+pdf_source = File.binread('facture_source.pdf')
+
+# Générer le PDF Factur-X (polling automatique)
+pdf_bytes = client.generer_facturx(
+  facture_data,
+  pdf_source,
+  profil: 'EN16931',
+  format_sortie: 'pdf',
+  sync: true  # Attend le résultat automatiquement
 )
 
-# PDF is in result['content'] (auto-polled, auto-decoded)
-File.binwrite('facturx_invoice.pdf', result['content'])
-
-puts "Flow ID: #{result['afnorResult']['flowId']}"
+# Sauvegarder
+File.binwrite('facture_facturx.pdf', pdf_bytes)
 ```
 
-## API Methods
+### Méthode alternative : SDK brut
 
-The SDK provides two generic methods that map directly to API endpoints:
+Pour un contrôle total, utilisez le SDK généré directement :
 
 ```ruby
-# POST /api/v1/{path}
-result = client.post('path/to/endpoint', key1: value1, key2: value2)
-
-# GET /api/v1/{path}
-result = client.get('path/to/endpoint', param1: value1)
-```
+require 'factpulse'
+require 'net/http'
+require 'json'
 
-### Common Endpoints
+# 1. Obtenir le token JWT
+uri = URI('https://factpulse.fr/api/token/')
+http = Net::HTTP.new(uri.host, uri.port)
+http.use_ssl = true
 
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `processing/invoices/submit-complete-async` | POST | Generate Factur-X + submit to PDP |
-| `processing/generate-invoice` | POST | Generate Factur-X XML or PDF |
-| `processing/validate-xml` | POST | Validate Factur-X XML |
-| `processing/validate-facturx-pdf` | POST | Validate Factur-X PDF |
-| `processing/sign-pdf` | POST | Sign PDF with certificate |
-| `afnor/flow/v1/flows` | POST | Submit flow to AFNOR PDP |
-| `afnor/incoming-flows/{flow_id}` | GET | Get incoming invoice |
-| `chorus-pro/factures/soumettre` | POST | Submit to Chorus Pro |
+request = Net::HTTP::Post.new(uri.path, { 'Content-Type' => 'application/json' })
+request.body = {
+  username: 'votre_email@example.com',
+  password: 'votre_mot_de_passe'
+}.to_json
 
-## Webhooks
+response = http.request(request)
+token = JSON.parse(response.body)['access']
 
-Instead of polling, you can receive results via webhook by adding `callbackUrl`:
+# 2. Configurer le client
+Factpulse.configure do |config|
+  config.host = 'https://factpulse.fr/api/facturation'
+  config.access_token = token
+end
 
-```ruby
-result = client.post('processing/invoices/submit-complete-async',
-  invoiceData: invoice_data,
-  sourcePdf: pdf_b64,
-  destination: { type: 'afnor' },
-  callbackUrl: 'https://your-server.com/webhook/factpulse',
-  webhookMode: 'INLINE'  # or 'DOWNLOAD_URL'
+# 3. Appeler l'API
+api = Factpulse::TraitementFactureApi.new
+response = api.generer_facture_api_v1_traitement_generer_facture_post(
+  facture_data.to_json,
+  'EN16931',
+  'pdf',
+  File.open('facture_source.pdf', 'rb')
 )
 
-task_id = result['taskId']
-# Result will be POSTed to your webhook URL
+# 4. Polling manuel pour récupérer le résultat
+task_id = response.id_tache
+# ... (implémenter le polling)
 ```
 
-### Webhook Receiver Example (Sinatra)
+## 🔧 Avantages des helpers
 
-```ruby
-require 'sinatra'
-require 'json'
-require 'openssl'
-
-WEBHOOK_SECRET = 'your-shared-secret'
+| Fonctionnalité | SDK brut | helpers |
+|----------------|----------|---------|
+| Authentification | Manuelle | Automatique |
+| Refresh token | Manuel | Automatique |
+| Polling tâches async | Manuel | Automatique (backoff) |
+| Retry sur 401 | Manuel | Automatique |
 
-def verify_signature(payload, signature)
-  return false unless signature&.start_with?('sha256=')
+## 🔑 Options d'authentification
 
-  expected = OpenSSL::HMAC.hexdigest('SHA256', WEBHOOK_SECRET, payload)
-  Rack::Utils.secure_compare(expected, signature[7..])
-end
+### Client UID (multi-clients)
 
-post '/webhook/factpulse' do
-  payload = request.body.read
-  signature = request.env['HTTP_X_WEBHOOK_SIGNATURE']
+Si vous gérez plusieurs clients :
 
-  unless verify_signature(payload, signature)
-    halt 401, { error: 'Invalid signature' }.to_json
-  end
-
-  event = JSON.parse(payload)
-  event_type = event['event_type']
-  data = event['data']
-
-  case event_type
-  when 'submission.completed'
-    flow_id = data.dig('afnorResult', 'flowId')
-    puts "Invoice submitted: #{flow_id}"
-  when 'submission.failed'
-    puts "Submission failed: #{data['error']}"
-  end
-
-  content_type :json
-  { status: 'received' }.to_json
-end
+```ruby
+client = Factpulse::Helpers::FactPulseClient.new(
+  email: 'votre_email@example.com',
+  password: 'votre_mot_de_passe',
+  client_uid: 'identifiant_client'  # UID du client cible
+)
 ```
 
-### Webhook Event Types
-
-| Event | Description |
-|-------|-------------|
-| `generation.completed` | Factur-X generated successfully |
-| `generation.failed` | Generation failed |
-| `validation.completed` | Validation passed |
-| `validation.failed` | Validation failed |
-| `signature.completed` | PDF signed |
-| `submission.completed` | Submitted to PDP/Chorus |
-| `submission.failed` | Submission failed |
-
-## Zero-Storage Mode
-
-Pass PDP credentials directly in the request (no server-side storage):
+### Configuration avancée
 
 ```ruby
-result = client.post('processing/invoices/submit-complete-async',
-  invoiceData: invoice_data,
-  sourcePdf: pdf_b64,
-  destination: {
-    type: 'afnor',
-    flowServiceUrl: 'https://api.pdp.example.com/flow/v1',
-    tokenUrl: 'https://auth.pdp.example.com/oauth/token',
-    clientId: 'your_pdp_client_id',
-    clientSecret: 'your_pdp_client_secret'
-  }
+client = Factpulse::Helpers::FactPulseClient.new(
+  email: 'votre_email@example.com',
+  password: 'votre_mot_de_passe',
+  api_url: 'https://factpulse.fr',  # URL personnalisée
+  polling_interval: 2.0,  # Intervalle de polling initial (secondes)
+  polling_timeout: 120.0,  # Timeout de polling (secondes)
+  max_retries: 2  # Tentatives en cas de 401
 )
 ```
 
-## Error Handling
+## 💡 Formats de montants acceptés
+
+L'API accepte plusieurs formats pour les montants :
 
 ```ruby
-require 'factpulse'
+# String (recommandé pour la précision)
+montant = '1234.56'
 
-begin
-  result = client.post('processing/validate-xml', xmlContent: xml_string)
-rescue FactPulse::Error => e
-  puts "Error: #{e.message}"
-  puts "Status code: #{e.status_code}"
-  puts "Details: #{e.details}"
-end
-```
+# Float
+montant = 1234.56
 
-## Available Helpers
+# Integer
+montant = 1234
 
-The SDK provides the following helper classes:
+# BigDecimal
+require 'bigdecimal'
+montant = BigDecimal('1234.56')
 
-- `FactPulse::Client`: Main HTTP client with auto-auth and polling
-- `FactPulse::Error`: Base exception class
-- `FactPulse::AuthError`: Authentication failure
-- `FactPulse::ValidationError`: Validation errors with details
-- `FactPulse::PollingTimeout`: Task polling timeout
+# Helper de formatage
+montant_formate = Factpulse::Helpers::FactPulseClient.format_montant(1234.5)  # => "1234.50"
+```
 
-## Resources
+## 📚 Ressources
 
-- **API Documentation**: https://factpulse.fr/api/facturation/documentation
-- **Support**: contact@factpulse.fr
+- **Documentation API** : https://factpulse.fr/api/facturation/documentation
+- **Code source** : https://github.com/factpulse/sdk-ruby
+- **Issues** : https://github.com/factpulse/sdk-ruby/issues
+- **Support** : contact@factpulse.fr
 
-## License
+## 📄 Licence
 
 MIT License - Copyright (c) 2025 FactPulse

data/docs/AFNORPDPPAApi.md

@@ -1,100 +1,19 @@
 # FactPulse::AFNORPDPPAApi
 
-All URIs are relative to *https://factpulse.fr*
+All URIs are relative to *http://localhost*
 
 | Method | HTTP request | Description |
 | ------ | ------------ | ----------- |
-| [**get_flux_entrant_api_v1_afnor_incoming_flows_flow_id_get**](AFNORPDPPAApi.md#get_flux_entrant_api_v1_afnor_incoming_flows_flow_id_get) | **GET** /api/v1/afnor/incoming-flows/{flow_id} | Retrieve and extract an incoming invoice |
-| [**oauth_token_proxy_api_v1_afnor_oauth_token_post**](AFNORPDPPAApi.md#oauth_token_proxy_api_v1_afnor_oauth_token_post) | **POST** /api/v1/afnor/oauth/token | Test PDP OAuth2 credentials |
-
-
-## get_flux_entrant_api_v1_afnor_incoming_flows_flow_id_get
-
-> <IncomingInvoice> get_flux_entrant_api_v1_afnor_incoming_flows_flow_id_get(flow_id, opts)
-
-Retrieve and extract an incoming invoice
-
-Downloads an incoming flow from the AFNOR PDP and extracts invoice metadata into a unified JSON format. Supports Factur-X, CII, and UBL formats.
-
-### Examples
-
-```ruby
-require 'time'
-require 'factpulse'
-# setup authorization
-FactPulse.configure do |config|
-  # Configure API key authorization: APIKeyHeader
-  config.api_key['X-API-Key'] = 'YOUR API KEY'
-  # Uncomment the following line to set a prefix for the API key, e.g. 'Bearer' (defaults to nil)
-  # config.api_key_prefix['X-API-Key'] = 'Bearer'
-
-  # Configure Bearer authorization: HTTPBearer
-  config.access_token = 'YOUR_BEARER_TOKEN'
-end
-
-api_instance = FactPulse::AFNORPDPPAApi.new
-flow_id = 'flow_id_example' # String | AFNOR flow ID (UUID format)
-opts = {
-  include_document: true, # Boolean | Include base64-encoded document in response
-  x_encryption_key: 'x_encryption_key_example' # String | Client encryption key for double encryption mode. Must be a base64-encoded AES-256 key (32 bytes). Required only when accessing resources encrypted with encryption_mode='double'.
-}
-
-begin
-  # Retrieve and extract an incoming invoice
-  result = api_instance.get_flux_entrant_api_v1_afnor_incoming_flows_flow_id_get(flow_id, opts)
-  p result
-rescue FactPulse::ApiError => e
-  puts "Error when calling AFNORPDPPAApi->get_flux_entrant_api_v1_afnor_incoming_flows_flow_id_get: #{e}"
-end
-```
-
-#### Using the get_flux_entrant_api_v1_afnor_incoming_flows_flow_id_get_with_http_info variant
-
-This returns an Array which contains the response data, status code and headers.
-
-> <Array(<IncomingInvoice>, Integer, Hash)> get_flux_entrant_api_v1_afnor_incoming_flows_flow_id_get_with_http_info(flow_id, opts)
-
-```ruby
-begin
-  # Retrieve and extract an incoming invoice
-  data, status_code, headers = api_instance.get_flux_entrant_api_v1_afnor_incoming_flows_flow_id_get_with_http_info(flow_id, opts)
-  p status_code # => 2xx
-  p headers # => { ... }
-  p data # => <IncomingInvoice>
-rescue FactPulse::ApiError => e
-  puts "Error when calling AFNORPDPPAApi->get_flux_entrant_api_v1_afnor_incoming_flows_flow_id_get_with_http_info: #{e}"
-end
-```
-
-### Parameters
-
-| Name | Type | Description | Notes |
-| ---- | ---- | ----------- | ----- |
-| **flow_id** | **String** | AFNOR flow ID (UUID format) |  |
-| **include_document** | **Boolean** | Include base64-encoded document in response | [optional][default to false] |
-| **x_encryption_key** | **String** | Client encryption key for double encryption mode. Must be a base64-encoded AES-256 key (32 bytes). Required only when accessing resources encrypted with encryption_mode&#x3D;&#39;double&#39;. | [optional] |
-
-### Return type
-
-[**IncomingInvoice**](IncomingInvoice.md)
-
-### Authorization
-
-[APIKeyHeader](../README.md#APIKeyHeader), [HTTPBearer](../README.md#HTTPBearer)
-
-### HTTP request headers
-
-- **Content-Type**: Not defined
-- **Accept**: application/json
+| [**oauth_token_proxy_api_v1_afnor_oauth_token_post**](AFNORPDPPAApi.md#oauth_token_proxy_api_v1_afnor_oauth_token_post) | **POST** /api/v1/afnor/oauth/token | Endpoint OAuth2 pour authentification AFNOR |
 
 
 ## oauth_token_proxy_api_v1_afnor_oauth_token_post
 
 > Object oauth_token_proxy_api_v1_afnor_oauth_token_post
 
-Test PDP OAuth2 credentials
+Endpoint OAuth2 pour authentification AFNOR
 
-OAuth2 proxy to validate PDP credentials. Use this endpoint to verify that OAuth credentials (client_id, client_secret) are valid before saving a PDP configuration. This endpoint is public (no authentication required).
+Endpoint proxy OAuth2 pour obtenir un token d'accès AFNOR. Fait proxy vers le mock AFNOR (sandbox) ou la vraie PDP selon MOCK_AFNOR_BASE_URL. Cet endpoint est public (pas d'auth Django requise) car il est appelé par le SDK AFNOR.
 
 ### Examples
 
@@ -105,7 +24,7 @@ require 'factpulse'
 api_instance = FactPulse::AFNORPDPPAApi.new
 
 begin
-  # Test PDP OAuth2 credentials
+  # Endpoint OAuth2 pour authentification AFNOR
   result = api_instance.oauth_token_proxy_api_v1_afnor_oauth_token_post
   p result
 rescue FactPulse::ApiError => e
@@ -121,7 +40,7 @@ This returns an Array which contains the response data, status code and headers.
 
 ```ruby
 begin
-  # Test PDP OAuth2 credentials
+  # Endpoint OAuth2 pour authentification AFNOR
   data, status_code, headers = api_instance.oauth_token_proxy_api_v1_afnor_oauth_token_post_with_http_info
   p status_code # => 2xx
   p headers # => { ... }