Well, my last post on this blog is from a long, long time ago: let's just say I have been quite busy during this very long time:

• I changed job, and I'm now the senior engineer of the most talented team I had the pleasure to work with in...
• Canada! Yes, I switched country and even continent. It has been a crazy experience, with a few bumps on the way:
  • My move went pretty smooth, but I also had a couple of thrills about expiring visas and healthcare for...
• The birth of my second son!

So, we sure have been busy! So far, I cannot be more grateful for everything I had the chance to live and experience, even the problems. It's a life changing experience.

My new job, the kids and life pretty much consumed all of my free time: just recently though, I had the opportunity to extract some of the code I wrote for an ongoing side business.

Strice is a company based in Italy, and we use the fattura24 online service to perform invoicing. Back home, electronic invoicing is mandatory, and it's better to rely on an external service to correctly perform these duties.

Fattura24 is a pretty simple, yet powerful service: but most importantly it exposes a few api endpoints (link in Italian) to hook invoicing to your code.

On Github, you can easily find a very good javascript library wrapping these calls, but nothing had been developed for Ruby: the opportunity was too good to pass.

Meet https://github.com/snada/fattura24, a simple rubygem to easily interact with the service in simple and Ruby friendly fashion. Find it's rubygems page here, and the live documentation here.

It's tested on Ruby versions 2.4+ and should work on Rails versions after 4.2.

Usage is really simple: first, install the gem:

gem 'fattura24', '~> 1.0'

or directly with:

gem install fattura24

Now, initialize the library with your api secret:

Fattura24.configure do |configuration|
  configuration.api_key = 'your_secret_key'
end

And simply perform the calls you need:

r = Fattura24::Api.save_document(
  document_type: Fattura24::DocumentType::ELECTRONIC_INVOICE,
  customer_name: 'John Doe',
  customer_fiscal_code: 'DOEJHN89A27L219Y',
  customer_address: '100 Yonge Street',
  customer_city: 'Toronto',
  customer_country: 'CA',
  payments: [
    {
      date: '2020-04-27',
      amount: '100',
      paid: 'true'
    }
  ],
  rows: [
    {
      code: '001',
      description: 'Element description',
      qty: '1',
      price: '100'
    }
  ],
  id_template: '65',
  send_email: 'true',
  object: 'test',
  total: 100,
  total_without_tax: 100,
  vat_amount: 0
)

# Call this to see http request went fine
r.success?


# Then you can get your invoice with another call
r = Fattura24::Api.get_file('1234567')

# true if response content is actually a file
if r.pdf?
  # String value of the response will contain the file
  File.write('invoice.pdf', r.to_s)
end

Pretty simple, right?

If I missed something, please feel free to open a pull request.

There are a few things I added on the repo to make working on it a bit easier.

If you want to test against multiple Ruby versions and you have docker installed, you can see a bunch of dockerfiles on the root of the project: simply run

make build && make

to build and run tests on different Ruby images. Travis CI should run on pull requests, but I usually prefer to test locally before pushing anything.

In development, there's also an interactive console you can use to test your changes.

Run it with bin/console: there's some code there already initializing the library, and it tries to do it by reading the API_KEY environment variable. If you want to speed up your work and forget about typing it, simply create a .env file with the key on the root folder.

Happy coding!