Registry / http-networking / viesapi-client

viesapi-client

JSON →
library1.3.3jsnpmunverified

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.

npm install viesapi-client
INSTALL
IMPORT
SIG · VIESAPI-CLIENT
V
viesapi-client
http-networkingjavascriptv1.3.3
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

VIESAPIClient
import { VIESAPIClient } from 'viesapi-client';
const VIESAPIClient = require('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
import { EUVAT } from 'viesapi-client';
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.

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');
Debug
Known issues
gotchaFor 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.
affects: >=1.0.0
gotchaThe 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'.
affects: >=1.0.0
gotchaEU 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')`.
affects: >=1.0.0
gotchaLike 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.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Request failed with status code 401
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
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)
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)
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.
Upgrade
Version history
1.3.3latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
28 hits · last 30 days
node
24
OpenAI (training)
1
Resources
viesapi-client — npm install viesapi-client · libregistry