Démarrage rapide
Quickstart : créer une facture en Ruby
Pas de SDK officiel — utiliser Faraday (BYO client)
Pas de SDK Ruby officiel pour Scell.io. L'intégration se fait via `Faraday` (HTTP client le plus utilisé en Rails/Ruby) ou la lib `net/http` standard. L'API utilise du JSON snake_case standard, parfaitement aligné avec les conventions Ruby. Pour Rails : utiliser `ActiveJob` pour la création asynchrone et `Sidekiq` pour les retries. Pour Hanami / Roda / Sinatra : intégration directe. Le SDK Ruby n'est pas planifié à court terme.
À retenir
- Prérequis : Ruby 3.2+, `gem install faraday`
- Pas de SDK officiel : BYO client (faraday, httparty, net/http)
- Variable d'env : `ENV['SCELL_API_KEY']`
- HTTP : Faraday recommandé (middlewares retry/json)
- Output attendu : Hash avec `id`, `status`, `pdf_url`
- Codes erreur : `Faraday::ClientError` (4xx), `Faraday::ServerError` (5xx)
Exemple de code
require 'faraday'
require 'json'
require 'securerandom'
client = Faraday.new(url: 'https://api.scell.io/api/v1') do |f|
f.request :json
f.response :json
f.headers['X-API-Key'] = ENV.fetch('SCELL_API_KEY')
end
def call(client, path, body)
r = client.post(path, body) { |req| req.headers['Idempotency-Key'] = SecureRandom.uuid }
raise "#{r.status}: #{r.body}" unless r.success?
r.body
end
seller = {
siret: '12345678901234', name: 'Ma SAS', vat_number: 'FR12345678901',
address: { street: '1 rue Test', city: 'Paris', postal_code: '75001', country: 'FR' }
}
# 1. Facture B2B
b2b = call(client, '/invoices', {
format: 'factur-x', profile: 'EN16931', currency: 'EUR', seller: seller,
buyer: {
siret: '98765432109876', name: 'Client SARL',
address: { street: '2 avenue Demo', city: 'Lyon', postal_code: '69001', country: 'FR' }
},
lines: [{ description: 'Prestation conseil', quantity: 1, unit_price: 1000.0, vat_rate: 20.0 }]
})
puts "B2B: #{b2b['id']} (#{b2b['status']})"
# 2. Facture B2C (particulier)
b2c = call(client, '/invoices', {
format: 'factur-x', profile: 'EN16931', currency: 'EUR', seller: seller,
buyer: {
buyer_is_individual: true, name: 'Jean Dupont', email: 'jean@example.com',
address: { street: '3 bd Client', city: 'Marseille', postal_code: '13001', country: 'FR' }
},
lines: [{ description: 'Abonnement', quantity: 1, unit_price: 49.90, vat_rate: 20.0 }]
})
puts "B2C: #{b2c['id']} (#{b2c['status']})"
# 3. Signature simple eIDAS EU-SES
sig = call(client, '/signatures', {
document_url: 'https://example.com/contrat.pdf',
signers: [{ name: 'Jean Dupont', email: 'jean@example.com', phone: '+33612345678' }],
signature_options: { signature_mode: 'drawn', timezone: 'Europe/Paris' }
})
puts "Signature: #{sig['id']} -> #{sig['signing_url']}"