myfinance-client-ruby

A Ruby client for the Myfinance REST API

Myfinance API docs: https://app.myfinance.com.br/docs/api

Installation

Add this line to your application's Gemfile:

gem 'myfinance'

And then execute:

$ bundle

Or install it yourself as:

$ gem install myfinance

Configuration

Use Myfinance.configure to setup your environment:

require 'myfinance'

Myfinance.configure do |config|
  config.url = 'https://sandbox.myfinance.com.br' # defaults to 'https://app.myfinance.com.br'
  config.user_agent = 'My App v1.0' # optional, but you should pass a custom user-agent identifying your app
end

Usage

Given your token, create an instance of Myfinance::Client, as below:

client = Myfinance.client("YOUR_TOKEN_HERE")

Now you have access to these API endpoints:

• Entities API as client.entities
• FinancialTransactions API as client.financial_transactions
• PayableAccounts API as client.payable_accounts
• ReceivableAccounts API as client.receivable_accounts
• Attachments API as client.attachments
• Accounts API as client.accounts
• DepositAccounts API as client.deposit_accounts
• Categories API as client.categories
• ClassificationCenters API as client.classification_centers
• People API as client.people
• Webhooks API as client.webhooks
• Taxes API as client.taxes
• CreditCards API as client.credit_cards
• CreditCardsTransactions API as client.credit_cards_transactions
• Reconciles API as client.reconciles
• BankStatements API as client.bank_statements
• Sales API as client.sales
• SaleAccounts API as client.sale_accounts
• SaleRules API as client.sale_rules
• CustomClassifiers API as client.custom_classifiers
• CustomClassifierValues API as client.custom_classifier_values

Endpoints

Entities

HTTP method	Endpoint	Client method
GET	/entities	client.entities.find_all
GET	/entities/:id	client.entities.find

FinancialTransactions

HTTP method	Endpoint	Client method
GET	/entities/:entity_id/deposit_accounts/:deposit_account_id/financial_transactions	client.financial_transactions.find_all
GET	/entities/:entity_id/deposit_accounts/:deposit_account_id/financial_transactions/:id	client.financial_transactions.find
POST	/entities/:entity_id/deposit_accounts/:deposit_account_id/financial_transactions	client.financial_transactions.create
PUT	/entities/:entity_id/deposit_accounts/:deposit_account_id/financial_transactions/:id	client.financial_transactions.update
DELETE	/entities/:entity_id/deposit_accounts/:deposit_account_id/financial_transactions/:id	client.financial_transactions.destroy
DELETE	/entities/:entity_id/deposit_accounts/:deposit_account_id/financial_transactions/destroy_many?selected_ids=:id1,id2,id3	client.financial_transactions.destroy_many

PayableAccounts

HTTP method	Endpoint	Client method
GET	/entities/:entity_id/payable_accounts	client.payable_accounts.find_all
GET	/entities/:entity_id/payable_accounts/:id	client.payable_accounts.find
POST	/entities/:entity_id/payable_accounts	client.payable_accounts.create
PUT	/entities/:entity_id/payable_accounts/:id	client.payable_accounts.update
PUT	/entities/:entity_id/payable_accounts/:id/pay	client.payable_accounts.pay
PUT	/entities/:entity_id/payable_accounts/:id/undo_payment	client.payable_accounts.undo_payment
DELETE	/entities/:entity_id/payable_accounts/:id	client.payable_accounts.destroy
DELETE	/entities/:entity_id/payable_accounts/:id/recurrence	client.payable_accounts.destroy_recurrence
DELETE	/entities/:entity_id/payable_accounts?selected_ids=:id1,id2,id3	client.payable_accounts.destroy_many

ReceivableAccounts

HTTP method	Endpoint	Client method
GET	/entities/:entity_id/receivable_accounts	client.receivable_accounts.find_all
GET	/entities/:entity_id/receivable_accounts/:id	client.receivable_accounts.find
POST	/entities/:entity_id/receivable_accounts	client.receivable_accounts.create
PUT	/entities/:entity_id/receivable_accounts/:id	client.receivable_accounts.update
PUT	/entities/:entity_id/receivable_accounts/:id/receive	client.receivable_accounts.receive
PUT	/entities/:entity_id/receivable_accounts/:id/undo_receivement	client.receivable_accounts.undo_receivement
DELETE	/entities/:entity_id/receivable_accounts/:id	client.receivable_accounts.destroy
DELETE	/entities/:entity_id/receivable_accounts/:id/recurrence	client.receivable_accounts.destroy_recurrence
DELETE	/entities/:entity_id/receivable_accounts?selected_ids=:id1,id2,id3	client.receivable_accounts.destroy_many

Attachments

HTTP method	Endpoint	Client method
GET	/entities/:entity_id/attachments	client.attachments.find_all
GET	/entities/:entity_id/attachments/:id	client.attachments.find
POST	/entities/:entity_id/attachments	client.attachments.create
DELETE	/entities/:entity_id/attachments/:id	client.attachments.destroy

Accounts

HTTP method	Endpoint	Client method
GET	/accounts	client.accounts.find_all

DepositAccounts

HTTP method	Endpoint	Client method
GET	/entities/:entity_id/deposit_accounts	client.deposit_accounts.find_all
GET	/entities/:entity_id/deposit_accounts/:id	client.deposit_accounts.find
POST	/entities/:entity_id/deposit_accounts	client.deposit_accounts.create
PUT	/entities/:entity_id/deposit_accounts/:id	client.deposit_accounts.update
DELETE	/entities/:entity_id/deposit_accounts/:id	client.deposit_accounts.destroy

Categories

HTTP method	Endpoint	Client method
GET	/categories	client.categories.find_all
GET	/categories/:id	client.categories.find
POST	/categories	client.categories.create
PUT	/categories/:id	client.categories.update
DELETE	/categories/:id	client.categories.destroy

ClassificationCenters

HTTP method	Endpoint	Client method
GET	/classification_centers	client.classification_centers.find_all
GET	/classification_centers/:id	client.classification_centers.find
POST	/classification_centers	client.classification_centers.create
PUT	/classification_centers/:id	client.classification_centers.update
DELETE	/classification_centers/:id	client.classification_centers.destroy

People

HTTP method	Endpoint	Client method
GET	/people	client.people.find_all
GET	/people/:id	client.people.find
POST	/people	client.people.create
PUT	/people/:id	client.people.update
DELETE	/people/:id	client.people.destroy

Webhooks

HTTP method	Endpoint	Client method
GET	/integrations/webhooks	client.webhooks.find_all
GET	/integrations/webhooks/:id	client.webhooks.find
POST	/integrations/webhooks	client.webhooks.create
PUT	/integrations/webhooks/:id	client.webhooks.update
DELETE	/integrations/webhooks/:id	client.webhooks.destroy

Taxes

HTTP method	Endpoint	Client method
GET	/taxes	client.taxes.find_all
GET	/taxes/:id	client.taxes.find

CreditCards

HTTP method	Endpoint	Client method
GET	/entities/:entity_id/credit_cards	client.credit_cards.find_all
GET	/entities/:entity_id/credit_cards/:id	client.credit_cards.find
POST	/entities/:entity_id/credit_cards	client.credit_cards.create
PUT	/entities/:entity_id/credit_cards/:id	client.credit_cards.update
DELETE	/entities/:entity_id/credit_cards/:id	client.credit_cards.destroy

CreditCardTransactions

HTTP method	Endpoint	Client method
GET	/entities/:entity_id/credit_cards/:credit_card_id/transactions	client.credit_card_transactions.find_all
GET	/entities/:entity_id/credit_cards/:credit_card_id/transactions/:id	client.credit_card_transactions.find
POST	/entities/:entity_id/credit_cards/:credit_card_id/transactions	client.credit_card_transactions.create
PUT	/entities/:entity_id/credit_cards/:credit_card_id/transactions/:id	client.credit_card_transactions.update
DELETE	/entities/:entity_id/credit_cards/:credit_card_id/transactions/:id	client.credit_card_transactions.destroy
DELETE	/entities/:entity_id/credit_cards/:credit_card_id/transactions/:id/recurrence	client.credit_card_transactions.destroy_parcelled

Reconciles

HTTP method	Endpoint	Client method
POST	/entities/:entity_id/reconciles	client.reconciles.reconcile

BankStatements

HTTP method	Endpoint	Client method
POST	/entities/:entity_id/deposit_accounts/:deposit_account_id/bank_statements	client.bank_statements.import
GET	/entities/:entity_id/deposit_accounts/:deposit_account_id/bank_statements/:id	client.bank_statements.status

Sales

HTTP method	Endpoint	Client method
GET	/entities/:entity_id/sales	client.sales.find_all
GET	/entities/:entity_id/sales/:id	client.sales.find
POST	/entities/:entity_id/sales	client.sales.create
PUT	/entities/:entity_id/sales/:id	client.sales.update
DELETE	/entities/:entity_id/sales/:id	client.sales.destroy

SaleAccounts

HTTP method	Endpoint	Client method
GET	/entities/:entity_id/sale_accounts	client.sale_accounts.find_all
GET	/entities/:entity_id/sale_accounts/:id	client.sale_accounts.find
POST	/entities/:entity_id/sale_accounts	client.sale_accounts.create
PUT	/entities/:entity_id/sale_accounts/:id	client.sale_accounts.update
DELETE	/entities/:entity_id/sale_accounts/:id	client.sale_accounts.destroy

SaleRules

HTTP method	Endpoint	Client method
GET	/entities/:entity_id/sale_rules	client.sale_rules.find_all
GET	/entities/:entity_id/sale_rules/:id	client.sale_rules.find
POST	/entities/:entity_id/sale_rules	client.sale_rules.create
PUT	/entities/:entity_id/sale_rules/:id	client.sale_rules.update
DELETE	/entities/:entity_id/sale_rules/:id	client.sale_rules.destroy

CustomClassifiers

HTTP method	Endpoint	Client method
GET	/custom_classifiers	client.custom_classifiers.find_all
GET	/custom_classifiers/:id	client.custom_classifiers.find
POST	/custom_classifiers	client.custom_classifiers.create
PUT	/custom_classifiers/:id	client.custom_classifiers.update
DELETE	/custom_classifiers/:id	client.custom_classifiers.destroy

CustomClassifierValues

HTTP method	Endpoint	Client method
GET	/custom_classifiers/:custom_classifier_value_id/values	client.custom_classifier_values.find_all
GET	/custom_classifiers/:custom_classifier_value_id/values/:id	client.custom_classifier_values.find
POST	/custom_classifiers/:custom_classifier_value_id/values	client.custom_classifier_values.create
PUT	/custom_classifiers/:custom_classifier_value_id/values/:id	client.custom_classifier_values.update
DELETE	/custom_classifiers/:custom_classifier_value_id/values/:id	client.custom_classifier_values.destroy

Configuration

require 'myfinance'

Myfinance.configure do |m|
  m.url = 'https://sandbox.myfinance.com.br' # defaults to 'https://app.myfinance.com.br' if omitted
  m.user_agent = 'My App v1.0' # optional, but you should pass a custom user-agent identifying your app
end

Multiple accounts

When an account has multiple accounts, an ACCOUNT_ID header is required for the requests. To instantiate a new client with an ACCOUNT_ID header:

client = Myfinance.client("YOUR_TOKEN_HERE", ACCOUNT_ID) # where ACCOUNT_ID is the ID of the account

If you instantiate a new client without an account_id and the user has more than one account, the lib will raise a Myfinance::RequestError error. The list of available accounts will be in the body of the object.

begin
  client.entities.find_all
rescue Myfinance::RequestError => e
  e.body # { "error" => "O cabeçalho da requisição não possui o atributo ACCOUNT_ID.", "accounts" => [{"account" => { "id" => 3, .. } }, { ... }] }
  e.message # O cabeçalho da requisição não possui o atributo ACCOUNT_ID.
  e.code # 422
end

Development

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.

Release

To release a new version, update the version number in lib/myfinance/version.rb, run bundle install and commit & push the changes to the repository.

Before releasing the gem, remember to update de CHANGELOG.md, describing the changes made in this version.

If this is your first time publishing a RubyGem in your local device, you will have to download your credentials. To do this, follow the instructions in your profile page in RubyGems or just type the following in your command line, replacing $username with your RubyGems username.

$ curl -u $username https://rubygems.org/api/v1/api_key.yaml > ~/.gem/credentials; chmod 0600 ~/.gem/credentials

Then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org. Make sure you have publishing rights for the gem on RubyGems beforehand, though.

After publishing the new version, add a released label to each pull request included in the release and write a comment like this:

:shipit: released on [version x.y.z](https://rubygems.org/gems/myfinance/versions/x.y.z)

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/myfreecomm/myfinance-client-ruby. This project is intended to be a safe and welcoming space for collaboration.

License

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