Fattura24

Simple, lightweight and with minimal dependencies ruby 2+ wrapper for the Fattura24 apis.

Tested and developed on rubies 2.4+.

Installation

Add this line to your application's Gemfile:

gem 'fattura24'

And then execute:

$ bundle

Or install it yourself as:

$ gem install fattura24

Usage

First, configure the module by adding your api key.

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

Once set, you can call the api methods to get the responses you need.

# This method checks if your key is valid
response = Fattura24::Api.test_key

# Check for possible network errors, returns true on ok (200) responses
puts response.success?

# Call .to_h to get a hash version of the xml response
puts response.to_h[:returnCode]

# If you need more info, check the raw Net::HTTP response object
raw_response = response.http_response

Api calls

You can take inspiration on the params to provide to your calls by visiting the official documentation. Generally speaking, this library will translate the structure of your hash to an equivalent xml document camelizing all of your keys.

TestKey, GetTemplate, GetPdc, GetNumerator

All of these calls don't require any argument. Simply call them and inspect their response:

r = Fattura24::Api.test_key
r = Fattura24::Api.get_template
r = Fattura24::Api.get_pdc
r = Fattura24::Api.get_numerator

puts r.to_h

SaveCustomer

r = Fattura24::Api.save_customer(
  customer_name: 'John Doe',
  customer_address: '100 Yonge Street',
  customer_city: 'Toronto',
  customer_country: 'CA',
  customer_fiscal_code: 'Set this for persons',
  customer_vat_code: 'vat',
  customer_email: 'some@email.com',
  fe_customer_pec: 'a@pec.com'
)

SaveDocument

r = Fattura24::Api.save_document(
  document_type: Fattura24::DocumentType::ELECTRONIC_INVOICE,
  customer_name: 'John Doe',
  customer_fiscal_code: 'NDASFN89A27L219Y',
  customer_address: '100 Yonge Street',
  customer_city: 'Toronto',
  customer_country: 'CA',
  fe_payment_code: Fattura24::FePaymentCode::CREDIT_CARD,
  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
)

GetFile

r = Fattura24::Api.get_file('1234567')

# true if response content is actually a file
if r.pdf?
  File.write('invoice.pdf', r.to_s)
end

GetProduct

# gets all products
r = Fattura24::Api.get_product

# filters by code
r = Fattura24::Api.get_product(code: 'some_code')

# filters by category
r = Fattura24::Api.get_product(category: 'some_category')

# combines both
r = Fattura24::Api.get_product({
  code: 'some_code',
  category: 'some_category'
})

Development

After checking out the repo, run bundle to install dependencies. You can 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 run tests and linting, simply run bundle exec rake.

When you edit something, include appropriate docs and rebuild them by running bundle exec rake rdoc.

If you have docker installed, you can test against all of the supported ruby versions by running:

$ make build

That will build the required docker images, and then you can run tests with:

$ make

Release of a new version

To release a new version, update the version number in lib/fattura24/version.rb. Make sure version tests are still satisfied. 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

Everyone is welcome to contribute. This project tries to follow the git-flow branching model. Open a branch named feature/<name> and make a PR against develop.

Please, make sure you include appropriate unit tests to the codebase (also check coverage) and that your code satisfies rubocop checks.

License

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