VIES (VAT Validation) #

A Dart client for the EU VIES checkVat SOAP service. Validates a VAT number and, when valid, returns the registered business information (legal name, address) published by the member state.

Install #

dart pub add vies      # Dart
flutter pub add vies   # Flutter

Usage #

import 'package:vies/vies.dart';

Future<void> main() async {
  try {
    final response = await ViesProvider.validateVat(
      countryCode: 'BE',
      vatNumber: '1000341796',
      timeout: const Duration(seconds: 15),
      retries: 2, // transient VIES faults are retried with backoff
    );
    print('Valid VAT for ${response.name}');
    print('Address: ${response.address}');
  } on ViesClientError catch (e) {
    // Invalid VAT, parsing errors, INVALID_INPUT faults ...
    print('Client error: ${e.code.wireName} — ${e.message}');
  } on ViesServerError catch (e) {
    // Network, timeout, VIES outage ...
    print('Server error: ${e.code.wireName} — ${e.message}');
  }
}

Validation levels #

// Offline regex check only (no network call):
await ViesProvider.validateVat(
  countryCode: 'FR',
  vatNumber: '64443061841',
  validationLevel: ValidationLevel.regex,
);

// Skip the regex pre-check, hit VIES directly:
await ViesProvider.validateVat(
  countryCode: 'FR',
  vatNumber: '64443061841',
  validationLevel: ValidationLevel.vies,
);

// Default: regex first, then VIES (saves a network round-trip on bad input):
await ViesProvider.validateVat(
  countryCode: 'FR',
  vatNumber: '64443061841',
  // validationLevel: ValidationLevel.all,
);

A regex-only result is not a validation. source says which check answered, so a shape check is never recorded as a confirmation from a member state:

final response = await ViesProvider.validateVat(
  countryCode: 'FR',
  vatNumber: '64443061841',
  validationLevel: ValidationLevel.regex,
);
response.valid;  // true
response.source; // ValidationSource.regex, nobody confirmed anything

Offline shape check #

VatShape answers without a network call. RegexType.eu applies the format published by each member state, RegexType.world a single permissive shape:

VatShape.isValid('NL123456789b01', RegexType.eu); // true, case-insensitive
VatShape.isValid('RO99908', RegexType.eu);        // true, RO is 2 to 10 digits
VatShape.isValid('DE12345', RegexType.eu);        // false, DE is 9 digits

VatShape.normalize(' 1234 5678-9b01 '); // 123456789B01
VatShape.supportedCountryCodes;         // the prefixes RegexType.eu knows

Reusing an HTTP client #

For batch validation, inject a shared http.Client to enable connection pooling:

final client = http.Client();
try {
  for (final vat in batch) {
    await ViesProvider.validateVat(
      countryCode: vat.country,
      vatNumber: vat.number,
      client: client,
    );
  }
} finally {
  client.close();
}

timeout bounds one attempt, not the whole call. With retries: 2 a call can take up to three times the timeout plus the backoff, which is capped at maxRetryBackoff.

Test endpoint #

serviceUrl selects the endpoint. The VIES test service answers deterministically from the VAT number tail, which is useful in integration tests that must not touch the real database:

await ViesProvider.validateVat(
  countryCode: 'BE',
  vatNumber: '100',
  serviceUrl: viesTestServiceUrl,
);

Country prefixes #

VIES uses ISO 3166-1 alpha-2 codes, with two exceptions:

• EL for Greece (instead of GR).
• XI for Northern Ireland (post-Brexit).

Error codes #

Dependencies #

• http

License #

MIT - see LICENSE.