Ruby
Ruby helper to connect your backend with VatZen.
VatZen is Deprecated since January 2022 and API server will be shut down soon!
Gem is published in RubyGems register and can be installed by following commands:
gem install vatzen
or
bundle add vatzen
For more extensive documentation, please visit our official docs at https://documentation.vatzen.com
Once you obtained your API key from VatZen Dashboard, you can start using the module. To get started quickly, simply import the module and pass the API Key. After initialization, you can already start calling endpoints:
require 'vatzen'
vatzen = Vatzen.new('your api key')
rates = vatzen.rates.get_rates(member_state: true)
All the rates function are available inside
VatZen object inside rates parameter. For example vatzen.rates.get_rates.In order to obtain all the rates, you can use
rates.get_rates() function, which accepts optional options object with the following (also optional) keys:key | type | description |
limit | number | Limit for pagination |
page | number | Page number, starting from 1 |
member_state | boolean | Response will be filtered by member states only |
getAll usage example:vatzen.rates.get_rates(member_state: true)
If you want to obtain the rate by known ISO Country Code, you can use
rates.get_rate_by_country_code function, which accepts country code string as a parameter. For example:vatzen.rates.get_rate_by_country_code('FR')
You can use VatZen to lookup country rate using different parameters, such as country name, country code or ip address. In order to do that, you can use
rates.find function, which accepts options object with the following properties:key | type | description |
country_code | string | 2 characters ISO country code |
country_name | string | Country name, for example Germany |
ip_address | string | IP Address of your client which will be used to identify the country |
use_client_ip | boolean | If set to true, VatZen will extract ip address from the request |
Example for using this function:
vatzen.rates.get_rate(country_name: 'Germany')
Before using the endpoint, you can familiarize yourself with our Validations endpoint documentation.
All the rates function are available inside
VatZen object inside validation parameter. For example vatzen.validations.validate.VAT number validation is implemented inside
validate function, which accepts only 1 parameter - vat number string. As the response, it returns the complete Validations entity.Example:
vatzen.validation.validate('LU123455');
If you want to validate VAT number and store the validation, you can use
create_validation function, which accepts VAT number as a parameter and returns VAT Entity.Example:
vatzen.validation.create_validation('LU123455');
Returns stored validation object by id. Implemented in
get_validation_by_id function.vatzen.validation.get_validation_by_id('dgy13wjbhbj342');
If you want to fetch all validations, you can use
get_validations function, which accepts optional options object with the following optional parameters:key | type | description |
limit | number | Limit for pagination |
page | number | Page number, starting from 1 |
vatzen.validation.get_validations(page: 2)
VAT prices calculations are implemented inside
prices module in vatzen client, which you can access via vatzen.prices. Before using this endpoint, make sure to read our Official Prices Documentation.Implemented via
vatzen.prices.calculate function. Using this function, you can perform price calculation based on different parameters. If accepts options object, with 1 required fields: amount, and various option fields, which will be used to identify VAT rate.key | type | description |
amount | number | Amount for VAT calculation in cents |
vat_included | boolean | Identifies if VAT already included in amount |
category | VatCategory | VAT Category used for price calculations |
country_code | string | 2 characters ISO country code |
country_name | string | Country name, for example Germany |
ip_address | string | IP Address of your client which will be used to identify the country |
use_client_ip | boolean | If set to true, VatZen will extract ip address from the request |
Example:
calculate_price_for_germany = vatzen.prices.calculate(
amount: 10000,
country_code: 'DE',
category: 'audiobook',
)
print '100 EUR with VAT for AudioBooks in Germany: ' + (calculate_price_for_germany['amount']['total_incl_vat'] / 100).to_s
If you want to calculate price and store the calculation, you can use
create_price_calculation function, which accepts the same parameters as calculate function.Example:
created_price_for_spain = vatzen.prices.create_price_calculation(
amount: 10000,
country_code: 'ES',
)
print 'Created price ID: ' + created_price_for_spain['id']
Returns stored price calculation object by id. Implemented in
get_calculation_by_id function.vatzen.prices.get_calculation_by_id(createdPriceForSpain['id'])
If you want to fetch all calculations you performed, you can use
get_prices function, which accepts optional options object with the following optional parameters:key | type | description |
limit | number | Limit for pagination |
page | number | Page number, starting from 1 |
Last modified 1yr ago