Package Exports

vat-id-validator
vat-id-validator/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (vat-id-validator) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

VAT ID Validator - Node.js Client

Official Node.js client for the VAT ID Validator API. Validate EU VAT numbers using the VIES (VAT Information Exchange System) database.

Installation

npm install vat-id-validator

Quick Start

import { VatValidatorClient } from 'vat-id-validator';

// Initialize with API key
const client = new VatValidatorClient({
  apiKey: 'your-rapidapi-key'
});

// Validate a VAT number
const result = await client.validateVat({
  countryCode: 'IT',
  vatNumber: '00743110157'
});

if (result.valid) {
  console.log(`Valid VAT for: ${result.name}`);
  console.log(`Address: ${result.address}`);
} else {
  console.log('Invalid VAT number');
}

Features

✅ TypeScript Support - Full type definitions included
✅ Environment Variables - API key via RAPIDAPI_KEY env var
✅ Configurable Endpoint - Change base URL for testing or custom deployments
✅ Error Handling - Comprehensive error handling with custom error types
✅ Modern ES Modules - Full ESM support

Configuration

Constructor Options

const client = new VatValidatorClient({
  apiKey: 'your-rapidapi-key',        // RapidAPI key (or use RAPIDAPI_KEY env var)
  baseUrl: 'https://custom-url.com',  // Optional: Override API endpoint
  timeout: 15000                      // Optional: Request timeout in ms (default: 10000)
});

Environment Variable

Instead of passing the API key in the constructor, you can set it via environment variable:

export RAPIDAPI_KEY=your-rapidapi-key

// API key will be read from environment
const client = new VatValidatorClient();

Runtime Configuration

You can update the API key or base URL at runtime:

client.setApiKey('new-api-key');
client.setBaseUrl('https://new-endpoint.com');

API Reference

`validateVat(request)`

Validate a VAT number (basic validation).

Parameters:

countryCode (string) - 2-letter ISO country code (e.g., 'DE', 'IT', 'FR')
vatNumber (string) - VAT number without country prefix

Returns: Promise<ValidateVatResponse>

const result = await client.validateVat({
  countryCode: 'DE',
  vatNumber: '169838187'
});

console.log(result);
// {
//   countryCode: 'DE',
//   vatNumber: '169838187',
//   requestDate: '2025-12-30T10:00:00.000Z',
//   valid: true,
//   name: 'Google Germany GmbH',
//   address: 'ABC Street 123, Berlin'
// }

`validateVatApprox(request)`

Validate a VAT number with approximate matching (advanced validation with trader details).

Parameters:

countryCode (string) - 2-letter ISO country code
vatNumber (string) - VAT number without country prefix
traderName (string, optional) - Company name for matching
traderStreet (string, optional) - Street address for matching
traderPostalCode (string, optional) - Postal code for matching
traderCity (string, optional) - City for matching
requesterCountryCode (string, optional) - Your company's country code
requesterVatNumber (string, optional) - Your company's VAT number

Returns: Promise<ValidateVatApproxResponse>

const result = await client.validateVatApprox({
  countryCode: 'DE',
  vatNumber: '169838187',
  traderName: 'Google Germany',
  traderCity: 'Berlin'
});

console.log(result);
// {
//   countryCode: 'DE',
//   vatNumber: '169838187',
//   requestDate: '2025-12-30T10:00:00.000Z',
//   valid: true,
//   traderName: 'Google Germany GmbH',
//   traderStreet: 'ABC Street 123',
//   traderPostalCode: '10115',
//   traderCity: 'Berlin'
// }

`health()`

Check API health status (no authentication required).

Returns: Promise<HealthResponse>

const health = await client.health();
console.log(health); // { status: 'healthy' }

`getConfig()`

Get current configuration (API key is masked for security).

Returns: Config object

const config = client.getConfig();
console.log(config);
// {
//   apiKey: '***abc123',
//   baseUrl: 'https://vies-vat-validator.p.rapidapi.com',
//   timeout: 10000
// }

Error Handling

The client throws VatValidatorError for API errors:

import { VatValidatorError } from 'vat-id-validator';

try {
  const result = await client.validateVat({
    countryCode: 'DE',
    vatNumber: '123456789'
  });
} catch (error) {
  if (error instanceof VatValidatorError) {
    console.error('Status:', error.statusCode);
    console.error('Message:', error.message);
    console.error('Response:', error.response);
  }
}

Common Errors

401 Unauthorized - Invalid or missing API key
500 Internal Server Error - VIES service error or network issue
Network Error - Connection timeout or no response from server

TypeScript

Full TypeScript support with comprehensive type definitions:

import {
  VatValidatorClient,
  ValidateVatRequest,
  ValidateVatResponse,
  VatValidatorError
} from 'vat-id-validator';

const request: ValidateVatRequest = {
  countryCode: 'IT',
  vatNumber: '00743110157'
};

const response: ValidateVatResponse = await client.validateVat(request);

Examples

Basic Usage

import { VatValidatorClient } from 'vat-id-validator';

const client = new VatValidatorClient({
  apiKey: process.env.RAPIDAPI_KEY
});

// Validate Italian VAT
const result = await client.validateVat({
  countryCode: 'IT',
  vatNumber: '00743110157'
});

console.log(`Valid: ${result.valid}`);
console.log(`Company: ${result.name}`);

With Trader Details

// Validate with approximate matching
const result = await client.validateVatApprox({
  countryCode: 'DE',
  vatNumber: '169838187',
  traderName: 'Google Germany GmbH',
  traderCity: 'Berlin',
  requesterCountryCode: 'IT',
  requesterVatNumber: '00743110157'
});

Batch Validation

const vatNumbers = [
  { countryCode: 'IT', vatNumber: '00743110157' },
  { countryCode: 'DE', vatNumber: '169838187' },
  { countryCode: 'FR', vatNumber: '123456789' }
];

const results = await Promise.all(
  vatNumbers.map(vat => client.validateVat(vat))
);

results.forEach((result, index) => {
  console.log(`${vatNumbers[index].countryCode}${vatNumbers[index].vatNumber}: ${result.valid ? '✓' : '✗'}`);
});

Custom Endpoint for Testing

// Use a custom endpoint (e.g., for local testing)
const client = new VatValidatorClient({
  apiKey: 'test-key',
  baseUrl: 'http://localhost:8787'
});

Supported Countries

All EU member states are supported:

AT (Austria), BE (Belgium), BG (Bulgaria), CY (Cyprus)
CZ (Czech Republic), DE (Germany), DK (Denmark), EE (Estonia)
ES (Spain), FI (Finland), FR (France), GR (Greece)
HR (Croatia), HU (Hungary), IE (Ireland), IT (Italy)
LT (Lithuania), LU (Luxembourg), LV (Latvia), MT (Malta)
NL (Netherlands), PL (Poland), PT (Portugal), RO (Romania)
SE (Sweden), SI (Slovenia), SK (Slovakia)

License

MIT

Support

API Documentation: Full API Docs
Issues: GitHub Issues
RapidAPI: Get your API key at RapidAPI