How to Validate EU VAT Numbers with VIES API (and Why Most Teams Use a Wrapper)

import soap from 'node-soap';

const WSDL = 'https://ec.europa.eu/taxation_customs/vies/checkVatService.wsdl';

export async function validateViesDirectly(
  countryCode: string,
  vatNumber: string
) {
  // Creating a new SOAP client on every call is expensive — cache it
  const client = await soap.createClientAsync(WSDL, { timeout: 10000 });

  try {
    const [result] = await client.checkVatAsync({
      countryCode,
      vatNumber: vatNumber.replace(/^[A-Z]{2}/, ''), // Strip country prefix
    });

    return {
      valid: result.valid,
      name: result.name ?? null,
      address: result.address ?? null,
    };
  } catch (err: unknown) {
    // VIES SOAP faults are not well-typed — check the message string
    const message = (err as Error).message ?? '';
    if (message.includes('MS_UNAVAILABLE') || message.includes('SERVICE_UNAVAILABLE')) {
      // The member state's VIES node is down — this is NOT the same as invalid
      throw new Error('VIES_SERVICE_UNAVAILABLE');
    }
    throw err;
  }
}
// Problems with this approach:
// - No caching: every call hits VIES, averaging 800ms–2500ms
// - MS_UNAVAILABLE for invalid looks the same as service down in many SOAP parsers
// - WSDL parsing is slow unless you cache the client
// - No distinction between 'never existed' vs 'previously registered, now inactive'

export async function validateVat(countryCode: string, vatNumber: string) {
  const res = await fetch(
    `https://www.taxid.dev/api/v1/validate/${countryCode}/${vatNumber}`,
    {
      headers: { Authorization: `Bearer ${process.env.TAXID_API_KEY}` },
      signal: AbortSignal.timeout(8000),
    }
  );

  if (!res.ok) throw new Error(`HTTP ${res.status}`);

  return res.json() as Promise<{
    valid: boolean;
    status: 'active' | 'invalid' | 'inactive' | 'format_invalid' | 'service_unavailable';
    company_name: string | null;
    company_address: string | null;
    request_id: string;
  }>;
}
// Advantages over calling VIES directly:
// - REST + JSON instead of SOAP + XML
// - Cached warm responses in < 10ms
// - 5 distinct status codes instead of SOAP fault strings
// - 'inactive' distinguishes deregistered from never-existed
// - 31 countries via a single endpoint (VIES covers only EU27)

import requests
from typing import Literal

StatusCode = Literal['active', 'invalid', 'inactive', 'format_invalid', 'service_unavailable']

def validate_vat(country_code: str, vat_number: str) -> dict:
    r = requests.get(
        f'https://www.taxid.dev/api/v1/validate/{country_code}/{vat_number}',
        headers={'Authorization': f'Bearer {TAXID_API_KEY}'},
        timeout=10,
    )
    r.raise_for_status()
    return r.json()

# Usage
result = validate_vat('DE', 'DE123456789')
match result['status']:
    case 'active':             # Valid — apply reverse charge
    case 'invalid':            # Does not exist
    case 'inactive':           # Was valid, now deregistered
    case 'format_invalid':     # Bad format for DE
    case 'service_unavailable': # VIES temporarily down — allow, retry later