Cobrato Client

This is the official Ruby client for the Cobrato API.

Gem Version Build Status Test Coverage Code Climate Grade Inline docs

Compatibility

The Cobrato Ruby Client is compatible with Ruby 2.4.3 or higher.

Installation

Add this line to your application's Gemfile:

gem 'cobrato-client'

And then execute:

$ bundle

Or install it yourself as:

$ gem install cobrato-client

Configuration

Use Cobrato.configure to setup your environment:

require "cobrato"

Cobrato.configure do |config|
  config.url = "https://sandbox.cobrato.com/api/v1" # defaults to "https://app.cobrato.com.br/api/v1"
  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 Cobrato::Client, as below:

client = Cobrato.client("YOUR_TOKEN_HERE")

Now you have acess to every API endpoint:

Endpoints

Payees

HTTP method Endpoint Client method
POST api/v1/payees client.payees.create
GET api/v1/payees client.payees.list
GET api/v1/payees/:id client.payees.show
PUT api/v1/payees/:id client.payees.update
DELETE api/v1/payees/:id client.payees.destroy

Bank Accounts

HTTP method Endpoint Client method
POST api/v1/bank_accounts client.bank_accounts.create
GET api/v1/bank_accounts client.bank_accounts.list
GET api/v1/bank_accounts/:id client.bank_accounts.show
PUT api/v1/bank_accounts/:id client.bank_accounts.update
DELETE api/v1/bank_accounts/:id client.bank_accounts.destroy
GET api/v1/bank_accounts/portfolio_codes client.bank_accounts.portfolio_codes

People

HTTP method Endpoint Client method
POST api/v1/people client.people.create
GET api/v1/people client.people.list
GET api/v1/people/:id client.people.show
PUT api/v1/people/:id client.people.update

Payers (DEPRECATED)

HTTP method Endpoint Client method
POST api/v1/payers client.payers.create
GET api/v1/payers client.payers.list
GET api/v1/payers/:id client.payers.show
PUT api/v1/payers/:id client.payers.update

Charge Configs

HTTP method Endpoint Client method
POST api/v1/charge_configs client.charge_configs.create
GET api/v1/charge_configs client.charge_configs.list
GET api/v1/charge_configs/:id client.charge_configs.show
PUT api/v1/charge_configs/:id client.charge_configs.update
DELETE api/v1/charge_configs/:id client.charge_configs.destroy
POST api/v1/charge_configs/:id/deactivate client.charge_configs.deactivate

Charges

HTTP method Endpoint Client method
POST api/v1/charges client.charges.create
GET api/v1/charges client.charges.list
GET api/v1/charges/:id client.charges.show
PUT api/v1/charges/:id client.charges.update
DELETE api/v1/charges/:id client.charges.destroy
POST api/v1/charges/:id/receive client.charges.receive
POST api/v1/charges/:id/undo_receive client.charges.undo_receive
POST api/v1/charges/:id/deliver_billet client.charges.deliver_billet
GET api/v1/charges/:id/billet client.charges.billet
POST api/v1/charges/:id/cancel client.charges.cancel

Regress Cnab

HTTP method Endpoint Client method
POST api/v1/regress_cnabs client.regress_cnabs.create
GET api/v1/regress_cnabs client.regress_cnabs.list
GET api/v1/regress_cnabs/:id client.regress_cnabs.show
DELETE api/v1/regress_cnabs/:id client.regress_cnabs.destroy
GET api/v1/regress_cnabs/:id/file client.regress_cnabs.file

Remittance Cnab

HTTP method Endpoint Client method
POST api/v1/remittance_cnabs client.remittance_cnabs.create
GET api/v1/remittance_cnabs client.remittance_cnabs.list
GET api/v1/remittance_cnabs/:id client.remittance_cnabs.show
DELETE api/v1/remittance_cnabs/:id client.remittance_cnabs.destroy
GET api/v1/remittance_cnabs/:id/file client.remittance_cnabs.file
GET api/v1/remittance_cnabs/:id/charges client.remittance_cnabs.charges (DEPRECATED)
GET api/v1/remittance_cnabs/:id/items client.remittance_cnabs.items

Credit Card

HTTP method Endpoint Client method
POST api/v1/credit_cards client.credit_cards.create
GET api/v1/credit_cards client.credit_cards.list
GET api/v1/credit_cards/:id client.credit_cards.show
GET api/v1/credit_cards/:id/charges client.credit_cards.charges

Webhooks

HTTP method Endpoint Client method
POST api/v1/webhooks client.webhooks.create
GET api/v1/webhooks client.webhooks.list
GET api/v1/webhooks/:id client.webhooks.show
PUT api/v1/webhooks/:id client.webhooks.update
DELETE api/v1/webhooks/:id client.webhooks.destroy

Charging types

HTTP method Endpoint Client method
GET api/v1/charging_types client.changing_types.list

Charge Template

HTTP method Endpoint Client method
POST api/v1/charge_templates client.charge_templates.create
GET api/v1/charge_templates client.charge_templates.list
GET api/v1/charge_templates/:id client.charge_templates.show
PUT api/v1/charge_templates/:id client.charge_templates.update
DELETE api/v1/charge_templates/:id client.charge_templates.destroy

Payment Config (BETA)

HTTP method Endpoint Client method
POST api/v1/payment_configs client.payment_configs.create
GET api/v1/payment_configs client.payment_configs.list
GET api/v1/payment_configs/:id client.payment_configs.show
PUT api/v1/payment_configs/:id client.payment_configs.update
DELETE api/v1/payment_configs/:id client.payment_configs.destroy

Payment (BETA)

HTTP method Endpoint Client method
POST api/v1/payments client.payments.create
GET api/v1/payments client.payments.list
GET api/v1/payments/:id client.payments.show
PUT api/v1/payments/:id client.payments.update
DELETE api/v1/payments/:id client.payments.destroy
POST api/v1/payments/:id/cancel client.payments.cancel
GET api/v1/payments/schema client.payments.schema
POST api/v1/payments/:id/unauthorize client.payments.unauthorize
POST api/v1/payments/:id/register_error client.payments.register_error
POST api/v1/payments/:id/reschedule client.payments.reschedule

PaymentMethod

HTTP method Endpoint Client method
GET api/v1/payment_methods client.payment_methods.list

Payload signature check

You can check the Cobrato signature on the payload request:

sgnature = Cobrato.signature('secret')
signature.check?(request.headers['X-Cobrato-RequestId'], request.headers['X-Cobrato-Signature'], request.body)
# => true

Callbacks

All actions that change data triggers an event that you can subscribe to. This event allow you to extend the logic executed when you call a client method.

Subscribing to an event

All you have to do is create a class that responds to a method #call with two arguments:

class MyListener
  def call(result, args)
  end
end

Where:

  • result is the return of a client method
  • args is an array of arguments passed to the client method you called

Now you have a listener, you can subscribe to an event:

Cobrato.subscribe("cobrato.payees.destroy", MyListener.new)

Example:

When you call client.payees.destroy(1), an event cobrato.payees.destroy will be triggered. Your listener method #call will receive:

  • result would be true or false - depending on what client.payees.destroy(1) returned
  • args would be [1] - an array with the arguments passed to the client method

Available hooks

  • payees
    • cobrato.payees.create
    • cobrato.payees.destroy
  • bank_accounts
    • cobrato.bank_accounts.create
    • cobrato.bank_accounts.destroy
  • charge_configs
    • cobrato.charge_configs.create
    • cobrato.charge_configs.destroy
  • charges
    • cobrato.charges.create
    • cobrato.charges.destroy
    • cobrato.charges.receive
    • cobrato.charges.undo_receive
    • cobrato.charges.cancel
  • webhooks
    • cobrato.webhooks.create
    • cobrato.webhooks.destroy
  • charge_templates
    • cobrato.charge_templates.create
    • cobrato.charge_templates.destroy

Release

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

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.

Contributing

  1. Fork it ( https://github.com/[my-github-username]/cobrato-client-ruby/fork )
  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 a new Pull Request