README

Official PHP SDK for the EuroValidate API — validate EU VAT numbers, IBANs, EORI numbers, look up company data, and retrieve VAT rates.

Zero dependencies. Requires only PHP 8.1+ with the curl and json extensions.

Installation

composer require eurovalidate/sdk

Quick Start

use EuroValidate\EuroValidate;

$client = new EuroValidate('ev_live_your_key');

// Validate a VAT number
$vat = $client->validateVat('NL820646660B01');
echo $vat->valid;        // true
echo $vat->companyName;  // "COOLBLUE B.V."
echo $vat->meta->confidence; // "HIGH"

// Validate an IBAN
$iban = $client->validateIban('DE89370400440532013000');
echo $iban->valid;    // true
echo $iban->bankName; // "Commerzbank"

// Validate an EORI number
$eori = $client->validateEori('DE328169180000040');
echo $eori->valid;

// Look up a company by LEI
$company = $client->lookupCompanyByLei('724500Y6DUVHQD6OXN27');
echo $company->legalName;

// Get VAT rates for a country
$rates = $client->getVatRates('DE');
echo $rates->standardRate; // 19.0

// Get all EU VAT rates
$allRates = $client->getAllVatRates();

// Unified validation (multiple checks in one call)
$result = $client->validate([
    'vat_number' => 'NL820646660B01',
    'iban' => 'DE89370400440532013000',
]);
echo $result->vat->companyName;
echo $result->iban->bankName;

// Account info
$account = $client->getAccount();
echo $account->plan;
echo $account->callsUsed . '/' . $account->callsLimit;

Error Handling

The SDK throws typed exceptions for different error scenarios:

use EuroValidate\Exceptions\AuthException;
use EuroValidate\Exceptions\RateLimitException;
use EuroValidate\Exceptions\ValidationException;
use EuroValidate\Exceptions\ServerException;
use EuroValidate\Exceptions\EuroValidateException;

try {
    $vat = $client->validateVat('INVALID');
} catch (AuthException $e) {
    // 401/403 — invalid or missing API key
    echo "Auth error: " . $e->getMessage();
} catch (RateLimitException $e) {
    // 429 — rate limit exceeded (auto-retried up to 3 times)
    echo "Retry after: " . $e->getRetryAfter() . " seconds";
} catch (ValidationException $e) {
    // 400/422 — invalid input
    echo "Validation error: " . $e->getErrorDetail();
} catch (ServerException $e) {
    // 5xx — server error
    echo "Server error: " . $e->getMessage();
} catch (EuroValidateException $e) {
    // Any other API error
    echo "Request ID: " . $e->getRequestId();
}

Configuration

// Custom base URL (for testing or self-hosted)
$client = new EuroValidate('ev_test_key', baseUrl: 'https://staging-api.eurovalidate.com');

// Custom timeout (default: 30 seconds)
$client = new EuroValidate('ev_live_key', timeout: 60);

Requirements

• PHP 8.1+
• ext-curl
• ext-json

License

MIT