VATlayer SDKs & Libraries: Integration Guides and Examples

SDKs overview

VATlayer provides a set of official and community-contributed SDKs (Software Development Kits) and libraries to facilitate integration with its VAT number validation and VAT rate lookup API. These SDKs simplify the process of interacting with the VATlayer API by providing language-specific clients, handling HTTP requests, response parsing, and error management. Developers can utilize these tools to embed VAT compliance features directly into their applications without needing to write custom API client code.

The core functionality of the VATlayer API includes validating European Union (EU) VAT numbers for businesses and retrieving current VAT rates for individual countries. The SDKs abstract the underlying RESTful API calls, enabling developers to perform these operations using native language constructs. This approach aims to reduce development time and potential integration errors, as detailed in the VATlayer API documentation.

Official SDKs by language

VATlayer offers official SDKs for several popular programming languages, designed to provide direct access to the API's features. These SDKs are maintained by APILayer GmbH, the owner of VATlayer, ensuring compatibility and adherence to API specifications. The following table summarizes the key details of the official SDKs:

Each SDK provides specific methods for interacting with the VATlayer API endpoints, such as validating a VAT number or looking up VAT rates. For instance, the PHP SDK might offer a validateVatNumber() method, while the Python SDK could have a corresponding validate_vat_number() function. Developers are encouraged to consult the specific VATlayer SDK documentation for detailed usage instructions and available methods for each language.

Installation

Installing VATlayer SDKs typically involves using the package manager specific to the programming language. These commands fetch the necessary library files and integrate them into your project, making the VATlayer API client available for use.

PHP Installation

For PHP projects, Composer is the standard dependency manager. To install the VATlayer PHP client, execute the following command in your project's root directory:

composer require apilayer/vatlayer-php

This command adds the apilayer/vatlayer-php package to your composer.json file and downloads it into your vendor/ directory. After installation, you can include Composer's autoloader in your PHP script to access the SDK classes.

Python Installation

Python developers can install the VATlayer SDK using pip, the Python package installer. Run the following command:

pip install vatlayer-python

This command downloads and installs the vatlayer-python package and its dependencies. Once installed, you can import the library into your Python scripts.

jQuery Installation

The jQuery library for VATlayer is typically integrated client-side. It can be included directly via a Content Delivery Network (CDN) or by downloading the JavaScript file and hosting it locally. An example of CDN inclusion in an HTML file is:

<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<script src="https://api.vatlayer.com/api/jquery_sdk.js"></script> // Example path, verify actual CDN path in docs

Refer to the VATlayer jQuery integration guide for the precise CDN link and usage.

Go Installation

Go modules are used to manage dependencies in Go projects. To add the VATlayer Go SDK, use the go get command:

go get github.com/apilayer/vatlayer-go

After running this command, the module will be added to your go.mod file. You can then import it into your Go source files.

Ruby Installation

For Ruby projects, the RubyGems package manager is used. Install the VATlayer Ruby gem with:

gem install vatlayer-ruby

Once installed, you can require the gem in your Ruby scripts.

Quickstart example

The following examples demonstrate how to use the VATlayer SDKs to perform a basic VAT number validation, which is a common use case for the API. These snippets assume you have already installed the respective SDK and have an API key available from your VATlayer account.

PHP Quickstart

This PHP example validates a hypothetical German VAT number.

<?php
require 'vendor/autoload.php';

use Apilayer\Vatlayer\Client;
use Apilayer\Vatlayer\Enums\VatlayerApiEndpoints;
use Apilayer\Vatlayer\Enums\VatlayerApiMethods;

$access_key = 'YOUR_VATLAYER_API_KEY'; // Replace with your actual API key
$client = new Client($access_key);

try {
    $response = $client->call(VatlayerApiEndpoints::VALIDATE, [
        VatlayerApiMethods::VALIDATE_VAT_NUMBER => 'DE815250462',
    ]);

    if ($response->isSuccess()) {
        echo "VAT Number: " . $response->getVatNumber() . "\n";
        echo "Valid: " . ($response->isValid() ? 'Yes' : 'No') . "\n";
        echo "Company Name: " . $response->getCompanyName() . "\n";
    } else {
        echo "Error: " . $response->getError()->getInfo() . "\n";
    }
} catch (Exception $e) {
    echo "An unexpected error occurred: " . $e->getMessage() . "\n";
}
?>

Python Quickstart

This Python example validates a hypothetical French VAT number.

import requests

API_KEY = 'YOUR_VATLAYER_API_KEY' # Replace with your actual API key
VAT_NUMBER = 'FR23476834000'

try:
    response = requests.get(f'http://api.vatlayer.com/validate?access_key={API_KEY}&vat_number={VAT_NUMBER}')
    response.raise_for_status() # Raise an exception for HTTP errors (4xx or 5xx)
    data = response.json()

    if data.get('success'):
        print(f"VAT Number: {data.get('vat_number')}")
        print(f"Valid: {'Yes' if data.get('valid') else 'No'}")
        print(f"Company Name: {data.get('company_name')}")
    else:
        print(f"Error: {data.get('error', {}).get('info', 'Unknown error')}")
except requests.exceptions.RequestException as e:
    print(f"An error occurred during the request: {e}")
except ValueError:
    print("Failed to decode JSON response.")

Note: The Python example above uses the requests library for direct API interaction, which is a common way to consume REST APIs in Python when a dedicated SDK might not be strictly necessary or for simpler integrations. While VATlayer provides a Python SDK, direct requests usage is also well-documented and widely adopted for similar API interactions, as detailed in the Requests library documentation.

jQuery Quickstart

This jQuery example performs a client-side validation of a VAT number using AJAX.

<script>
$(document).ready(function() {
    var access_key = 'YOUR_VATLAYER_API_KEY'; // Replace with your actual API key
    var vat_number = 'IE6388047V'; // Example Irish VAT number

    $.ajax({
        url: 'http://api.vatlayer.com/validate',
        data: {
            access_key: access_key,
            vat_number: vat_number
        },
        dataType: 'jsonp', // Use jsonp for cross-domain requests
        success: function(json) {
            if (json.success) {
                console.log('VAT Number: ' + json.vat_number);
                console.log('Valid: ' + (json.valid ? 'Yes' : 'No'));
                console.log('Company Name: ' + json.company_name);
            } else {
                console.error('Error: ' + json.error.info);
            }
        },
        error: function(jqXHR, textStatus, errorThrown) {
            console.error('AJAX Error: ' + textStatus, errorThrown);
        }
    });
});
</script>

Note: Client-side API calls expose your API key. For production environments, it is generally recommended to route API calls through a secure backend server to protect your API key and control access, as outlined in general API key security best practices.

Community libraries

While VATlayer provides official SDKs, the API's RESTful nature and JSON output also allow for community-driven client libraries or direct HTTP client usage across virtually any programming language. These community contributions may offer alternative implementations or support for languages not covered by official SDKs.

Developers often create their own wrappers or utilities for APIs like VATlayer when specific features or integration patterns are required that are not present in official offerings. These can range from simple HTTP request functions to more elaborate frameworks that handle caching, rate limiting, or specific data transformations. The API's straightforward design facilitates such custom implementations, as developers can use any HTTP client library (e.g., Axios in JavaScript, Guzzle in PHP, Apache HttpClient in Java) to interact with the endpoints directly, as described in the VATlayer API reference.

When considering community-developed libraries, it is important to evaluate their maintenance status, documentation, and community support. These factors can influence the long-term viability and security of integrating such libraries into a production system. For critical applications, relying on official SDKs or well-maintained, proven direct HTTP client implementations is generally recommended.

The VATlayer API's consistent structure, which adheres to common REST principles, means that even without a specific SDK, developers can integrate the service efficiently using standard web development practices. This flexibility is a common characteristic of modern web APIs, allowing for broad adoption across diverse technology stacks.