README.rdoc
= charging-client-ruby
A Ruby client for the Charging REST API
{<img src="https://badge.fury.io/rb/charging-client.png" alt="Gem Version" />}[https://rubygems.org/gems/charging-client]
{<img src="https://travis-ci.org/myfreecomm/charging-client-ruby.png?branch=master" alt="Build Status" />}[https://travis-ci.org/myfreecomm/charging-client-ruby]
{<img src="https://coveralls.io/repos/myfreecomm/charging-client-ruby/badge.png?branch=master" alt="Coverage Status" />}[https://coveralls.io/r/myfreecomm/charging-client-ruby]
{<img src="https://codeclimate.com/github/myfreecomm/charging-client-ruby.png" alt="Code Climate Status" />}[https://codeclimate.com/github/myfreecomm/charging-client-ruby]
Charging API docs: ???
charging-client-ruby RDoc documentation: http://rubydoc.info/github/myfreecomm/charging-client-ruby/frames/
The {RDoc}[http://rubydoc.info/github/myfreecomm/charging-client-ruby/frames/] is the best place to learn how to use this client. A few example uses are listed below. See the mapping of API endpoints to this client code below as well to find what you need.
== Installation
Add this line to your application's Gemfile:
gem 'charging-client', :require => 'charging'
And then execute:
$ bundle
Or install it yourself as:
$ gem install charging-client
== Usage
=== Mapping of API endpoints to this client
TODO
=== Configuration
require "charging"
Charging.configure do |c|
# You application token at Charging Service
# Required
c.application_token = 'YourApptoken=='
# URL for request data.
# Default: 'https://charging.finnanceconnect.com.br'
c.url = 'http://sandbox.charging.financeconnect.com.br'
# User agent to identify the http request on Charing.
# Default: 'Charging Ruby Client v0.0.1'
c.user_agent = 'My App v1.0'
end
=== Examples
==== Getting info about your service account
account = Charging::ServiceAccount.current
account.name # => 'Your App Name on Charging'
account.last_response # a success RestClient::Response instance
account.last_response.code # => 200
begin
account = Charging::ServiceAccount.current
rescue Charging::Http::LastResponseError => exception
exception.last_response # an unauthorized RestClient::Response instance
exception.last_response.code # 401
end
==== List domains for an account
domains = Charging::Domain.find_all(account)
==== Create a new domain
attributes = {
:supplier_name => 'Myfreecomm',
:address => 'Rua do Carmo, 43',
:city_state => 'Rio de Janeiro/RJ',
:zipcode => '20011-020',
national_identifier => '37.818.380/0001-86',
description => 'A Myfreecomm é uma empresa moderna...'
}
new_domain = Charging::Domain.new(attributes, account)
new_domain.persisted? # => false
new_domain.create!
new_domain.persisted? # => true
==== Find a domain by uuid
domain = Charging::Domain.find_by_uuid(account, 'supposed-uuid-for-domain')
domain.persisted? # => true
==== Update an attribute of a domain (Not working yet)
Pending
=== Update all attributes for a domain (Not working yet)
Pending
==== Delete a domain
domain.destroy!
domain.deleted? # => true
domain.persisted? # => false
==== Find a domain by token
domain = Charging::Domain.find_by_token('domain-token')
==== Create a charge account for a domain
attributes = {
:bank => '237',
:name => 'Conta de Cobrança no Bradesco',
:agreement_code => '1234',
:portifolio_code => '25'
:agency => {:number => '1234'},
:account => {:number => '12345', :digit => '6'}
}
new_charge_account = Charging::ChargeAccount.new(attributes, domain)
new_charge_account.persisted? # => false
new_charge_account.create!
new_charge_account.persisted? # => true
==== List charge accounts for current domain
charge_accountes = ChargeAccount::ChargeAccount.find_all(domain)
==== Find a charge account by uuid
charge_account = ChargeAccount::ChargeAccount.find_by_uuid(domain, 'supposed-uuid-for-charge-account')
charge_account.persisted? # => true
==== List available banks for a charge account (Not working yet)
Pending
==== List currencies for a charge account (Not working yet)
Pending
==== Update an attribute of a charge account
charge_account.update_attribute! :address, 'Novo Endereço'
==== Update attributes of a charge account
charge_account.update_attributes! address: 'Novo Endereço', city_state: 'Cidade/UF'
Note: This will execute <tt>charge_account#update_attribute!</tt> for each attribute. If something wrong, updated attributes will not get back old values.
==== Delete a charge account
charge_account.destroy!
==== Get invoice kinds
Invoice.kinds(domain) # => [{"acronym"=>"DM", "itau_code"=>1, "code"=>2, "name"=>"Duplicata Mercantil"}, ...]
Invoice.kinds(domain)
==== Create an invoice
attributes = {
:kind => 1,
:amount => 123.45,
:document_number => '123456789012345',
:due_date => '2015-12-31'
:drawee => {
:name => 'Fulano de Tal',
:address => 'Rua do Carmo, 43',
:city_state => 'Rio de Janeiro/RJ',
:zipcode => '20011-020',
:national_identifier => '43.055.679/0001-29'
}
}
new_invoice = Charging::Invoice.new(attributes, domain, charge_account)
new_invoice.persisted? # => false
new_invoice.create!
new_invoice.persisted? # => true
==== Find an invoice by uuid
invoice = Charging::Invoice.find_by_uuid(domain, 'supposed-uuid-for-invoice')
invoice.persisted? # => true
==== Get URL to print invoice
invoice.billet_url # => 'https://charging.financeconnect.com.br/billets/6a60.../ff01.../'
==== Delete an invoice
invoice.destroy!
invoice.deleted? # => true
invoice.persisted? # => false
==== Register a payment for an invoice
invoice.pay!
invoice.paid # => invoice.amount
invoice.pay!({
:amount => invoice.amount, # default
:date => Time.now.strftime('%Y-%m-%d'), #default
:note => 'some important note about this payment'
})
==== List payments for an invoice
invoice.payments
==== Batches (Not working yet)
Pending
== Contributing
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request