README

A comprehensive PHP library for integrating with the VAT Sense API in WordPress applications.

Features

VAT Number Validation: Validate VAT numbers against EU, UK, and other supported countries
EORI Number Validation: Validate Economic Operators Registration and Identification numbers
Tax Rate Information: Get tax rates for specific countries, including standard, reduced, and zero rates
Currency Conversion: Convert between currencies using official exchange rates
VAT Price Calculation: Calculate VAT-inclusive and VAT-exclusive prices
Invoice Creation and Management: Create, retrieve, update, and delete VAT-compliant invoices
WordPress Integration: Built-in transient caching and WP_Error support
Complete API Coverage: All VAT Sense API endpoints supported

Installation

Install via Composer:

composer require arraypress/vat-sense

Usage

Initialization

use ArrayPress\VAT\Sense\Client;

// Initialize the client with your VAT Sense API key
$client = new Client('your_vat_sense_api_key_here');

// Optionally, configure caching
$client->set_cache_enabled(true);
$client->set_cache_expiration(HOUR_IN_SECONDS * 12); // 12 hours

VAT Number Validation

// Validate a VAT number
$response = $client->validate_vat('GB123456789');

if (is_wp_error($response)) {
    echo "Error: " . $response->get_error_message();
} else {
    if ($response->is_vat_valid()) {
        echo "VAT number is valid!";
        echo "Company name: " . $response->get_company_name();
        echo "Company address: " . $response->get_company_address();
        echo "Country code: " . $response->get_country_code();
    } else {
        echo "VAT number is not valid.";
    }
}

Get Tax Rates

// Get tax rates for a country
$response = $client->get_rates_filtered('DE');

if (!is_wp_error($response)) {
    $standard_rate = $response->get_standard_rate_percentage();
    echo "Standard VAT rate: {$standard_rate}%";
    
    // Get reduced rates if available
    $reduced_rates = $response->get_reduced_rates();
    if ($reduced_rates) {
        foreach ($reduced_rates as $rate) {
            echo "Reduced rate: {$rate['rate']}%";
        }
    }
}

// Find a tax rate for a specific product type
$response = $client->find_tax_rate('FR', '', 'ebooks');

Calculate VAT Prices

// Calculate VAT on a price
$response = $client->calculate_vat_price(100.00, 20.0, 'excl');

if (!is_wp_error($response)) {
    $price_excl_vat = $response->get_price_excl_vat();
    $price_incl_vat = $response->get_price_incl_vat();
    $vat_amount = $response->get_vat_amount();
    
    echo "Price (excl. VAT): {$price_excl_vat}";
    echo "VAT amount: {$vat_amount}";
    echo "Price (incl. VAT): {$price_incl_vat}";
}

Currency Conversion

// Convert currency
$response = $client->convert_currency('USD', 'EUR', 50.00);

if (!is_wp_error($response)) {
    $converted_amount = $response->get_converted_amount();
    $exchange_rate = $response->get_exchange_rate();
    
    echo "50.00 USD = {$converted_amount} EUR (rate: {$exchange_rate})";
}

Create and Manage Invoices

// Create an invoice
$invoice_data = [
    'date' => date('Y-m-d H:i:s'),
    'tax_point' => date('Y-m-d H:i:s'),
    'type' => 'sale',
    'tax_type' => 'incl',
    'currency_code' => 'EUR',
    'business' => [
        'name' => 'My Company',
        'address' => "123 Business Street\nLondon\nSW1 1AA\nUnited Kingdom",
        'vat_number' => 'GB123456789',
        'company_number' => '12345678'
    ],
    'customer' => [
        'name' => 'Client Company',
        'address' => "456 Client Avenue\nBerlin\n10115\nGermany",
        'vat_number' => 'DE987654321'
    ],
    'items' => [
        [
            'item' => 'Professional services',
            'quantity' => 1,
            'price_each' => 500.00,
            'vat_rate' => 19.0
        ]
    ]
];

$response = $client->create_invoice($invoice_data);

if (!is_wp_error($response)) {
    $invoice_id = $response->get_invoice_id();
    $invoice_url = $response->get_invoice_url();
    $invoice_pdf_url = $response->get_invoice_url(true);
    
    echo "Invoice created successfully!";
    echo "Invoice ID: {$invoice_id}";
    echo "Invoice URL: {$invoice_url}";
    echo "Invoice PDF URL: {$invoice_pdf_url}";
}

Check API Usage

// Check API usage
$response = $client->get_usage();

if (!is_wp_error($response)) {
    $total = $response->get_total_requests();
    $used = $response->get_used_requests();
    $remaining = $response->get_remaining_requests();
    
    echo "API Usage:";
    echo "Total allowed: {$total}";
    echo "Used: {$used}";
    echo "Remaining: {$remaining}";
}

Cache Management

The library includes built-in caching using WordPress transients:

// Enable or disable caching
$client->set_cache_enabled(true);

// Set cache expiration time (in seconds)
$client->set_cache_expiration(DAY_IN_SECONDS);

// Clear all cached data
$client->clear_cache();

// Clear specific cached data
$client->clear_cache('vat_validate_GB123456789');

API Documentation

For detailed API documentation, visit the VAT Sense API Reference.

Requirements

PHP 7.4 or later
WordPress 5.0 or later

License

This library is licensed under the GPL v2 or later.

Credits

Developed by ArrayPress

arraypress / vat-sense

Maintainers

Details