VIES API Client for JavaScript

Common errors

• Error: Request failed with status code 401

  cause This typically indicates an authentication failure; your API ID or Key is missing, incorrect, or your account is not active for the production environment.
  fix Ensure you have registered on viesapi.eu and are using the correct API ID and Key for the production client. Double-check for typos and ensure the keys are for the correct environment (test vs. production).

• TypeError: VIESAPIClient is not a constructor

  cause This error often occurs when attempting to use a CommonJS `require` statement with a library primarily designed for ES Modules, or when trying to directly `require` a named export incorrectly.
  fix For CommonJS, use `const { VIESAPIClient } = require('viesapi-client');` or `const VIESAPI = require('viesapi-client'); const client = new VIESAPI.VIESAPIClient();`. For ES Modules, ensure you are using `import { VIESAPIClient } from 'viesapi-client';`.

• Error: Network Error (or similar FetchError message)

  cause The client could not reach the VIES API server due to network connectivity issues, DNS problems, or firewall restrictions.
  fix Verify your internet connection. Check if the VIES API service is online. If running in a Node.js environment, ensure there are no proxy or firewall settings blocking outbound connections to `viesapi.eu`.

• Error: Invalid VAT number format (or similar validation error from local utilities)

  cause The provided VAT number does not conform to the expected format, typically missing the 2-letter country code prefix.
  fix Prepend the correct two-letter country code to the VAT number (e.g., 'DE123456789' for Germany). Utilize `EUVAT.isValid()` for client-side format validation before making API calls.

Warnings

• gotcha For production usage, an API ID and Key are mandatory. These credentials are generated after registration on the viesapi.eu portal. Attempts to use the production API without valid credentials will result in authentication failures.
  Fix: Register for an account on viesapi.eu to obtain your API ID and Key. Pass them as arguments to the `VIESAPIClient` constructor: `new VIESAPIClient(apiId, apiKey);`. Store credentials securely, e.g., using environment variables.
• gotcha The VIES API offers a test environment that does not require registration or credentials, but it only accepts a predefined set of EU VAT numbers for testing. Attempting to validate other numbers in the test environment may yield unexpected results.
  Fix: Use the parameter-less constructor `new VIESAPIClient()` for the test environment. Refer to the VIES API documentation for the list of valid test VAT numbers, such as 'PL7171642051' or 'DE327990207'.
• gotcha EU VAT numbers must include the 2-letter country prefix (e.g., 'PL' for Poland, 'DE' for Germany). Omitting or providing an incorrect prefix will result in validation errors. The client provides local `EUVAT.isValid()` utility for pre-checking.
  Fix: Always ensure the VAT number string includes the correct two-letter country code prefix, e.g., `client.getVIESData('PL7171642051')`.
• gotcha Like most external APIs, the VIES API has rate limits and usage policies. Excessive requests within a short period may lead to temporary blocking or error responses.
  Fix: Implement proper error handling for rate limit responses (e.g., HTTP 429 Too Many Requests) and consider implementing a back-off strategy or caching successful results. Review your service plan details for specific rate limits.

Install

• npm install viesapi-client npm
• yarn add viesapi-client yarn
• pnpm add viesapi-client pnpm

Imports

• VIESAPIClient
  wrong:

  const VIESAPIClient = require('viesapi-client');

  correct:

  import { VIESAPIClient } from 'viesapi-client';

  The primary class for interacting with the VIES API. For CommonJS, destructure from `require('viesapi-client')` as `const { VIESAPIClient } = require('viesapi-client');` or access via `VIESAPI.VIESAPIClient`.
• EUVAT
  wrong:

  import EUVAT from 'viesapi-client';

  correct:

  import { EUVAT } from 'viesapi-client';

  A utility object providing static methods for local validation of EU VAT numbers (e.g., `EUVAT.isValid('PL...')`).
• VIESAPIClientOptions

  import type { VIESAPIClientOptions } from 'viesapi-client';

  Type import for configuration options when instantiating the client, useful for TypeScript projects. The library ships with comprehensive types.

Quickstart

This quickstart demonstrates how to instantiate the `VIESAPIClient` for both test and production environments, perform local VAT number validation, and then query the VIES API to check the status of an EU VAT number, including basic error handling.

import { VIESAPIClient, EUVAT } from 'viesapi-client';

const API_ID = process.env.VIESAPI_ID ?? '';
const API_KEY = process.env.VIESAPI_KEY ?? '';

async function validateVatNumber(vatNumber: string) {
  let client: VIESAPIClient;

  // Instantiate client for test mode if no credentials are provided
  // The test environment has specific VAT numbers it will respond to successfully.
  if (!API_ID || !API_KEY) {
    console.warn('VIESAPI_ID or VIESAPI_KEY not set. Using test environment.');
    client = new VIESAPIClient(); // Test mode constructor
  } else {
    client = new VIESAPIClient(API_ID, API_KEY); // Production mode
  }

  // Optionally set a custom application identifier for tracking
  client.setApp('MyAwesomeApp/1.0');

  // Local validation first for basic format checks
  if (!EUVAT.isValid(vatNumber)) {
    console.error(`Error: Invalid EU VAT number format for ${vatNumber}.`)
    return;
  }

  try {
    console.log(`Checking VAT number: ${vatNumber}...`);
    const viesData = await client.getVIESData(vatNumber);

    if (viesData.valid) {
      console.log(`VAT number ${vatNumber} is VALID.`);
      console.log(`Company Name: ${viesData.traderName}`);
      console.log(`Address: ${viesData.traderAddress}`);
    } else {
      console.log(`VAT number ${vatNumber} is INVALID or not found.`);
      console.log(`UID: ${viesData.uid}`); // Unique ID of the query
    }
  } catch (error: any) {
    console.error(`Failed to validate VAT number ${vatNumber}:`, error.message);
    if (error.status === 401) {
      console.error('Check your API ID and Key. They might be incorrect or missing for production environment.');
    }
  }
}

// Example usage with a test VAT number for the VIES API test environment
validateVatNumber('PL7171642051');
// Example with an invalid VAT number (will fail local validation)
// validateVatNumber('DE12345');
// Example for a production key (replace with actual values in .env or similar)
// validateVatNumber('FR10402571889');