# myfinance-client-ruby A Ruby client for the [Myfinance](http://www.myfinance.com.br) REST API [![Gem version](https://badge.fury.io/rb/myfinance.png)](https://rubygems.org/gems/myfinance) [![Build status](https://travis-ci.org/myfreecomm/myfinance-client-ruby.png?branch=master)](https://travis-ci.org/myfreecomm/myfinance-client-ruby) [![Test coverage](https://codeclimate.com/github/myfreecomm/myfinance-client-ruby/badges/coverage.svg)](https://codeclimate.com/github/myfreecomm/myfinance-client-ruby) [![Code Climate grade](https://codeclimate.com/github/myfreecomm/myfinance-client-ruby.png)](https://codeclimate.com/github/myfreecomm/myfinance-client-ruby) Myfinance API docs: https://app.myfinance.com.br/docs/api ## Installation Add this line to your application's Gemfile: ```ruby gem 'myfinance' ``` And then execute: $ bundle Or install it yourself as: $ gem install myfinance ## Configuration Use `Myfinance.configure` to setup your environment: ```ruby 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: ```ruby client = Myfinance.client("YOUR_TOKEN_HERE") ``` ##### Now you have access to these API endpoints: * [Entities API](https://app.myfinance.com.br/docs/api/entities) as `client.entities` * [FinancialTransactions API](https://app.myfinance.com.br/docs/api/financial_transactions) as `client.financial_transactions` * [PayableAccounts API](https://app.myfinance.com.br/docs/api/payable_accounts) as `client.payable_accounts` * [ReceivableAccounts API](https://app.myfinance.com.br/docs/api/receivable_accounts) as `client.receivable_accounts` * [Attachments API](https://app.myfinance.com.br/docs/api/attachments) as `client.attachments` * [Accounts API](https://app.myfinance.com.br/docs/api/multiple_accounts) as `client.accounts` * [DepositAccounts API](https://app.myfinance.com.br/docs/api/deposit_accounts) as `client.deposit_accounts` * [Categories API](https://app.myfinance.com.br/docs/api/categories) as `client.categories` * [ClassificationCenters API](https://app.myfinance.com.br/docs/api/classification_centers) as `client.classification_centers` * [People API](https://app.myfinance.com.br/docs/api/people) as `client.people` * [Webhooks API](https://app.myfinance.com.br/docs/api/webhooks) as `client.webhooks` * [Taxes API](https://app.myfinance.com.br/docs/api/taxes) as `client.taxes` * [CreditCards API](https://app.myfinance.com.br/docs/api/credit_cards) as `client.credit_cards` * [CreditCardsTransactions API](https://app.myfinance.com.br/docs/api/credit_cards_transactions) as `client.credit_cards_transactions` * [Reconciles API](https://app.myfinance.com.br/docs/api/reconciles) as `client.reconciles` * [BankStatements API](https://app.myfinance.com.br/docs/api/bank_statements) as `client.bank_statements` ### Endpoints #### [Entities](https://app.myfinance.com.br/docs/api/entities)
HTTP method Endpoint Client method
GET /entities client.entities.find_all
GET /entities/:id client.entities.find
#### [FinancialTransactions](https://app.myfinance.com.br/docs/api/financial_transactions)
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](https://app.myfinance.com.br/docs/api/payable_accounts)
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](https://app.myfinance.com.br/docs/api/receivable_accounts)
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](https://app.myfinance.com.br/docs/api/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](https://app.myfinance.com.br/docs/api/multiple_accounts)
HTTP method Endpoint Client method
GET /accounts client.accounts.find_all
#### [DepositAccounts](https://app.myfinance.com.br/docs/api/deposit_accounts)
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](https://app.myfinance.com.br/docs/api/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](https://app.myfinance.com.br/docs/api/classification_centers)
HTTP method Endpoint Client method
GET /classification_centers client.classification_centers.find_all
GET /classification_centers/:id client.classification_centers.find
GET /classification_centers client.classification_centers.find_by
POST /classification_centers client.classification_centers.create
PUT /classification_centers/:id client.classification_centers.update
DELETE /classification_centers/:id client.classification_centers.destroy
#### [People](https://app.myfinance.com.br/docs/api/people)
HTTP method Endpoint Client method
GET /people client.people.find_all
GET /people client.people.find_by
GET /people/:id client.people.find
POST /people client.people.create
PUT /people/:id client.people.update
DELETE /people/:id client.people.destroy
#### [Webhooks](https://app.myfinance.com.br/docs/api/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](https://app.myfinance.com.br/docs/api/taxes)
HTTP method Endpoint Client method
GET /taxes client.taxes.find_all
GET /taxes/:id client.taxes.find
#### [CreditCards](https://app.myfinance.com.br/docs/api/credit_cards)
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](https://app.myfinance.com.br/docs/api/credit_card_transactions)
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](https://app.myfinance.com.br/docs/api/reconciles)
HTTP method Endpoint Client method
POST /entities/:entity_id/reconciles client.reconciles.reconcile
#### [BankStatements](https://app.myfinance.com.br/docs/api/bank_statements)
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
### Configuration ```ruby 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: ```ruby 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`](https://github.com/myfreecomm/myfinance-client-ruby/blob/master/lib/myfinance/response.rb#L33) error. The list of available accounts will be in the body of the object. ```ruby 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`. 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. 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](https://rubygems.org). Make sure you have publishing rights for the gem on RubyGems beforehand, though. ## 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](http://opensource.org/licenses/MIT).