Metadata-Version: 2.4
Name: taxvett
Version: 0.1.0
Summary: Official TaxVett API client for Python
Author: TaxVett
License-Expression: MIT
Project-URL: Homepage, https://taxvett.com
Project-URL: Documentation, https://api.taxvett.com/docs
Keywords: vat,vat-validation,vat-number,vies,eu-vat,uk-vat,abn,tax-id,tax-number
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Office/Business :: Financial :: Accounting
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27
Requires-Dist: typing-extensions>=4.0
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"
Dynamic: license-file

# TaxVett Python SDK

Python client for the [TaxVett API](https://api.taxvett.com) — validates VAT/tax registration numbers across EU, UK, Australia, Norway, and Singapore.

## Install

```bash
pip install taxvett
```


## Quick start

### Sync

```python
from taxvett import TaxVett

client = TaxVett(api_key="tv_...")

result = client.validate("SE556677881301")
print(result["valid"])        # True
print(result["company_name"]) # "Acme AB"
```

### Async

```python
import asyncio
from taxvett import AsyncTaxVett

async def main():
    client = AsyncTaxVett(api_key="tv_...")
    result = await client.validate("SE556677881301")
    print(result["valid"])

asyncio.run(main())
```

## Methods

### `validate(number, country=None)`

Validate a single tax number. `country` is optional — the API will auto-detect it.

```python
result = client.validate("GB123456789", country="GB")
# result: ValidateResponse
```

### `validate_batch(numbers)`

Validate multiple numbers in one request.

```python
from taxvett import BatchItem

numbers: list[BatchItem] = [
    {"number": "SE556677881301"},
    {"number": "GB123456789", "country": "GB"},
]
response = client.validate_batch(numbers)
print(response["count"])    # 2
print(response["results"])  # list[ValidateResponse]
```

### `get_stats()`

Retrieve usage statistics for your API key.

```python
stats = client.get_stats()
print(stats["total_requests"])
print(stats["requests_by_country"])
print(stats["requests_per_day"])
```

## Error handling

```python
from taxvett import TaxVett, TaxVettError

client = TaxVett(api_key="tv_...")

try:
    result = client.validate("INVALID")
except TaxVettError as e:
    print(e.status)  # e.g. 401, 400, 500
    print(e.body)    # raw response body as dict
```

## Custom base URL

```python
client = TaxVett(api_key="tv_...", base_url="https://staging.taxvett.com")
```
