PrivatBankBusinessApi

This gem is an API wrapper for the PrivatBank Business API. It is currently a work in progress. For more details, see the changelog.

API documentation can be found here.

This project uses dry-transformers and dry-schema to provide proper names for API fields. See the model files in the /models directory and the mapping from the original fields in the /transformers directory. For example, see the balance transformer and balance model.

Certain fields in the API responses can be handled as Money using the Money gem. These fields are available in various formats depending on the context. Below are some examples:

• Standard Fields:
  • balance_in and balance_in_uah
  • balance_out and balance_out_uah
  • turnover_debt and turnover_debt_uah
  • turnover_cred and turnover_cred_uah
• Money Gem Fields:
  The same fields may also appear with an additional _money suffix (e.g., balance_in_money), providing a Money-formatted version.

• Standard Amount Fields:
  • money_amount_uah
  • money_amount
• Money Gem Fields:
  • amount_uah_money
  • amount_money

Follow the installation instructions provided in the main guide to add and use the gem in your application.

Install the gem and add to the application's Gemfile by executing:

bundle add privat_bank_business_api

If bundler is not being used to manage dependencies, install the gem by executing:

gem install privat_bank_business_api

To use the API, you need to initialize the client with your API token. Here is a basic example of how to list balances:

require "pb_api"
require "date"

# Initialize the client with your API token
client = PbAPI::Client.new(api_token: "your_api_token_here")

# Define the date range for the balance query
today = Date.today
last_month = today.prev_month

# Fetch the list of balances
balances = client.balance.list(start_date: last_month)

# Print the account and balance information
balances.each do |balance|
  puts "Account: #{balance.account}"
  puts "Balance: #{balance.balance_in_money.format}"
end

All API methods internally use lazy loading to handle paginated results. By leveraging Ruby's Enumerator, the gem fetches data on-demand

PbAPI's has configurable logging logging is configured in pb_api.rb. The logger uses Rails.logger if available, otherwise defaults to a standard Ruby Logger writing to STDOUT with a custom formatter that includes abbreviated severity, a timestamp with microseconds, and process details.

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

This project includes a development container configuration. To use it, you need to have Visual Studio Code and the Remote - Containers extension installed. You can open the project in a dev container by clicking the badge below:

To use the API from the interactive console (bin/console), you need to add your own API key. Create a file named environment.rb in the root directory and add your API key there. You can use the provided environment.sample.rb as a template by renaming it to environment.rb and replacing the placeholder with your actual API key.

# environment.rb
ENV['API_TOKEN'] = 'your_api_key_here'

Once inside the console, you can use the @client object to interact with the API. For example, to list balances:

balances = @client.balance.list(@today)
balances.each do |balance|
  puts balance.account
  puts balance.balance_in_money.format
end

Bug reports and pull requests are welcome on GitHub at https://github.com/merof-code/privat_bank_business_api. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

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

Everyone interacting in the PrivatBankBusinessApi project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.