Voltaria Ruby Library

Quickstart

Install the gem:

gem install voltaria_sdk

Then load it with require "voltaria".

Construct a client with Voltaria.new, passing your API key. The base URL is derived automatically from the key prefix:

require "voltaria"

# Production
client = Voltaria.new("live_...")

# Sandbox
# client = Voltaria.new("sandbox_...")

# List loans
loans = client.loans.list_loans

Key prefix	Environment	Base URL
live_	Production	https://api.voltaria.io
sandbox_	Sandbox	https://api.sandbox.voltaria.io

Passing an explicit base_url: overrides prefix routing.

See reference.md for the full API reference.

---

The Voltaria Ruby library provides convenient access to the Voltaria APIs from Ruby.

Table of Contents

• Reference
• Usage
• Environments
• Errors
• Advanced
  • Retries
  • Timeouts
  • Additional Headers
  • Additional Query Parameters
• Contributing

Reference

A full reference for this library is available here.

Usage

Instantiate and use the client with the following:

require "voltaria"

client = Voltaria::Client.new(token: "<token>")

client.clients.create_client(
  name: "ACME Corp",
  jurisdiction: "eu"
)

Environments

This SDK allows you to configure different environments or custom URLs for API requests. You can either use the predefined environments or specify your own custom URL.

Environments

require "voltaria"

voltaria = Voltaria::Client.new(
    base_url: Voltaria::Environment::SANDBOX
)

Custom URL

require "voltaria"

client = Voltaria::Client.new(
    base_url: "https://example.com"
)

Errors

Failed API calls will raise errors that can be rescued from granularly.

require "voltaria"

client = Voltaria::Client.new(
    base_url: "https://example.com"
)

begin
    result = client.clients.create_client
rescue Voltaria::Errors::TimeoutError
    puts "API didn't respond before our timeout elapsed"
rescue Voltaria::Errors::ServiceUnavailableError
    puts "API returned status 503, is probably overloaded, try again later"
rescue Voltaria::Errors::ServerError
    puts "API returned some other 5xx status, this is probably a bug"
rescue Voltaria::Errors::ResponseError => e
    puts "API returned an unexpected status other than 5xx: #{e.code} #{e.message}"
rescue Voltaria::Errors::ApiError => e
    puts "Some other error occurred when calling the API: #{e.message}"
end

Advanced

Retries

The SDK is instrumented with automatic retries. A request will be retried as long as the request is deemed retryable and the number of retry attempts has not grown larger than the configured retry limit (default: 2).

A request is deemed retryable when any of the following HTTP status codes is returned:

• 408 (Timeout)
• 429 (Too Many Requests)
• 5XX (Internal Server Errors)

Use the max_retries option to configure this behavior.

require "voltaria"

client = Voltaria::Client.new(
    base_url: "https://example.com",
    max_retries: 3  # Configure max retries (default is 2)
)

Timeouts

The SDK defaults to a 60 second timeout. Use the timeout option to configure this behavior.

require "voltaria"

response = client.clients.create_client(
    ...,
    timeout: 30  # 30 second timeout
)

Additional Headers

If you would like to send additional headers as part of the request, use the additional_headers request option.

require "voltaria"

response = client.clients.create_client(
    ...,
    request_options: {
        additional_headers: {
            "X-Custom-Header" => "custom-value"
        }
    }
)

Additional Query Parameters

If you would like to send additional query parameters as part of the request, use the additional_query_parameters request option.

require "voltaria"

response = client.clients.create_client(
    ...,
    request_options: {
        additional_query_parameters: {
            "custom_param" => "custom-value"
        }
    }
)

Contributing

While we value open-source contributions to this SDK, this library is generated programmatically. Additions made directly to this library would have to be moved over to our generation code, otherwise they would be overwritten upon the next generated release. Feel free to open a PR as a proof of concept, but know that we will not be able to merge it as-is. We suggest opening an issue first to discuss with us!

On the other hand, contributions to the README are always very welcome!