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