> ## 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.

# Endpoint de cálculo de IVA

> O endpoint `calculate` permite cálculos precisos de IVA para preços em conformidade, tendo em conta regulamentos específicos por país, valores de transação e categorias de produto opcionais.

## Primeiros passos

### URL base

```
https://vat.cleariflow.com/v1/calculate/
```

### Endpoint de cálculo

O endpoint `calculate` requer a sua chave API única, o país e o preço que pretende verificar:

```
https://vat.cleariflow.com/v1/calculate/
? api_key = YOUR_UNIQUE_API_KEY
& amount = 175  
& country_code = DE
& category = standard
```

Este pedido bem-sucedido devolve resultados abrangentes de cálculo de IVA, incluindo taxas, montantes e informações do país:

<ResponseExample>
  ```json theme={"system"}
  {
      "amount_excluding_vat": "175.00",
      "amount_including_vat": "208.25",
      "country": {
          "code": "DE",
          "name": "Germany"
      },
      "vat_amount": "33.25",
      "vat_category": "standard",
      "vat_rate": "0.190"
  }
  ```
</ResponseExample>

### Parâmetros de pedido

<ParamField query="api_key" type="String" required>
  A sua chave API única. Note que cada utilizador tem chaves API únicas para cada API Cleariflow — a sua chave da API de validação de IVA não funcionará para a API de geolocalização IP, por exemplo.
</ParamField>

<ParamField query="amount" type="String" required>
  O montante para o qual pretende obter o valor de IVA ou a partir do qual pretende calculá-lo.
</ParamField>

<ParamField query="country_code" type="String" required>
  O código ISO 3166-1 alpha-2 de duas letras do país onde a transação ocorre.
</ParamField>

<ParamField query="category" type="String" required>
  A categoria de IVA a utilizar no cálculo. Utilize "standard" para a taxa padrão de IVA, ou categorias específicas como "e-books", "audiobooks", etc. para taxas reduzidas.
</ParamField>

<ParamField query="is_vat_incl" type="Boolean">
  Se o montante já inclui IVA e pretende fazer o cálculo inverso para separar o montante e o IVA, defina este parâmetro como `true`. Se este parâmetro não for explicitamente incluído, o valor predefinido é `false`.
</ParamField>

### Parâmetros de resposta

A resposta da API é devolvida num [formato JSON](https://www.json.org/json-en.html) universal e leve.

<ResponseField name="amount_excluding_vat" type="String">
  O montante sem IVA.
</ResponseField>

<ResponseField name="amount_including_vat" type="String">
  A soma do montante base e do IVA, ou seja, `amount_excluding_vat` + `vat_amount`.
</ResponseField>

<ResponseField name="vat_amount" type="String">
  O montante de IVA calculado.
</ResponseField>

<ResponseField name="vat_category" type="String">
  A categoria da compra, utilizada para determinar se se qualifica para uma taxa reduzida. Consulte abaixo a lista de categorias suportadas.
</ResponseField>

<ResponseField name="vat_rate" type="String">
  A taxa de IVA como string decimal (por exemplo, "0.190" para 19%).
</ResponseField>

<ResponseField name="country" type="Object">
  Objeto que contém informações do país.
</ResponseField>

<ResponseField name="country.code" type="String">
  O código ISO 3166-1 alpha-2 de duas letras do país onde a transação ocorre.
</ResponseField>

<ResponseField name="country.name" type="String">
  O nome do país a partir do qual o IVA está a ser calculado.
</ResponseField>