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

# Introdução

> A API de validação de IVA da Cleariflow oferece soluções abrangentes de conformidade fiscal através de uma interface RESTful JSON moderna — para validação e cálculo fluidos em negócios nacionais e internacionais.

## Primeiros passos

<Card title="Endpoint de validação de IVA" icon="tag" href="vat/validate">
  Verifique a autenticidade do número de IVA e obtenha informações abrangentes da empresa, incluindo país, nome comercial, morada e detalhes de registo.
</Card>

<Card title="Endpoint de cálculo de IVA" icon="tags" href="vat/calculate">
  Calcule preços em conformidade com o IVA com base em regulamentos específicos por país, tipo de compra e valor da transação para cálculos financeiros precisos.
</Card>

<Card title="Endpoint de categorias de IVA" icon="globe" href="vat/categories">
  Aceda às taxas de IVA atuais e categorias fiscais para países específicos para garantir conformidade com os regulamentos fiscais locais.
</Card>

### Arquitetura REST

A API de validação de IVA segue os princípios REST, utilizando URLs previsíveis e orientadas a recursos e códigos de estado HTTP padrão para integração fluida e tratamento de erros. Todos os endpoints da API devem terminar com uma barra final (/) e suportam apenas pedidos GET.

### Segurança HTTPS

Todas as comunicações da API são protegidas com protocolos de encriptação TLS 1.2 ou superior para garantir a integridade e privacidade dos dados.

### Versionamento da API

A API de validação de IVA mantém compatibilidade retroativa através de versionamento, operando atualmente na Versão 1 com melhorias futuras planeadas.

### Autenticação

A sua chave API serve como credencial exclusiva para aceder à API de validação de IVA. Cada serviço Cleariflow requer uma chave única, garantindo acesso seguro e isolado entre diferentes APIs. A API implementa limitação de taxa para garantir utilização justa entre todos os utilizadores.

## Códigos de resposta e erro

Quando os pedidos falham, a API devolve respostas de erro JSON estruturadas com códigos e descrições específicos para resolução eficaz de problemas.

| Code | Type                  | Detalhes                                                                                                                                                                  |
| ---- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200  | OK                    | Tudo funcionou como esperado.                                                                                                                                             |
| 400  | Bad request           | Pedido inválido.                                                                                                                                                          |
| 401  | Unauthorized          | O pedido não foi aceite — normalmente devido a uma chave API em falta ou incorreta.                                                                                       |
| 422  | Quota reached         | O pedido foi abortado devido a créditos API insuficientes (planos gratuitos).                                                                                             |
| 429  | Too many requests     | O pedido foi abortado porque foi atingido o número de pedidos permitidos por segundo. Isto acontece em planos gratuitos, pois os pedidos estão limitados a 1 por segundo. |
| 500  | Internal server error | O pedido não pôde ser concluído devido a um erro no servidor.                                                                                                             |
| 503  | Service unavailable   | O servidor estava indisponível.                                                                                                                                           |

## Códigos de país

Abaixo está a lista de países suportados pelos endpoints de IVA

| Código do país | Nome do país    |
| -------------- | --------------- |
| AT             | Austria         |
| BE             | Belgium         |
| BG             | Bulgaria        |
| CY             | Cyprus          |
| CZ             | Czech Republic  |
| DE             | Germany         |
| DK             | Denmark         |
| EE             | Estonia         |
| FI             | Finland         |
| FR             | France          |
| GB             | United Kingdom  |
| GR             | Greece          |
| HR             | Croatia         |
| HU             | Hungary         |
| IE             | Ireland         |
| IT             | Italy           |
| LT             | Lithuania       |
| LU             | Luxembourg      |
| LV             | Latvia          |
| MT             | Malta           |
| NL             | The Netherlands |
| PL             | Poland          |
| PT             | Portugal        |
| RO             | Romania         |
| SE             | Sweden          |
| SI             | Slovenia        |
| SK             | Slovakia        |