Ruby SDK

Official Ruby SDK for thelawin.dev.

Requires Ruby 3.0+

Installation

Beta-Phase

Während der Beta sind die SDKs über GitHub verfügbar. RubyGems-Veröffentlichung folgt mit dem stabilen Release.

In deinem Gemfile:

gem 'thelawin', git: 'https://github.com/steviee/thelawin-clients.git', glob: 'ruby/*.gemspec'

Dann:

bundle install

Quick Start

require 'thelawin'

client = Thelawin::Client.new(api_key: 'env_sandbox_xxx')

result = client.invoice
  .number('2026-001')
  .date('2026-01-15')
  .seller(name: 'Acme GmbH', vat_id: 'DE123456789', city: 'Berlin', country: 'DE')
  .buyer(name: 'Customer AG', city: 'München', country: 'DE')
  .add_item(description: 'Consulting Services', quantity: 8, unit: 'HUR', unit_price: 150, vat_rate: 19)
  .template('minimal')
  .generate

if result.success?
  result.save_pdf('./invoice.pdf')
  puts "Generated: #{result.filename}"
else
  result.errors.each { |e| puts "#{e.path}: #{e.message}" }
end

Client Options

client = Thelawin::Client.new(
  api_key: 'env_sandbox_xxx',
  base_url: 'https://api.thelawin.dev',  # optional
  timeout: 30                            # optional, seconds
)

Builder API

Invoice Details

client.invoice
  .number('2026-001')           # Required
  .date('2026-01-15')           # Required, String or Date
  .due_date('2026-02-15')       # Optional
  .currency('EUR')              # Default: 'EUR'

Parties

.seller(
  name: 'Acme GmbH',           # Required
  vat_id: 'DE123456789',       # Required
  street: 'Hauptstraße 1',
  city: 'Berlin',              # Required
  postal_code: '10115',
  country: 'DE'                # Required
)
.buyer(
  name: 'Customer AG',         # Required
  vat_id: 'DE987654321',
  city: 'München',             # Required
  country: 'DE'                # Required
)

Line Items

.add_item(
  description: 'Consulting',   # Required
  quantity: 8,                 # Required
  unit: 'HUR',                 # Required
  unit_price: 150.00,          # Required
  vat_rate: 19.0               # Required
)

Customization

.template('minimal')           # 'minimal', 'classic', 'compact'
.locale('de')                  # 'en', 'de', 'fr', 'es', 'it'
.accent_color('#8b5cf6')
.footer_text('Thank you!')

Logo

# From file (auto Base64)
.logo_file('./logo.png')
.logo_file('./logo.png', width_mm: 30)

# From Base64
.logo_base64('iVBORw0KGgo...', width_mm: 30)

Result Handling

result = builder.generate

if result.success?
  puts result.filename        # 'invoice-2026-001.pdf'
  puts result.validation      # { status: 'valid', profile: 'EN16931' }

  # Save to file
  result.save_pdf('./invoice.pdf')

  # Get bytes
  pdf_bytes = result.to_bytes

  # Get data URL
  data_url = result.to_data_url
else
  result.errors.each do |error|
    puts "#{error.path}: #{error.message}"
  end
end

Error Handling

begin
  result = client.invoice.generate
rescue Thelawin::QuotaExceededError
  puts 'Quota exceeded, upgrade your plan'
rescue Thelawin::NetworkError => e
  puts "Network error: #{e.message}"
rescue Thelawin::ApiError => e
  puts "API error #{e.status_code}: #{e.message}"
end

Rails Integration

# config/initializers/thelawin.rb
Thelawin.configure do |config|
  config.api_key = Rails.application.credentials.thelawin_api_key
  config.base_url = Rails.env.production? ? 'https://api.thelawin.dev' : 'http://localhost:8080'
end

# In your controller/service
class InvoiceService
  def generate_invoice(order)
    Thelawin.client.invoice
      .number(order.invoice_number)
      .date(order.created_at.to_date)
      .seller(company_details)
      .buyer(customer: order.customer)
      .items(order.line_items.map { |li| line_item_attrs(li) })
      .generate
  end
end

Source Code

github.com/steviee/thelawin-clients/tree/main/ruby