npm package: @salespark/validate-vat-eu
Description: Validate EU VAT numbers using the official VIES SOAP API
Author: SalesPark
Latest version: 1.0.9

> **npm registry notice:** On **2 May 2026** (timezone **Europe/Lisbon**), this package will no longer be **publicly** installable from the npm registry and will become **restricted to the SalesPark npm organization**. Until then, already-published versions remain public. **No further public releases** or support for external consumers is planned — if you depend on this package, **fork** before that date.

# SalesPark Validade Vat EU - Documentation

## @salespark/validate-vat-eu

Modern TypeScript module to validate European VAT numbers using the official [VIES](https://ec.europa.eu/taxation_customs/vies/) SOAP API.

No dependencies beyond `fast-xml-parser` and native Node.js HTTPS. Fully typed, promise-based, and production-ready.

---

## 📦 Installation

```bash
yarn add @salespark/validate-vat-eu

# or

npm install @salespark/validate-vat-eu
```

---

## 🚀 Usage

```ts
import { validateVatEU } from "@salespark/validate-vat-eu";

const result = await validateVatEU("PT", "502011378");

console.log(result);
/*
{
  countryCode: 'PT',
  vatNumber: '502011378',
  valid: true,
  name: 'SIBS FORWARD PAYMENT SOLUTIONS SA',
  address: 'RUA SOUSA MARTINS, 1\n1050-094 LISBOA',
  requestDate: '2025-06-28+02:00'
}
*/
```

---

## 🧾 API

### `validateVatEU(countryCode: string, vatNumber: string, timeoutMs?: number): Promise<VatCheckResult>`

Validates a European VAT number using the official VIES SOAP API.

---

#### Parameters

| Parameter     | Type     | Description                                                               |
| ------------- | -------- | ------------------------------------------------------------------------- |
| `countryCode` | `string` | Two-letter ISO 3166-1 alpha-2 country code (e.g. `'PT'`, `'DE'`)          |
| `vatNumber`   | `string` | VAT number without the country prefix (digits or alphanumeric, no spaces) |
| `timeoutMs`   | `number` | Optional request timeout in milliseconds (default: `7000`)                |

---

#### Returns

A `Promise` that resolves to the following object:

```ts
interface VatCheckResult {
  countryCode: string;
  vatNumber: string;
  valid: boolean;
  name: string;
  address: string;
  requestDate: string;
}
```

---

## 📝 Notes

- Only VAT numbers registered for intra-community operations will return `valid: true`.
- Some VAT numbers that are valid at national level might not be registered in the VIES system.
- VIES service availability may vary — it's not guaranteed to be 100% online.
- This package uses the official SOAP endpoint:  
  `https://ec.europa.eu/taxation_customs/vies/services/checkVatService`

---

## 🧪 Testing

You can test with a known valid VAT number:

```ts
validateVatEU("PT", "502011378"); // Should return valid: true
```

---

### 🛠 Built With

- [Node.js `https`](https://nodejs.org/api/https.html) – native module for secure HTTP requests
- [fast-xml-parser](https://www.npmjs.com/package/fast-xml-parser) – lightweight, performant XML parsing
- [TypeScript](https://www.typescriptlang.org/) – strict typing and developer tooling

---

### 🔒 Internal Usage Notice

This package is primarily designed and maintained for internal use within the SalesPark ecosystem.
While it can technically be used in other Node.js/Mongoose projects, no official support or guarantees are provided outside of SalesPark-managed projects.

All code follows the same engineering standards applied across the SalesPark platform, ensuring consistency, reliability, and long-term maintainability of our internal systems.

⚡ Note: This package is most efficient and works best when used together with other official SalesPark packages, where interoperability and optimizations are fully leveraged.

Disclaimer: This software is provided “as is”, without warranties of any kind, express or implied. SalesPark shall not be held liable for any issues, damages, or losses arising from its use outside the intended SalesPark environment.

Organization packages: https://www.npmjs.com/org/salespark

---

## 📄 License

MIT © [SalesPark](https://salespark.io)

---

_Document version: 3_  
_Last update: 04-04-2026_