> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bunny.build/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /vat-validator

> Valide números de IVA europeus e recupere a razão social e o endereço registrado da empresa.

## Endpoint

```
POST https://api.bunny.build/api/v1/vat-validator
```

## Autenticação

| Header         | Obrigatório | Valor                        |
| -------------- | ----------- | ---------------------------- |
| `X-API-Key`    | Sim         | Sua chave de API (`bun_...`) |
| `Content-Type` | Sim         | `application/json`           |

## Visão geral

Valide números de IVA da União Europeia no banco de dados oficial do VIES (Sistema de Troca de Informações sobre IVA) e recupere a razão social e o endereço registrado da empresa. Use esta API para automatizar verificações de conformidade fiscal B2B e manter seus dados de faturamento precisos.

## Casos de uso

* Verificar números de IVA de clientes durante o checkout B2B
* Preencher automaticamente razão social e endereço a partir de um número de IVA
* Condicionar a isenção de imposto à confirmação de IVA válido
* Detectar números de IVA fraudulentos ou expirados

## Detalhes

Cobre todos os estados-membros da UE. O campo `vat` deve incluir o prefixo de dois letras do país (ex.: `DE123456789`, `FR12345678901`). A validação consulta o serviço VIES em tempo real; eventuais timeouts do sistema VIES são propagados como erros.

## Corpo da requisição

| Campo | Tipo   | Obrigatório | Descrição                                                    |
| ----- | ------ | ----------- | ------------------------------------------------------------ |
| `vat` | string | Sim         | Número de IVA incluindo prefixo do país (ex.: `DE123456789`) |

### Exemplo

```json theme={null}
{
  "vat": "DE123456789"
}
```

## Resposta

### 200 OK

| Campo     | Tipo    | Descrição                                  |
| --------- | ------- | ------------------------------------------ |
| `valid`   | boolean | Se o número de IVA está registrado e ativo |
| `vat`     | string  | Número de IVA normalizado                  |
| `country` | string  | Código de país ISO                         |
| `name`    | string  | Razão social registrada                    |
| `address` | string  | Endereço registrado da empresa             |

**Exemplo**

```json theme={null}
{
  "valid": true,
  "vat": "DE123456789",
  "country": "DE",
  "name": "Example GmbH",
  "address": "Musterstraße 1, 10115 Berlin"
}
```

### 401 Unauthorized

```json theme={null}
{
  "detail": "Missing API key. Include X-API-Key header."
}
```

### 402 Payment Required

```json theme={null}
{
  "detail": "Monthly quota exceeded. Upgrade your plan."
}
```

### 422 Unprocessable Entity

```json theme={null}
{
  "detail": "Invalid VAT number format"
}
```

### 429 Too Many Requests

```json theme={null}
{
  "detail": "Rate limit exceeded. Try again in 60 seconds."
}
```

## Exemplo cURL

```bash theme={null}
curl -X POST https://api.bunny.build/api/v1/vat-validator \
  -H "X-API-Key: bun_sua_chave_api" \
  -H "Content-Type: application/json" \
  -d '{"vat": "DE123456789"}'
```