Complyance Ruby SDK

Production ready Ruby SDK with comprehensive e-invoicing support for multiple countries including UAE, Germany, Saudi Arabia, Malaysia, and Belgium. Built for real-world e-invoice applications with Ruby best practices.

Feature Summary

Multi-Country Support - UAE, Germany, KSA, Malaysia, Belgium
Rails Compatible - Seamless Rails integration
Ruby 3.0+ - Modern Ruby features
Gem - Easy installation and updates

Installation

Gemfile

gem 'complyance-sdk'

Then run:

bundle install

Manual Installation

gem install complyance-sdk

Quick Start

Initialize the SDK

require 'complyance'

client = Complyance::Client.new(
  api_key: 'your-api-key',
  base_url: 'https://api.complyance.io'
)

Submit an Invoice

invoice = Complyance::Invoice.new(
  document_type: 'Invoice',
  document_number: 'INV-001',
  issue_date: '2024-01-01',
  currency: 'SAR',
  seller: Complyance::Party.new(
    name: 'Example Company',
    tax_ids: [
      Complyance::TaxId.new(
        type: 'VAT',
        value: '300000000000003'
      )
    ]
  ),
  buyer: Complyance::Party.new(
    name: 'Customer Company'
  ),
  line_items: [
    Complyance::LineItem.new(
      description: 'Product',
      quantity: 1,
      unit_price: 100.00,
      tax_rate: 15
    )
  ]
)

begin
  result = client.submit_invoice(invoice, 'SA')
  puts "Invoice submitted: #{result.invoice_id}"
rescue => e
  puts "Error: #{e.message}"
end

Configuration

Environment Variables

export COMPLYANCE_API_KEY="your-api-key"
export COMPLYANCE_BASE_URL="https://api.complyance.io"

Configuration Block

Complyance.configure do |config|
  config.api_key = ENV['COMPLYANCE_API_KEY']
  config.base_url = ENV['COMPLYANCE_BASE_URL']
  config.timeout = 30
  config.retries = 3
end

client = Complyance::Client.new

Features

KSA (Saudi Arabia) - ZATCA Compliance

ksa_invoice = Complyance::KSA::Invoice.new(
  document_type: 'Standard',
  document_number: 'INV-001',
  # ... standard fields
  extensions: Complyance::KSA::Extensions.new(
    sa_digital: Complyance::KSA::SADigital.new(
      icv: '1',
      pih: 'NWZlY2ViNjZmZmM4NmYzOGQ5NTI3ODZjNmQ2OTZjNzljMmRiYzIzOWRkNGU5MWI0NjcyOWQ3M2EyN2ZiNTdlOQ==',
      qr_code: true
    )
  )
)

result = client.submit_invoice(ksa_invoice, 'SA')

UAE - FTA PINT Compliance

uae_invoice = Complyance::UAE::Invoice.new(
  document_type: 'Tax Invoice',
  # ... standard fields
  extensions: Complyance::UAE::Extensions.new(
    ae_identification: Complyance::UAE::AEIdentification.new(
      trn: '100000000000003',
      uuid: SecureRandom.uuid
    )
  )
)

result = client.submit_invoice(uae_invoice, 'AE')

Malaysia - MyInvois Integration

malaysia_invoice = Complyance::Malaysia::Invoice.new(
  document_type: 'Invoice',
  # ... standard fields
  extensions: Complyance::Malaysia::Extensions.new(
    my_identification: Complyance::Malaysia::MYIdentification.new(
      software_provider_id: 'SP-12345',
      document_id: 'DOC-001'
    ),
    my_classification: Complyance::Malaysia::MYClassification.new(
      category: '001',
      product_service_code: '12345'
    )
  )
)

result = client.submit_invoice(malaysia_invoice, 'MY')

Error Handling

begin
  result = client.submit_invoice(invoice, 'SA')
  puts "Success: #{result.invoice_id}"
rescue Complyance::ValidationError => e
  puts "Validation Error: #{e.message}"
  e.validation_errors.each do |error|
    puts "- #{error[:field]}: #{error[:message]}"
  end
rescue Complyance::ApiError => e
  puts "API Error: #{e.status_code} - #{e.message}"
rescue StandardError => e
  puts "Unexpected error: #{e.message}"
end

Rails Integration

Initializer

# config/initializers/complyance.rb
Complyance.configure do |config|
  config.api_key = Rails.application.credentials.complyance[:api_key]
  config.base_url = ENV.fetch('COMPLYANCE_BASE_URL', 'https://api.complyance.io')
  config.timeout = 30
  config.logger = Rails.logger
end

Controller Usage

# app/controllers/invoices_controller.rb
class InvoicesController < ApplicationController
  def create
    client = Complyance::Client.new
    
    invoice = build_invoice(params[:invoice])
    result = client.submit_invoice(invoice, params[:country])
    
    render json: { invoice_id: result.invoice_id }
  rescue Complyance::ValidationError => e
    render json: { errors: e.validation_errors }, status: :unprocessable_entity
  rescue Complyance::ApiError => e
    render json: { error: e.message }, status: :bad_gateway
  end
  
  private
  
  def build_invoice(invoice_params)
    Complyance::Invoice.new(
      document_type: invoice_params[:document_type],
      document_number: invoice_params[:document_number],
      # ... other fields
    )
  end
end

Background Job

# app/jobs/submit_invoice_job.rb
class SubmitInvoiceJob < ApplicationJob
  queue_as :default
  
  retry_on Complyance::ApiError, wait: :exponentially_longer
  
  def perform(invoice_id, country)
    invoice = Invoice.find(invoice_id)
    client = Complyance::Client.new
    
    complyance_invoice = convert_to_complyance_invoice(invoice)
    result = client.submit_invoice(complyance_invoice, country)
    
    invoice.update!(
      complyance_id: result.invoice_id,
      status: 'submitted'
    )
  end
  
  private
  
  def convert_to_complyance_invoice(invoice)
    Complyance::Invoice.new(
      document_type: invoice.document_type,
      document_number: invoice.document_number,
      # ... other fields
    )
  end
end

Sidekiq Integration

# app/workers/invoice_submission_worker.rb
class InvoiceSubmissionWorker
  include Sidekiq::Worker
  
  sidekiq_options retry: 3, queue: 'invoices'
  
  def perform(invoice_data, country)
    client = Complyance::Client.new
    invoice = Complyance::Invoice.new(invoice_data)
    
    result = client.submit_invoice(invoice, country)
    Rails.logger.info "Invoice submitted: #{result.invoice_id}"
  end
end

API Reference

For detailed API documentation, visit API Documentation.

Support

Contact: Contact Complyance for E-Invoicing - Complyance has helped over 1000+ organizations simplify global e-invoicing. Let us help you understand how Complyance can work for you.