VAT Layer - Ismena website

info@ismena.com

Vatlayer Connector

Connector Details

Type

Virtual machines, Single VM , BYOL

Runs on

Google Compute Engine

Last Update

24 October, 2024

Category

Overview

The Vatlayer Connector facilitates seamless integration providing access to VAT number validation, EU VAT rates retrieval, and price calculations for EU member states. This connector acts as a proxy to streamline data retrieval, supporting actions for VAT number validation, single country VAT rates, all EU VAT rates, price calculations with VAT, and reduced VAT rate types.

Integration Overview

This document provides a detailed guide for each integration point, its purpose, configuration, and workflow support using the Vatlayer Connector.

Supported Integration Action Points

validateVatNumber: Validates a provided VAT number and retrieves associated company information.
getVatRate: Retrieves VAT rates for a specified EU member state.
getAllVatRates: Retrieves VAT rates for all 28 EU member states.
calculateVatPrice: Calculates a VAT-compliant price based on a provided amount and country.
getVatTypes: Retrieves a list of available reduced VAT rate types.

Detailed Integration Documentation

VAT Number Validation

Action	validateVatNumber
Purpose	Validates a provided VAT number and returns company information, such as name and address, for financial or compliance purposes.
Parameters	Required: access_key: Your API key (string, e.g., YOUR-API-KEY) vat_number: The VAT number to validate (string, e.g., LU26375245) Optional: format: Set to 1 for JSON formatting (integer, e.g., 1) callback: Callback function name for JSONP support (string)
Output	Successful: Returns a JSON object with: valid: Indicates if the VAT number is valid (boolean, e.g., true) database: Status of the VAT database (string, e.g., "ok") format_valid: Indicates if the VAT number format is valid (boolean, e.g., true) query: The VAT number queried (string, e.g., "LU26375245") country_code: The 2-letter country code (string, e.g., "LU") vat_number: The VAT number without country code (string, e.g., "26375245") company_name: The name of the company (string, e.g., "AMAZON EUROPE CORE S.A R.L.") company_address: The address of the company (string, e.g., "5, RUE PLAETIS L-2338 LUXEMBOURG") Failure: Returns error details (e.g., error: {code: 104, type: "invalid_access_key", info: "You have not supplied a valid API Access Key."})
Workflow Example	Execute the validateVatNumber action with access_key and vat_number=LU26375245. Process the response to verify the VAT number and retrieve company details. Use the data for compliance checks or customer validation.

Single Country VAT Rates Retrieval

Action	getVatRate
Purpose	Retrieves VAT rates for a specified EU member state, including standard and reduced rates, based on country code, IP address, or client IP.
Parameters	Required: access_key: Your API key (string, e.g., YOUR-API-KEY) country_code: The 2-letter country code (string, e.g., "DE") Optional: ip_address: The IP address to determine the country (string, e.g., "176.249.153.36") use_client_ip: Set to 1 to use the client's IP address (integer, e.g., 1) format: Set to 1 for JSON formatting (integer, e.g., 1) callback: Callback function name for JSONP support (string)
Output	Successful: Returns a JSON object with: success: Success status (boolean, e.g., true) country_code: The 2-letter country code (string, e.g., "DE") country_name: The country name (string, e.g., "Germany") standard_rate: The standard VAT rate in percent (number, e.g., 19) reduced_rates: Object with reduced VAT rates for specific goods (e.g., {"foodstuffs": 7, "books": 7, "medical": 7}) Failure: Returns error details (e.g., error: {code: 104, type: "invalid_access_key", info: "You have not supplied a valid API Access Key."})
Workflow Example	Execute the getVatRate action with access_key and country_code=DE. Review the response to obtain standard and reduced VAT rates. Use the rates for pricing or tax calculations.

All EU VAT Rates Retrieval

Action	getAllVatRates
Purpose	Retrieves VAT rates for all 28 EU member states, providing a comprehensive dataset for multi-country tax calculations.
Parameters	Required: access_key: Your API key (string, e.g., YOUR-API-KEY) Optional: format: Set to 1 for JSON formatting (integer, e.g., 1) callback: Callback function name for JSONP support (string)
Output	Successful: Returns a JSON object with: success: Success status (boolean, e.g., true) rates: Array of objects with: country_code: The 2-letter country code (string, e.g., "DE") country_name: The country name (string, e.g., "Germany") standard_rate: The standard VAT rate (number, e.g., 19) reduced_rates: Object with reduced VAT rates (e.g., {"foodstuffs": 7, "books": 7}) Failure: Returns error details (e.g., error: {code: 104, type: "invalid_access_key", info: "You have not supplied a valid API Access Key."})
Workflow Example	Execute the getAllVatRates action with access_key. Process the response to obtain VAT rates for all EU countries. Use the data for cross-country tax analysis or e-commerce applications.

VAT Compliant Price Calculation

Action	calculateVatPrice
Purpose	Calculates a VAT-compliant price based on a provided amount and country, accounting for standard or reduced VAT rates.
Parameters	Required: access_key: Your API key (string, e.g., YOUR-API-KEY) amount: The amount/price for VAT calculation (number, e.g., 100) country_code: The 2-letter country code (string, e.g., "GB") Optional: ip_address: The IP address to determine the country (string, e.g., "176.249.153.36") use_client_ip: Set to 1 to use the client's IP address (integer, e.g., 1) type: The type of goods for reduced VAT rates (string, e.g., "medical") incl: Set to 1 if the amount includes VAT (integer, e.g., 1) format: Set to 1 for JSON formatting (integer, e.g., 1) callback: Callback function name for JSONP support (string)
Output	Successful: Returns a JSON object with: success: Success status (boolean, e.g., true) country_code: The 2-letter country code (string, e.g., "GB") country_name: The country name (string, e.g., "United Kingdom") price_excl_vat: Price excluding VAT (number, e.g., 125) price_incl_vat: Price including VAT (number, e.g., 150) vat_rate: The applied VAT rate (number, e.g., 20) type: The type of goods, if specified (string, e.g., "medical") Failure: Returns error details (e.g., error: {code: 104, type: "invalid_access_key", info: "You have not supplied a valid API Access Key."})
Workflow Example	Execute the calculateVatPrice action with access_key, amount=100, and country_code=GB. Save the calculated prices for financial reporting or e-commerce checkout. Use the result for pricing displays or tax calculations.

Reduced VAT Rate Types Retrieval

Action	getVatTypes
Purpose	Retrieves a list of available reduced VAT rate types, enabling applications to apply appropriate tax rates for specific goods.
Parameters	Required: access_key: Your API key (string, e.g., YOUR-API-KEY) Optional: format: Set to 1 for JSON formatting (integer, e.g., 1) callback: Callback function name for JSONP support (string)
Output	Successful: Returns a JSON object with: success: Success status (boolean, e.g., true) types: Array of reduced VAT rate types (e.g., ["foodstuffs", "books", "medical"]) Failure: Returns error details (e.g., error: {code: 104, type: "invalid_access_key", info: "You have not supplied a valid API Access Key."})
Workflow Example	Execute the getVatTypes action with access_key. Review the response to identify available reduced VAT rate types. Use the types to configure pricing rules for specific goods.

Workflow Creation with the Connector

Example Workflow: VAT Validation and Price Calculation

Step	Validate VAT Number
Workflow Example	Use the validateVatNumber action with access_key and vat_number=LU26375245 to verify a customer's VAT number. Confirm the validity and retrieve company details for compliance.
Step	Retrieve VAT Rates
Workflow Example	Execute the getVatRate action with access_key and country_code=DE to fetch VAT rates for a specific country. Alternatively, use getAllVatRates with access_key to obtain rates for all EU countries. Process the rates for tax calculations or pricing strategies.
Step	Calculate VAT-Compliant Price
Workflow Example	Execute the calculateVatPrice action with access_key, amount=100, country_code=GB, and optionally type=medical to calculate prices with applicable VAT rates. Use the calculated prices for e-commerce checkout or invoicing.
Step	Configure Reduced VAT Rates
Workflow Example	Execute the getVatTypes action with access_key to fetch available reduced VAT rate types. Apply the appropriate type (e.g., "medical") in subsequent calculateVatPrice calls for accurate pricing.

Pricing

bill-and-calculator-2023-11-27-05-25-06-utc 1

Request a Quote

Support

For Technical support please contact us on

custom-connectors-support@isolutions.sa

A tech solution company dedicated to providing innovation thus empowering businesses to thrive in the digital age.

Register to IBM x iSolution Event