factpulse 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 555565849759eba51afaa2f06f3e61aee4b41845b4c0199313382a74bc2d3173
+  data.tar.gz: ac9262699e7003ae0766c6270681cffbdd62a690499311f8aab320a75d95d68e
+SHA512:
+  metadata.gz: 4b2ab05ca8d3cb5f4cbe4621dd47f5f28e96af933bacf286d3ee153f52b89c733954c8f132f46061be0cbb0fe6e8de2992cdef602ae8e1c03466082d1225b646
+  data.tar.gz: 49bbc6f27eddfd7e24d798f90b45d48f8a89b6b05328864d341bf47b66a23dfb8df9cc73c9358a88e1b6289d36293ebf8f0f8f1765ce7de5e3aca1a428625a3a

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+Toutes les modifications notables de ce projet seront documentées dans ce fichier.
+
+Le format est basé sur [Keep a Changelog](https://keepachangelog.com/fr/1.0.0/),
+et ce projet adhère au [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-02-02
+
+### Added
+- Ajoute API gestion de clients
+
+
+[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

data/Gemfile

@@ -0,0 +1,9 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :development, :test do
+  gem 'rake', '~> 13.0.1'
+  gem 'pry-byebug'
+  gem 'rubocop', '~> 0.66.0'
+end

data/Gemfile.lock

@@ -0,0 +1,74 @@
+PATH
+  remote: .
+  specs:
+    factpulse (0.1.0)
+      typhoeus (~> 1.0, >= 1.0.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.3)
+    byebug (11.1.3)
+    coderay (1.1.3)
+    date (3.5.1)
+    diff-lcs (1.6.2)
+    ethon (0.15.0)
+      ffi (>= 1.15.0)
+    ffi (1.17.3)
+    jaro_winkler (1.5.6)
+    method_source (1.1.0)
+    parallel (1.27.0)
+    parser (3.3.10.1)
+      ast (~> 2.4.1)
+      racc
+    pry (0.14.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    pry-byebug (3.10.1)
+      byebug (~> 11.0)
+      pry (>= 0.13, < 0.15)
+    psych (5.3.1)
+      date
+      stringio
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.7)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rubocop (0.66.0)
+      jaro_winkler (~> 1.5.1)
+      parallel (~> 1.10)
+      parser (>= 2.5, != 2.5.1.1)
+      psych (>= 3.1.0)
+      rainbow (>= 2.2.2, < 4.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 1.6)
+    ruby-progressbar (1.13.0)
+    stringio (3.2.0)
+    typhoeus (1.5.0)
+      ethon (>= 0.9.0, < 0.16.0)
+    unicode-display_width (1.5.0)
+
+PLATFORMS
+  x86_64-linux
+
+DEPENDENCIES
+  factpulse!
+  pry-byebug
+  rake (~> 13.0.1)
+  rspec (~> 3.6, >= 3.6.0)
+  rubocop (~> 0.66.0)
+
+BUNDLED WITH
+   2.2.33

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 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
+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,220 @@
+# FactPulse SDK Ruby
+
+Official Ruby client for the FactPulse API - French electronic invoicing.
+
+## Features
+
+- **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
+
+## Installation
+
+```bash
+gem install factpulse
+```
+
+Or in your Gemfile:
+
+```ruby
+gem 'factpulse'
+```
+
+## Quick Start
+
+```ruby
+require 'factpulse'
+require 'base64'
+
+# Create the client
+client = FactPulse::Client.new(
+  email: 'your_email@example.com',
+  password: 'your_password',
+  client_uid: 'your-client-uuid'  # From dashboard: Configuration > Clients
+)
+
+# 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
+      }
+    ]
+  },
+  sourcePdf: pdf_b64,
+  profile: 'EN16931',
+  destination: { type: 'afnor' }
+)
+
+# PDF is in result['content'] (auto-polled, auto-decoded)
+File.binwrite('facturx_invoice.pdf', result['content'])
+
+puts "Flow ID: #{result['afnorResult']['flowId']}"
+```
+
+## API Methods
+
+The SDK provides two generic methods that map directly to API endpoints:
+
+```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)
+```
+
+### Common Endpoints
+
+| 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 |
+
+## Webhooks
+
+Instead of polling, you can receive results via webhook by adding `callbackUrl`:
+
+```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'
+)
+
+task_id = result['taskId']
+# Result will be POSTed to your webhook URL
+```
+
+### Webhook Receiver Example (Sinatra)
+
+```ruby
+require 'sinatra'
+require 'json'
+require 'openssl'
+
+WEBHOOK_SECRET = 'your-shared-secret'
+
+def verify_signature(payload, signature)
+  return false unless signature&.start_with?('sha256=')
+
+  expected = OpenSSL::HMAC.hexdigest('SHA256', WEBHOOK_SECRET, payload)
+  Rack::Utils.secure_compare(expected, signature[7..])
+end
+
+post '/webhook/factpulse' do
+  payload = request.body.read
+  signature = request.env['HTTP_X_WEBHOOK_SIGNATURE']
+
+  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
+```
+
+### 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):
+
+```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'
+  }
+)
+```
+
+## Error Handling
+
+```ruby
+require 'factpulse'
+
+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
+```
+
+## Available Helpers
+
+The SDK provides the following helper classes:
+
+- `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
+
+## Resources
+
+- **API Documentation**: https://factpulse.fr/api/facturation/documentation
+- **Support**: contact@factpulse.fr
+
+## License
+
+MIT License - Copyright (c) 2025 FactPulse

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+
+begin
+  require 'rspec/core/rake_task'
+
+  RSpec::Core::RakeTask.new(:spec)
+  task default: :spec
+rescue LoadError
+  # no rspec available
+end

data/docs/AFNORAcknowledgement.md

@@ -0,0 +1,20 @@
+# FactPulse::AFNORAcknowledgement
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **status** | [**AFNORFlowAckStatus**](AFNORFlowAckStatus.md) |  |  |
+| **details** | [**Array<AFNORAcknowledgementDetail>**](AFNORAcknowledgementDetail.md) |  | [optional] |
+
+## Example
+
+```ruby
+require 'factpulse'
+
+instance = FactPulse::AFNORAcknowledgement.new(
+  status: null,
+  details: null
+)
+```
+

data/docs/AFNORAcknowledgementDetail.md

@@ -0,0 +1,24 @@
+# FactPulse::AFNORAcknowledgementDetail
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **level** | **String** |  |  |
+| **item** | **String** | Item on which the error refers |  |
+| **reason_code** | [**AFNORReasonCode**](AFNORReasonCode.md) |  |  |
+| **reason_message** | **String** |  |  |
+
+## Example
+
+```ruby
+require 'factpulse'
+
+instance = FactPulse::AFNORAcknowledgementDetail.new(
+  level: null,
+  item: null,
+  reason_code: null,
+  reason_message: null
+)
+```
+

data/docs/AFNORAddressEdit.md

@@ -0,0 +1,30 @@
+# FactPulse::AFNORAddressEdit
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **ligne_adresse1** | **String** | Corresponds to the address of the recipient structure having defined the directory line(s). | [optional] |
+| **ligne_adresse2** | **String** | Corresponds to the address of the recipient structure having defined the directory line(s). | [optional] |
+| **ligne_adresse3** | **String** | Corresponds to the address of the recipient structure having defined the directory line(s). | [optional] |
+| **postal_code** | **String** | Service postal code | [optional] |
+| **country_subdivision** | **String** | Subdivision of the country | [optional] |
+| **locality** | **String** | Municipality of the recipient structure having defined the directory line(s). | [optional] |
+| **code_pays** | **String** | Corresponds to the country of the recipient structure. | [optional] |
+
+## Example
+
+```ruby
+require 'factpulse'
+
+instance = FactPulse::AFNORAddressEdit.new(
+  ligne_adresse1: 16 BIS RUE HENRI BARBUSSE,
+  ligne_adresse2: CEDEX 1,
+  ligne_adresse3: Bâtiment le Callipso,
+  postal_code: 38100,
+  country_subdivision: Bretagne,
+  locality: Grenoble,
+  code_pays: FR
+)
+```
+

data/docs/AFNORAddressPatch.md

@@ -0,0 +1,30 @@
+# FactPulse::AFNORAddressPatch
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **ligne_adresse1** | **String** | Corresponds to the address of the recipient structure having defined the directory line(s). | [optional] |
+| **ligne_adresse2** | **String** | Corresponds to the address of the recipient structure having defined the directory line(s). | [optional] |
+| **ligne_adresse3** | **String** | Corresponds to the address of the recipient structure having defined the directory line(s). | [optional] |
+| **postal_code** | **String** | Service postal code | [optional] |
+| **country_subdivision** | **String** | Subdivision of the country | [optional] |
+| **locality** | **String** | Corresponds to the municipality of the recipient structure having defined the directory line(s). | [optional] |
+| **code_pays** | **String** | Corresponds to the country code of the recipient structure | [optional] |
+
+## Example
+
+```ruby
+require 'factpulse'
+
+instance = FactPulse::AFNORAddressPatch.new(
+  ligne_adresse1: 16 BIS RUE HENRI BARBUSSE,
+  ligne_adresse2: CEDEX 1,
+  ligne_adresse3: Bâtiment le Callipso,
+  postal_code: 38100,
+  country_subdivision: Bretagne,
+  locality: Grenoble,
+  code_pays: FR
+)
+```
+

data/docs/AFNORAddressPut.md

@@ -0,0 +1,30 @@
+# FactPulse::AFNORAddressPut
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **ligne_adresse1** | **String** | Corresponds to the address of the recipient structure having defined the directory line(s). |  |
+| **ligne_adresse2** | **String** | Corresponds to the address of the recipient structure having defined the directory line(s). |  |
+| **ligne_adresse3** | **String** | Corresponds to the address of the recipient structure having defined the directory line(s). |  |
+| **postal_code** | **String** | Service postal code |  |
+| **country_subdivision** | **String** | Subdivision of the country |  |
+| **locality** | **String** | Corresponds to the municipality of the recipient structure having defined the directory line(s). |  |
+| **code_pays** | **String** | Corresponds to the country code of the recipient structure |  |
+
+## Example
+
+```ruby
+require 'factpulse'
+
+instance = FactPulse::AFNORAddressPut.new(
+  ligne_adresse1: 16 BIS RUE HENRI BARBUSSE,
+  ligne_adresse2: CEDEX 1,
+  ligne_adresse3: Bâtiment le Callipso,
+  postal_code: 38100,
+  country_subdivision: Bretagne,
+  locality: Grenoble,
+  code_pays: FR
+)
+```
+

data/docs/AFNORAddressRead.md

@@ -0,0 +1,32 @@
+# FactPulse::AFNORAddressRead
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **address_line1** | **String** | Corresponds to the address of the recipient structure having defined the directory line(s). | [optional] |
+| **address_line2** | **String** | Corresponds to the address of the recipient structure having defined the directory line(s). | [optional] |
+| **address_line3** | **String** | Corresponds to the address of the recipient structure having defined the directory line(s). | [optional] |
+| **postal_code** | **String** | Service postal code | [optional] |
+| **country_subdivision** | **String** | Subdivision of the country | [optional] |
+| **locality** | **String** | Municipality of the recipient structure having defined the directory line(s). | [optional] |
+| **country_code** | **String** | Corresponds to the country of the recipient structure. | [optional] |
+| **country_name** | **String** | Corresponds to the country of the recipient structure having defined the directory line(s). | [optional] |
+
+## Example
+
+```ruby
+require 'factpulse'
+
+instance = FactPulse::AFNORAddressRead.new(
+  address_line1: 16 BIS RUE HENRI BARBUSSE,
+  address_line2: CEDEX 1,
+  address_line3: Bâtiment le Callipso,
+  postal_code: 38100,
+  country_subdivision: Bretagne,
+  locality: Grenoble,
+  country_code: FR,
+  country_name: France
+)
+```
+

data/docs/AFNORAlgorithm.md

@@ -0,0 +1,15 @@
+# FactPulse::AFNORAlgorithm
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+
+## Example
+
+```ruby
+require 'factpulse'
+
+instance = FactPulse::AFNORAlgorithm.new()
+```
+

data/docs/AFNORContainsOperator.md

@@ -0,0 +1,15 @@
+# FactPulse::AFNORContainsOperator
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+
+## Example
+
+```ruby
+require 'factpulse'
+
+instance = FactPulse::AFNORContainsOperator.new()
+```
+

data/docs/AFNORCreateDirectoryLineBody.md

@@ -0,0 +1,20 @@
+# FactPulse::AFNORCreateDirectoryLineBody
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **period** | [**AFNORCreateDirectoryLineBodyPeriod**](AFNORCreateDirectoryLineBodyPeriod.md) |  | [optional] |
+| **addressing_information** | [**AFNORCreateDirectoryLineBodyAddressingInformation**](AFNORCreateDirectoryLineBodyAddressingInformation.md) |  | [optional] |
+
+## Example
+
+```ruby
+require 'factpulse'
+
+instance = FactPulse::AFNORCreateDirectoryLineBody.new(
+  period: null,
+  addressing_information: null
+)
+```
+

data/docs/AFNORCreateDirectoryLineBodyAddressingInformation.md

@@ -0,0 +1,24 @@
+# FactPulse::AFNORCreateDirectoryLineBodyAddressingInformation
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **siren** | **String** | SIREN number |  |
+| **siret** | **String** | SIRET Number | [optional] |
+| **routing_identifier** | **String** | Routing identifier od a routing code. | [optional] |
+| **addressing_suffix** | **String** | suffix of the directory line which defines an address mesh not attached to a facility | [optional] |
+
+## Example
+
+```ruby
+require 'factpulse'
+
+instance = FactPulse::AFNORCreateDirectoryLineBodyAddressingInformation.new(
+  siren: 702042755,
+  siret: 70204275500240,
+  routing_identifier: dcsc456sdcsdcs556,
+  addressing_suffix: dcsc456sdcsdcs556
+)
+```
+

data/docs/AFNORCreateDirectoryLineBodyPeriod.md

@@ -0,0 +1,20 @@
+# FactPulse::AFNORCreateDirectoryLineBodyPeriod
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **date_from** | **Date** | Effective start date of the directory line.. |  |
+| **date_to** | **Date** | Effective end date of the directory line. | [optional] |
+
+## Example
+
+```ruby
+require 'factpulse'
+
+instance = FactPulse::AFNORCreateDirectoryLineBodyPeriod.new(
+  date_from: 2023-01-01,
+  date_to: 2023-01-31
+)
+```
+

data/docs/AFNORCreateRoutingCodeBody.md

@@ -0,0 +1,32 @@
+# FactPulse::AFNORCreateRoutingCodeBody
+
+## Properties
+
+| Name | Type | Description | Notes |
+| ---- | ---- | ----------- | ----- |
+| **facility_nature** | [**AFNORFacilityNature**](AFNORFacilityNature.md) |  |  |
+| **routing_identifier** | **String** | Routing identifier od a routing code. |  |
+| **siret** | **String** | SIRET Number |  |
+| **routing_identifier_type** | **String** | Routing Identifier type. | [optional] |
+| **routing_code_name** | **String** | Name of the directory line routing code. This attribute is only returned if the directory line is defined at the SIREN / SIRET / Routing code mesh. |  |
+| **manages_legal_commitment_code** | **Boolean** | Indicates whether the public structure requires a legal commitment number. This attribute is only returned if the directory line is defined for a public structure at the SIREN / SIRET or SIREN / SIRET / Routing code level. | [optional] |
+| **administrative_status** | [**AFNORRoutingCodeAdministrativeStatus**](AFNORRoutingCodeAdministrativeStatus.md) |  |  |
+| **address** | [**AFNORAddressEdit**](AFNORAddressEdit.md) |  | [optional] |
+
+## Example
+
+```ruby
+require 'factpulse'
+
+instance = FactPulse::AFNORCreateRoutingCodeBody.new(
+  facility_nature: null,
+  routing_identifier: dcsc456sdcsdcs556,
+  siret: 70204275500240,
+  routing_identifier_type: 0224,
+  routing_code_name: Libellé Code routage,
+  manages_legal_commitment_code: true,
+  administrative_status: null,
+  address: null
+)
+```
+