Alegra

A ruby client for connecting to Alegra's API.

Please check the official API documentation here

Installation

Add this line to your application's Gemfile:

gem 'alegra'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install alegra

Usage

require 'alegra'
client = Alegra::Client.new('[email protected]', 'your-private-token')

Contacts

You can list all your contacts:

client.contacts.list()

Get a specific contact by id:

client.contacts.find(1)

And you can create a contact as well:

params = {
  name: 'Alan Britho'
}
client.contacts.create(params)

You can update this contact too:

params = {
  name: 'Sinc Hompas'
}
client.contacts.update(1, params)

Or delete it, as follows:

client.contacts.delete(1)

Items

You can list all your items:

client.items.list()

Get a specific item by id:

client.items.find(1)

And you can create an item as well:

params = {
  name: 'a new item',
  price: 1500
}
client.items.create(params)

You can update this item too:

params = {
  name: 'A better name!',
}
client.items.update(1, params)

Or delete it, as follows:

client.items.delete(1)

Invoices

You can get all invoices:

client.invoices.list()

Or get a specific invoice by id:

client.invoices.find(1) # the parameter is the inovice id

Also you are able to create a new invoice, as follows:

params = {
          date: '2016-10-12',
          due_date: '2016-10-12',
          client: 1,
          items: [
                    {
                        id: 1,
                        price: 40,
                        quantity: 5
                    },
                    {
                        id: 2,
                        description: 'Brown leather wallet',
                        price: 80,
                        discount: 10,
                        tax: [
                                {
                                    id: 3,
                                }
                             ],
                        quantity: 1
                    }
                  ],
          account_number: 1234,
          payment_method: 'cash',
          stamp: {
            generate_stamp: true
          },
        }

client.invoices.create(params)

Update that invoice:

params = { observations: 'This invoice was updated!'}
client.invoices.update(1, params)

Send that invoice by email:

params = { emails: ['[email protected]', '[email protected]'], send_copy_to_user: true, invoice_type: 'copy'}
client.invoices.send_by_email(1, params)

Payments

You can get all payments:

client.payments.list()

Or get a specific payment by id:

client.payments.find(1) # the parameter is the payment id

Also you are able to create a new payments, as follows:

params = {
  date: "2015-12-13",
  invoices: [
    {
      id: 6,
      amount: 150
    },
    {
      id: 200,
      amount: 500
    }
  ],
  bank_account: 1
}

client.payments.create(params)

Company

You can get the company:

client.company.find

Also you can update it, as follows:

params = { website: 'nominapp.com' }

client.company.update(params)

Users

You can get the users:

client.users.list

Also you can retrive a specific user by doing:

client.users.find(1)

Lastly you can retrive the current user, as follows:

client.users.find_current

Categories

You can get all the categories on the client account like this:

client.categories.list #this will retrieve the tree format by default

Or if you prefer the plain format from the Alegra API just pass it as a paramater:

client.categories.list(format: 'plain')

You can also retrive a specific category, as follows:

client.categories.find('5047')

BankAccounts

To retrive all bank accounts:

client.bank_accounts.list

Or get a specific bank_account by id:

client.bank_accounts.find(2)

Also you are able to create a new bank accounts, as follows:

params = { name: 'test',
           type: 'bank',
           initial_balance: '100000',
           initial_balance_date: '2020-02-25' }

client.bank_accounts.create(params)

And to create a bank transfer between accounts:

params = { id_destination: 4, # 4 is the destination bank_account_id
           amount: 100000,
           date: '2020-02-25' }
client.bank_accounts.transfer(7, params) # 7 is the origin bank_account_id

Journals

To retrive all existing journals:

client.journals.list

Or get a specif journal by :id:

client.journals.find(191)

You can create journals too, as follows:

params = { date: Date.today.strftime("%Y-%m-%d"),
           client: '416',
           entries: [{ id: '5009', debit: 3_000_000 },
                     { id: '5048', credit: 4_250_660 },
                     { id: '5008', debit: 755_000 },
                     { id: '5010', debit: 495_660 }] }

client.journals.create(params)

Or update them like this:

params = { client: '416'
           entries: [{ id: '5009', debit: 3_000_000 },
                     { id: '5048', credit: 4_150_660 },
                     { id: '5008', debit: 655_000 },
                     { id: '5010', debit: 495_660 }] }

client.journals.update(193, params) # Where 193 is the :id of the journal in Alegra

Lastly you can delete journals, by doing the following:

client.journals.delete(193, params) # Where 193 is the :id of the journal in Alegra

Development

This gem is under construction and I'm writing it with the goal that it will easy to use. However, if you have any recommendation is well received.

After checking out the repo, run bin/setup to install dependencies. Then, run rspec 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.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/degzcs/alegra. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

TODO

The next endpoints are pending:

• Estimates
• Number templates
• Retentions
• Sellers
• payments
  • cancel payment(void)
  • open payment convert https://developer.alegra.com/docs/convertir-pago-a-abierto
  • Add attachment https://developer.alegra.com/docs/adjuntar-archivos-a-pagos

License

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