### Installation Source: https://context7.com/viesapi/viesapi-javascript-client/llms.txt Install the VIES API client package using npm. ```APIDOC ## Installation Install the VIES API client package from NPM. ```bash npm install viesapi-client ``` ``` -------------------------------- ### Build and Install VIES API Client Source: https://github.com/viesapi/viesapi-javascript-client/blob/main/README.md Commands to clone the repository, install dependencies, and build TypeScript definitions for the VIES API client. ```bash git clone https://github.com/viesapi/viesapi-javascript-client.git cd viesapi-javascript-client npm install npm run build:types ``` -------------------------------- ### Install VIES API Client via NPM Source: https://github.com/viesapi/viesapi-javascript-client/blob/main/README.md Command to add the VIES API client as a dependency to your project using the npm package manager. ```bash npm install viesapi-client ``` -------------------------------- ### Local Polish NIP Number Validation with viesapi-javascript-client Source: https://context7.com/viesapi/viesapi-javascript-client/llms.txt This example demonstrates local validation and normalization of Polish NIP (Numer Identyfikacji Podatkowej) tax identification numbers using the VIESAPI.NIP utility from the viesapi-javascript-client. It includes checksum verification for provided NIP numbers. ```javascript const VIESAPI = require('viesapi-client'); // Validate Polish NIP numbers locally const nipNumbers = [ '7171642051', // Valid NIP '717-164-20-51', // Valid with dashes '717 164 20 51', // Valid with spaces '1234567890', // Invalid checksum 'invalid' // Invalid format ]; nipNumbers.forEach((nip) => { const isValid = VIESAPI.NIP.isValid(nip); const normalized = VIESAPI.NIP.normalize(nip); console.log(`${nip}: `); console.log(` Valid: ${isValid} `); console.log(` Normalized: ${normalized || 'N/A'}`); }); ``` -------------------------------- ### GET /vies/status Source: https://context7.com/viesapi/viesapi-javascript-client/llms.txt Checks the current availability status of the EU VIES system and individual member state services. ```APIDOC ## GET /vies/status ### Description Checks the current availability status of the EU VIES system and individual country services. Useful for determining if the VIES service is operational before making validation requests. ### Method GET ### Endpoint /vies/status ### Response #### Success Response (200) - **uid** (string) - Unique identifier for the status check request. - **available** (boolean) - Overall availability status of the VIES system. - **countries** (array) - List of individual country status objects. #### Response Example { "uid": "12345", "available": true, "countries": [ { "countryCode": "PL", "status": "Available" } ] } ``` -------------------------------- ### Validate EU VAT Number with getVIESData (JavaScript) Source: https://context7.com/viesapi/viesapi-javascript-client/llms.txt Retrieves VIES data for a specified EU VAT number, including validation status and trader information. The VAT number must include the 2-letter country prefix. This example shows usage with Promises and async/await. ```javascript const VIESAPI = require('viesapi-client'); const viesapi = new VIESAPI.VIESAPIClient(); // Validate a Polish VAT number viesapi.getVIESData('PL7171642051') .then((viesData) => { console.log('UID:', viesData.uid); console.log('Country Code:', viesData.countryCode); console.log('VAT Number:', viesData.vatNumber); console.log('Valid:', viesData.valid); console.log('Trader Name:', viesData.traderName); console.log('Trader Address:', viesData.traderAddress); console.log('Company Type:', viesData.traderCompanyType); console.log('Query Date:', viesData.date); console.log('Source:', viesData.source); }) .catch((error) => { console.error('Validation failed:', error.message); }); // Example with async/await async function validateVAT(vatNumber) { try { const result = await viesapi.getVIESData(vatNumber); return { isValid: result.valid, companyName: result.traderName, address: result.traderAddress }; } catch (error) { console.error('Error:', error.message); return null; } } ``` -------------------------------- ### Get Parsed Trader Information with getVIESDataParsed (JavaScript) Source: https://context7.com/viesapi/viesapi-javascript-client/llms.txt Retrieves VIES data with parsed trader name and address components. This method breaks down raw trader information into structured fields like name, legal form, street, city, and postal code. It handles cases where name or address components might not be available. ```javascript const VIESAPI = require('viesapi-client'); const viesapi = new VIESAPI.VIESAPIClient(); viesapi.getVIESDataParsed('DE123456789') .then((viesData) => { console.log('Valid:', viesData.valid); console.log('Trader Name:', viesData.traderName); // Parsed name components if (viesData.traderNameComponents) { console.log('Company Name:', viesData.traderNameComponents.name); console.log('Legal Form:', viesData.traderNameComponents.legalForm); console.log('Canonical Legal Form:', viesData.traderNameComponents.legalFormCanonicalName); console.log('Legal Form ID:', viesData.traderNameComponents.legalFormCanonicalId); } // Parsed address components if (viesData.traderAddressComponents) { console.log('Country:', viesData.traderAddressComponents.country); console.log('City:', viesData.traderAddressComponents.city); console.log('Postal Code:', viesData.traderAddressComponents.postalCode); console.log('Street:', viesData.traderAddressComponents.street); console.log('Street Number:', viesData.traderAddressComponents.streetNumber); console.log('House Number:', viesData.traderAddressComponents.houseNumber); } }) .catch((error) => { console.error('Error:', error.message); }); ``` -------------------------------- ### getVIESDataParsed - Get Parsed Trader Information Source: https://context7.com/viesapi/viesapi-javascript-client/llms.txt Retrieves VIES data with parsed trader name and address components, breaking down raw information into structured fields. ```APIDOC ## getVIESDataParsed - Get Parsed Trader Information Retrieves VIES data with parsed trader name and address components. This method breaks down the raw trader information into structured fields like name, legal form, street, city, and postal code. ```javascript const VIESAPI = require('viesapi-client'); const viesapi = new VIESAPI.VIESAPIClient(); viesapi.getVIESDataParsed('DE123456789') .then((viesData) => { console.log('Valid:', viesData.valid); console.log('Trader Name:', viesData.traderName); // Parsed name components if (viesData.traderNameComponents) { console.log('Company Name:', viesData.traderNameComponents.name); console.log('Legal Form:', viesData.traderNameComponents.legalForm); console.log('Canonical Legal Form:', viesData.traderNameComponents.legalFormCanonicalName); console.log('Legal Form ID:', viesData.traderNameComponents.legalFormCanonicalId); } // Parsed address components if (viesData.traderAddressComponents) { console.log('Country:', viesData.traderAddressComponents.country); console.log('City:', viesData.traderAddressComponents.city); console.log('Postal Code:', viesData.traderAddressComponents.postalCode); console.log('Street:', viesData.traderAddressComponents.street); console.log('Street Number:', viesData.traderAddressComponents.streetNumber); console.log('House Number:', viesData.traderAddressComponents.houseNumber); } }) .catch((error) => { console.error('Error:', error.message); }); ``` ``` -------------------------------- ### Create VIESAPIClient Instance (JavaScript) Source: https://context7.com/viesapi/viesapi-javascript-client/llms.txt Demonstrates how to create an instance of the VIESAPIClient. It shows how to initialize the client in test mode (without credentials) and production mode (with API credentials). Optionally, you can set a custom application identifier. ```javascript const VIESAPI = require('viesapi-client'); // Test mode client (uses test credentials automatically) const testClient = new VIESAPI.VIESAPIClient(); // Production mode client (requires API credentials) const productionClient = new VIESAPI.VIESAPIClient('your_api_id', 'your_api_key'); // Optional: Set custom application identifier for tracking productionClient.setApp('MyApplication/1.0'); ``` -------------------------------- ### Client Instance Creation Source: https://context7.com/viesapi/viesapi-javascript-client/llms.txt Create an instance of the VIESAPIClient for test or production mode. Production mode requires API credentials. ```APIDOC ## Creating a Client Instance Create a VIESAPIClient instance to interact with the VIES API service. Use without parameters for test mode, or provide your API credentials for production access. ```javascript const VIESAPI = require('viesapi-client'); // Test mode client (uses test credentials automatically) const testClient = new VIESAPI.VIESAPIClient(); // Production mode client (requires API credentials) const productionClient = new VIESAPI.VIESAPIClient('your_api_id', 'your_api_key'); // Optional: Set custom application identifier for tracking productionClient.setApp('MyApplication/1.0'); ``` ``` -------------------------------- ### Check VIES System Availability with viesapi-javascript-client Source: https://context7.com/viesapi/viesapi-javascript-client/llms.txt This snippet demonstrates how to check the current availability status of the EU VIES system and individual country services using the viesapi-javascript-client. It logs the overall system status and the status of each member state, and identifies any unavailable countries. ```javascript const VIESAPI = require('viesapi-client'); const viesapi = new VIESAPI.VIESAPIClient(); viesapi.getVIESStatus() .then((status) => { console.log('VIES System UID:', status.uid); console.log('VIES Available:', status.available); // Check individual country availability console.log('\nCountry Status:'); status.countries.forEach((country) => { const statusIcon = country.status === 'Available' ? '✓' : '✗'; console.log(` ${statusIcon} ${country.countryCode}: ${country.status}`); }); // Example: Find unavailable countries const unavailable = status.countries.filter(c => c.status !== 'Available'); if (unavailable.length > 0) { console.log('\nWarning: Some countries are currently unavailable:'); unavailable.forEach(c => console.log(` - ${c.countryCode}`)); } }) .catch((error) => { console.error('Failed to check VIES status:', error.message); }); ``` -------------------------------- ### Validate EU VAT Number using VIES API Client Source: https://context7.com/viesapi/viesapi-javascript-client/llms.txt Demonstrates how to import the VIES API client, perform local format validation using the EUVAT utility, and query the VIES API for official status. This approach ensures efficient validation by checking local formats before making network requests. ```javascript import { VIESAPIClient, EUVAT, NIP, Err } from 'viesapi-client'; // Create client instance const viesapi = new VIESAPIClient(); // Validate VAT number const vatNumber = 'PL7171642051'; // First validate locally if (EUVAT.isValid(vatNumber)) { // Then query VIES API const result = await viesapi.getVIESData(vatNumber); console.log(`${vatNumber} is ${result.valid ? 'valid' : 'invalid'}`); } else { console.log(`${vatNumber} has invalid format`); } ``` -------------------------------- ### Error Handling in viesapi-javascript-client Source: https://context7.com/viesapi/viesapi-javascript-client/llms.txt This snippet illustrates how to handle errors when using the viesapi-javascript-client. It shows how to retrieve the last error code and message from the client after a failed API request, and lists common error codes provided by the library. ```javascript const VIESAPI = require('viesapi-client'); const viesapi = new VIESAPI.VIESAPIClient(); viesapi.getVIESData('INVALID-VAT') .then((data) => { console.log('Validation successful:', data); }) .catch((error) => { // Get error details const errorCode = viesapi.getLastErrorCode(); const errorMessage = viesapi.getLastError(); console.error('Error Code:', errorCode); console.error('Error Message:', errorMessage); // Common error codes: // 204 - CLI_NIP: NIP is invalid // 205 - CLI_EUVAT: EU VAT ID is invalid // 209 - CLI_BATCH_SIZE: Batch size limit exceeded [3-99] // 22 - EUVAT_BAD: Invalid EU VAT number // 23 - VIES_SYNC: VIES synchronization error // 58 - VIES_TOO_MANY_REQ: Too many requests // 59 - VIES_UNAVAILABLE: VIES service unavailable }); // Available error constants in VIESAPI.Err: console.log('Error codes:', { CLI_CONNECT: VIESAPI.Err.CLI_CONNECT, // 201 CLI_RESPONSE: VIESAPI.Err.CLI_RESPONSE, // 202 CLI_NIP: VIESAPI.Err.CLI_NIP, // 204 CLI_EUVAT: VIESAPI.Err.CLI_EUVAT, // 205 CLI_EXCEPTION: VIESAPI.Err.CLI_EXCEPTION, // 206 CLI_INPUT: VIESAPI.Err.CLI_INPUT, // 208 CLI_BATCH_SIZE: VIESAPI.Err.CLI_BATCH_SIZE // 209 }); ``` -------------------------------- ### Submit Batch VAT Validation Request Source: https://context7.com/viesapi/viesapi-javascript-client/llms.txt Submits a list of 3-99 EU VAT numbers for asynchronous validation. Returns a token used to track the processing status, which typically takes 2-3 minutes. ```javascript const VIESAPI = require('viesapi-client'); const viesapi = new VIESAPI.VIESAPIClient(); const vatNumbers = [ 'PL7171642051', 'DK56314210', 'CZ7710043187', 'DE123456789', 'FR12345678901' ]; viesapi.getVIESDataAsync(vatNumbers) .then((token) => { console.log('Batch submitted successfully'); console.log('Batch token:', token); }) .catch((error) => { console.error('Batch submission failed:', error.message); }); ``` -------------------------------- ### Local EU VAT Number Validation with viesapi-javascript-client Source: https://context7.com/viesapi/viesapi-javascript-client/llms.txt This code snippet shows how to perform local validation and normalization of EU VAT numbers using the VIESAPI.EUVAT utility from the viesapi-javascript-client. It checks various VAT numbers against country-specific patterns without making external API calls. ```javascript const VIESAPI = require('viesapi-client'); // Validate EU VAT number format locally const vatNumbers = [ 'PL7171642051', // Poland 'DE123456789', // Germany 'FR12345678901', // France 'GB123456789', // Invalid (UK no longer in EU VIES) 'ATU12345678', // Austria 'invalid-number' // Invalid format ]; vatNumbers.forEach((vat) => { const isValid = VIESAPI.EUVAT.isValid(vat); const normalized = VIESAPI.EUVAT.normalize(vat); console.log(`${vat}: `); console.log(` Valid format: ${isValid} `); console.log(` Normalized: ${normalized || 'N/A'}`); }); // Supported country codes: // AT (Austria), BE (Belgium), BG (Bulgaria), CY (Cyprus), // CZ (Czech Republic), DE (Germany), DK (Denmark), EE (Estonia), // EL (Greece), ES (Spain), FI (Finland), FR (France), // 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), XI (Northern Ireland) ``` -------------------------------- ### Utility: EU VAT Validation Source: https://context7.com/viesapi/viesapi-javascript-client/llms.txt Local validation and normalization of EU VAT numbers without making API calls. ```APIDOC ## Utility: EU VAT Validation ### Description Validates the format of EU VAT numbers against country-specific patterns for all EU member states locally. ### Method N/A (Local Utility) ### Parameters #### Request Body - **vatNumber** (string) - The VAT number to validate. ### Response #### Success Response (200) - **isValid** (boolean) - Whether the format is valid. - **normalized** (string) - The cleaned/normalized VAT number. ``` -------------------------------- ### getVIESData - Validate EU VAT Number Source: https://context7.com/viesapi/viesapi-javascript-client/llms.txt Retrieves VIES data for a specified EU VAT number, including validation status and trader information. The VAT number must include the 2-letter country prefix. ```APIDOC ## getVIESData - Validate EU VAT Number Retrieves VIES data for a specified EU VAT number. Returns validation status and trader information directly from the VIES system. The VAT number must include the 2-letter country prefix (e.g., PL, DE, FR). ```javascript const VIESAPI = require('viesapi-client'); const viesapi = new VIESAPI.VIESAPIClient(); // Validate a Polish VAT number viesapi.getVIESData('PL7171642051') .then((viesData) => { console.log('UID:', viesData.uid); console.log('Country Code:', viesData.countryCode); console.log('VAT Number:', viesData.vatNumber); console.log('Valid:', viesData.valid); console.log('Trader Name:', viesData.traderName); console.log('Trader Address:', viesData.traderAddress); console.log('Company Type:', viesData.traderCompanyType); console.log('Query Date:', viesData.date); console.log('Source:', viesData.source); }) .catch((error) => { console.error('Validation failed:', error.message); }); // Example with async/await async function validateVAT(vatNumber) { try { const result = await viesapi.getVIESData(vatNumber); return { isValid: result.valid, companyName: result.traderName, address: result.traderAddress }; } catch (error) { console.error('Error:', error.message); return null; } } ``` ``` -------------------------------- ### Batch VAT Number Validation API Source: https://context7.com/viesapi/viesapi-javascript-client/llms.txt Submits a batch of VAT numbers (3-99) for asynchronous validation. Returns a token to track the batch status and retrieve results later. Processing typically takes 2-3 minutes. ```APIDOC ## POST /viesapi/getVIESDataAsync ### Description Uploads a batch of VAT numbers (3-99 numbers) for asynchronous processing. Returns a token that can be used to check status and retrieve results. Batch processing typically takes 2-3 minutes in production. ### Method POST ### Endpoint /viesapi/getVIESDataAsync ### Parameters #### Request Body - **vatNumbers** (array[string]) - Required - An array of EU VAT numbers to validate. Must contain between 3 and 99 numbers. ### Request Example ```json [ "PL7171642051", "DK56314210", "CZ7710043187", "DE123456789", "FR12345678901" ] ``` ### Response #### Success Response (200) - **token** (string) - A unique token representing the submitted batch job. #### Response Example ```json { "token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" } ``` ``` -------------------------------- ### Utility: Polish NIP Validation Source: https://context7.com/viesapi/viesapi-javascript-client/llms.txt Local validation and normalization of Polish NIP tax identification numbers using checksum verification. ```APIDOC ## Utility: Polish NIP Validation ### Description Validates and normalizes Polish NIP (Numer Identyfikacji Podatkowej) tax identification numbers using checksum verification. ### Method N/A (Local Utility) ### Parameters #### Request Body - **nip** (string) - The Polish NIP number to validate. ### Response #### Success Response (200) - **isValid** (boolean) - Whether the NIP checksum is valid. - **normalized** (string) - The NIP number formatted without spaces or dashes. ``` -------------------------------- ### Retrieve API Account Status Source: https://context7.com/viesapi/viesapi-javascript-client/llms.txt Fetches detailed information about the authenticated VIES API account, including billing plans, usage statistics, and enabled features. ```javascript const VIESAPI = require('viesapi-client'); const viesapi = new VIESAPI.VIESAPIClient('your_api_id', 'your_api_key'); viesapi.getAccountStatus() .then((account) => { console.log('Account UID:', account.uid); console.log('Plan Name:', account.billingPlanName); console.log('Monthly Limit:', account.limit); console.log('Total Requests:', account.totalCount); }) .catch((error) => { console.error('Failed to get account status:', error.message); }); ``` -------------------------------- ### Retrieve Batch Validation Results Source: https://context7.com/viesapi/viesapi-javascript-client/llms.txt Polls the API using a batch token to check if validation results are ready. Once available, it returns the status of each VAT number and any associated errors. ```javascript const VIESAPI = require('viesapi-client'); const viesapi = new VIESAPI.VIESAPIClient(); const batchToken = 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'; function checkBatchResults(token) { const checkInterval = setInterval(() => { viesapi.getVIESDataAsyncResult(token) .then((batchResult) => { console.log('Batch UID:', batchResult.uid); console.log('Validated numbers:', batchResult.numbers.length); batchResult.numbers.forEach((viesData) => { console.log(`${viesData.countryCode}${viesData.vatNumber}: ${viesData.valid ? 'VALID' : 'INVALID'}`); }); clearInterval(checkInterval); }) .catch((error) => { console.log('Waiting for results...', error.message); }); }, 10000); } checkBatchResults(batchToken); ``` -------------------------------- ### Account Status API Source: https://context7.com/viesapi/viesapi-javascript-client/llms.txt Retrieves detailed information about your VIES API account, including your current billing plan, usage limits, remaining quota, and enabled features. ```APIDOC ## GET /viesapi/getAccountStatus ### Description Retrieves information about your VIES API account including billing plan, usage limits, remaining quota, and enabled features. ### Method GET ### Endpoint /viesapi/getAccountStatus ### Parameters No parameters required. ### Response #### Success Response (200) - **uid** (string) - The unique identifier for your account. - **type** (string) - The type of account (e.g., 'free', 'paid'). - **validTo** (string) - The expiration date of the account or subscription. - **billingPlanName** (string) - The name of the current billing plan. - **subscriptionPrice** (number) - The price of the subscription. - **itemPrice** (number) - The price per API request. - **limit** (integer) - The monthly usage limit for the account. - **requestDelay** (integer) - The recommended delay in milliseconds between requests. - **domainLimit** (integer) - The limit on the number of domains associated with the account. - **overPlanAllowed** (boolean) - Whether exceeding the plan limit is allowed. - **funcGetVIESData** (boolean) - Whether the VIES data validation feature is enabled. - **funcGetVIESDataParsed** (boolean) - Whether the parsed VIES data feature is enabled. - **excelAddIn** (boolean) - Whether the Excel Add-in feature is enabled. - **app** (boolean) - Whether the Desktop App feature is enabled. - **cli** (boolean) - Whether the CLI Tool feature is enabled. - **stats** (boolean) - Whether the Statistics feature is enabled. - **monitor** (boolean) - Whether the Monitoring feature is enabled. - **viesDataCount** (integer) - The number of VIES data requests made this month. - **viesDataParsedCount** (integer) - The number of parsed VIES data requests made this month. - **totalCount** (integer) - The total number of API requests made this month. #### Response Example ```json { "uid": "acc-xxxxxxxxxxxxxxxxx", "type": "paid", "validTo": "2024-12-31T23:59:59Z", "billingPlanName": "Pro Plan", "subscriptionPrice": 99.99, "itemPrice": 0.01, "limit": 10000, "requestDelay": 50, "domainLimit": 10, "overPlanAllowed": true, "funcGetVIESData": true, "funcGetVIESDataParsed": true, "excelAddIn": false, "app": true, "cli": true, "stats": true, "monitor": true, "viesDataCount": 1500, "viesDataParsedCount": 500, "totalCount": 2000 } ``` ``` -------------------------------- ### Retrieve Batch Results API Source: https://context7.com/viesapi/viesapi-javascript-client/llms.txt Checks the status of a batch VAT number validation request and retrieves the results once they are ready. This method should be called periodically using the token obtained from the batch submission. ```APIDOC ## GET /viesapi/getVIESDataAsyncResult ### Description Checks the status of a batch request and downloads results when ready. Call this method periodically with the token received from getVIESDataAsync until results are available. Recommended polling interval is 10 seconds. ### Method GET ### Endpoint /viesapi/getVIESDataAsyncResult ### Parameters #### Query Parameters - **token** (string) - Required - The batch token received from the `getVIESDataAsync` call. ### Response #### Success Response (200) - **uid** (string) - The unique identifier for the batch job. - **numbers** (array[object]) - An array of validated VAT numbers. - **countryCode** (string) - The country code of the VAT number. - **vatNumber** (string) - The validated VAT number. - **valid** (boolean) - Indicates if the VAT number is valid. - **traderName** (string) - The name of the trader associated with the VAT number. - **traderAddress** (string) - The address of the trader. - **errors** (array[object]) - An array of errors encountered during validation. - **countryCode** (string) - The country code of the VAT number. - **vatNumber** (string) - The VAT number that caused an error. - **error** (string) - A description of the error. #### Response Example ```json { "uid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "numbers": [ { "countryCode": "PL", "vatNumber": "7171642051", "valid": true, "traderName": "VIESAPI SP. Z O.O.", "traderAddress": "ul. XYZ 1, 00-000 Warszawa" } ], "errors": [ { "countryCode": "DK", "vatNumber": "56314210", "error": "INVALID_INPUT" } ] } ``` ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.