{"id":15894,"library":"viesapi-client","title":"VIES API Client for JavaScript","description":"The `viesapi-client` is the official JavaScript library for interacting with the VIES API, which provides services for querying the European Union's VAT Information Exchange System. This client enables developers to validate EU VAT numbers, retrieve company details, and check the registration status of businesses across all EU member states. Currently at version 1.3.3, the library is actively maintained with regular updates and ships with full TypeScript type definitions. It supports both Node.js and browser environments, offering built-in authentication, request signing, and comprehensive error handling. Key differentiators include its ability to perform both synchronous single-number lookups and asynchronous batch processing, along with utility functions for local validation of EU VAT and Polish NIP numbers prior to making API requests. The library handles the intricacies of communicating with the VIES system, simplifying the process for developers.","status":"active","version":"1.3.3","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","viesapi","api","vat","nip","eu","vies","validator","typescript"],"install":[{"cmd":"npm install viesapi-client","lang":"bash","label":"npm"},{"cmd":"yarn add viesapi-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add viesapi-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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`.","wrong":"const VIESAPIClient = require('viesapi-client');","symbol":"VIESAPIClient","correct":"import { VIESAPIClient } from 'viesapi-client';"},{"note":"A utility object providing static methods for local validation of EU VAT numbers (e.g., `EUVAT.isValid('PL...')`).","wrong":"import EUVAT from 'viesapi-client';","symbol":"EUVAT","correct":"import { EUVAT } from 'viesapi-client';"},{"note":"Type import for configuration options when instantiating the client, useful for TypeScript projects. The library ships with comprehensive types.","symbol":"VIESAPIClientOptions","correct":"import type { VIESAPIClientOptions } from 'viesapi-client';"}],"quickstart":{"code":"import { VIESAPIClient, EUVAT } from 'viesapi-client';\n\nconst API_ID = process.env.VIESAPI_ID ?? '';\nconst API_KEY = process.env.VIESAPI_KEY ?? '';\n\nasync function validateVatNumber(vatNumber: string) {\n  let client: VIESAPIClient;\n\n  // Instantiate client for test mode if no credentials are provided\n  // The test environment has specific VAT numbers it will respond to successfully.\n  if (!API_ID || !API_KEY) {\n    console.warn('VIESAPI_ID or VIESAPI_KEY not set. Using test environment.');\n    client = new VIESAPIClient(); // Test mode constructor\n  } else {\n    client = new VIESAPIClient(API_ID, API_KEY); // Production mode\n  }\n\n  // Optionally set a custom application identifier for tracking\n  client.setApp('MyAwesomeApp/1.0');\n\n  // Local validation first for basic format checks\n  if (!EUVAT.isValid(vatNumber)) {\n    console.error(`Error: Invalid EU VAT number format for ${vatNumber}.`)\n    return;\n  }\n\n  try {\n    console.log(`Checking VAT number: ${vatNumber}...`);\n    const viesData = await client.getVIESData(vatNumber);\n\n    if (viesData.valid) {\n      console.log(`VAT number ${vatNumber} is VALID.`);\n      console.log(`Company Name: ${viesData.traderName}`);\n      console.log(`Address: ${viesData.traderAddress}`);\n    } else {\n      console.log(`VAT number ${vatNumber} is INVALID or not found.`);\n      console.log(`UID: ${viesData.uid}`); // Unique ID of the query\n    }\n  } catch (error: any) {\n    console.error(`Failed to validate VAT number ${vatNumber}:`, error.message);\n    if (error.status === 401) {\n      console.error('Check your API ID and Key. They might be incorrect or missing for production environment.');\n    }\n  }\n}\n\n// Example usage with a test VAT number for the VIES API test environment\nvalidateVatNumber('PL7171642051');\n// Example with an invalid VAT number (will fail local validation)\n// validateVatNumber('DE12345');\n// Example for a production key (replace with actual values in .env or similar)\n// validateVatNumber('FR10402571889');","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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'.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always ensure the VAT number string includes the correct two-letter country code prefix, e.g., `client.getVIESData('PL7171642051')`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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).","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.","error":"Error: Request failed with status code 401"},{"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';`.","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.","error":"TypeError: VIESAPIClient is not a constructor"},{"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`.","cause":"The client could not reach the VIES API server due to network connectivity issues, DNS problems, or firewall restrictions.","error":"Error: Network Error (or similar FetchError message)"},{"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.","cause":"The provided VAT number does not conform to the expected format, typically missing the 2-letter country code prefix.","error":"Error: Invalid VAT number format (or similar validation error from local utilities)"}],"ecosystem":"npm"}