# 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 ## Usage ##### Given your token, create an instance of Myfinance::Client, as below: ```ruby client = Myfinance.client("YOUR_TOKEN_HERE") ``` ##### Now you have access to every API endpoint: * [Entities API](https://app.myfinance.com.br/docs/api/entities) as `client.entities` * [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` ### 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
#### [PayableAccounts](https://app.myfinance.com.br/docs/api/payable_accounts)
HTTP method Endpoint Client method
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
#### [ReceivableAccounts](https://app.myfinance.com.br/docs/api/receivable_accounts)
HTTP method Endpoint Client method
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
#### [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
### 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 `version.rb`, and 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). ## 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).