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.