Tapsilat Ruby Client

A Ruby client for the Tapsilat API.

Installation

Add this line to your application's Gemfile:

gem 'tapsilat'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install tapsilat

Usage

Configure the client with your API credentials:

Tapsilat.configure do |config|
  config.base_url = ENV['TAPSILAT_BASE_URL']
  config.api_token = ENV['TAPSILAT_API_TOKEN']
end

Create a client instance and start using the API:

client = Tapsilat::Client.new

# Create an order
order_data = client.orders.build_order(
  locale: "tr",
  amount: 100.0,
  currency: "TRY",
  buyer: {
    name: "John",
    surname: "Doe",
    email: "john@doe.com"
  },
  billing_address: {
    billing_type: "PERSONAL",
    city: "Istanbul",
    country: "TR"
  },
  basket_items: [
    {
      id: "BI101",
      price: 100.0,
      quantity: 1,
      name: "Test Product"
    }
  ]
)

response = client.orders.create(order_data)

# Get an order
order = client.orders.get(order_id)
puts order.status_text

# List orders
orders = client.orders.list
orders.rows.each do |order|
  puts "#{order.reference_id}: #{order.status_text}"
end

Error Handling

The client provides comprehensive error handling with specific exception types:

begin
  # Create an order
  order = client.orders.create(order_data)
  puts "Order created successfully: #{order.reference_id}"
rescue Tapsilat::OrderValidationError => e
  puts "Validation error: #{e.message}"
  # Handle validation errors (missing fields, invalid data, etc.)
rescue Tapsilat::OrderCreationError => e
  puts "Order creation failed: #{e.message}"
  # Handle order creation failures
rescue Tapsilat::OrderAPIError => e
  puts "API error: #{e.message}"
  # Handle API-related errors (auth, server errors, etc.)
rescue Tapsilat::OrderError => e
  puts "General order error: #{e.message}"
  # Handle any other order-related errors
end

# Specific error handling for different operations
begin
  order = client.orders.get(order_id)
rescue Tapsilat::OrderNotFoundError => e
  puts "Order not found: #{e.message}"
rescue Tapsilat::OrderAPIError => e
  puts "API error while fetching order: #{e.message}"
end

Error Types

Tapsilat::OrderError - Base class for all order-related errors
Tapsilat::OrderValidationError - Validation errors (missing/invalid data)
Tapsilat::OrderCreationError - Order creation failures
Tapsilat::OrderNotFoundError - Order not found errors
Tapsilat::OrderAPIError - API-related errors (auth, server, etc.)

Retry Mechanism

The client automatically retries transient network errors (timeouts, connection issues) up to 3 times with exponential backoff. This helps handle temporary network issues gracefully.

Features

Order creation and management
Built-in validation and error handling
Automatic retry mechanism for network errors
Comprehensive error types for different failure scenarios
Pagination support for order listings
Response objects with convenient helper methods
Full order status tracking

Requirements

Ruby >= 2.6.0

License

The gem is available as open source under the terms of the MIT License.

tapsilat

Development

Runtime