Quickstart: create an invoice in Ruby

Key facts

• •Requirements: Ruby 3.2+, `gem install faraday`
• •No official SDK: bring your own (faraday, httparty, net/http)
• •Env var: `ENV['SCELL_API_KEY']`
• •HTTP: Faraday recommended (retry/json middlewares)
• •Expected output: Hash with `id`, `status`, `pdf_url`
• •Error codes: `Faraday::ClientError` (4xx), `Faraday::ServerError` (5xx)

Code example

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']}"

See also