Liberic is a ruby wrapper for ERiC, a C library to interact with German Tax Authority's ELSTER service.
WARNING: This gem is at a very early stage and not able to do much useful stuff.
This README can only give a brief overview. You can look up the complete documentation on RubyDoc.info.
Add this line to your application's Gemfile:
And then execute:
Or install it yourself (not possible yet) as:
$ gem install liberic
The ERiC library files are not distributed with this gem. They must be obtained from the ELSTER Downloads Page. (Requires your personal credentials which have to be requested from ELSTER).
Follow the installation instructions from the ERiC documentation.
After extracting the downloaded library files to a location of your choice, there should be a folder containing at least three subfolders:
bin/ include/ lib/
Currently, the environment variable
ERIC_HOME_27 needs to be set to this
folder or the gem will not find the library files.
$ export ERIC_HOME_27=/opt/ERiC-22.214.171.124/Linux-x86_64
Additional steps on OS X
On Mac OS X you need to process the libraries to fix the interal paths (credits to @deviantbits):
libs=`ls $ERIC_HOME_27/lib/*.dylib` plugins=`ls $ERIC_HOME_27/lib/plugins2/*.dylib` for target in $libs do for lib in $libs do install_name_tool -change "@rpath/"`basename $lib` "$ERIC_HOME_27/lib/"`basename $lib` $target done for plugin in $plugins do install_name_tool -change "@rpath/plugins2/"`basename $plugin` "$ERIC_HOME_27/lib/plugins2/"`basename $plugin` $target done done for target in $plugins do for lib in $libs do install_name_tool -change "@rpath/"`basename $lib` "$ERIC_HOME_27/lib/"`basename $lib` $target done done
Check your settings by running:
$ ls $ERIC_HOME_27/lib/libericapi.*
This should list you one file with an operating system dependend suffix.
The gem exposes an interface to ERiC's native functions inside the
Function names have been converted from camel case and stripped of the 'Eric' prefix, otherwise the original (German) names have been kept.
is in Ruby:
A more Ruby friendly encapsulation of the ERiC functionality is in the
making (check out
The following script will load an example tax filing (from the SDK) to validate it with ERiC.
require 'liberic' # Use a convenience wrapper that deals with creating a buffer for the # native function's results. This will also raise a Ruby exception if # the native function returns anything else then 0 (= OK). version_info = Liberic::Helpers::Invocation.with_result_buffer do |handle| # Call ERiC function EricVersion() Liberic::SDK::API::version(handle) end # version info contains XML with all ERiC libraries and their versions. puts version_info # Read example file that declares income tax for 2011. Assumes you have extraced # the 'Beispiel' folder that comes with the ERiC libraries. tax_filing = File.read(File.expand_path('Beispiel/ericdemo-java/steuersatz.xml', Liberic.eric_home)) # Liberic::Process is a high level wrapper around ERiC's EricBearbeiteVorgang() function. submission = Liberic::Process.new(tax_filing, 'ESt_2011') # Check for validity of the XML schema submission.check # Submit tax filing for a dry run (validity of the fields will be checked). result = submission.execute # Will be empty if everything was ok. Otherwise, result contains XML with a list of offending fields. # Try editing the example file to see this in action- for example change the year of birth to a future year, etc. puts result
This gem is rather early stage. It does not implement all ERiC features
yet. It does support submitting various tax filings via
Liberic::Process which should be sufficient for the majority of use
cases. Dealing with certificates (necessary for retrieving the tax
assessment or cryptographically signing a tax filing) is possible, but
no Ruby style wrapper exists yet.
Please refer to
Liberic::SDK::API and the official docs for this.
This library is used in production for submitting tax filings. Not all
of the methods implemented in
Liberic::SDK::API have been tested
though, so the data types defined there might be wrong.
Please consider this if you encounter problems and are looking for bugs in your code.
Pull requests, improvements and examples are welcome, we are all in this together :)
After checking out the repo, run
bin/setup to install dependencies. Then, run
rake spec 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.
Bug reports and pull requests are welcome on GitHub at https://github.com/mpm/liberic. 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.