Atura
Atura

API Atura

Cálculo de IVA

Fiscal

Calcula automaticamente o IVA e outros impostos portugueses com suporte para variações regionais dos Açores e Madeira.

Documentação em Desenvolvimento

Esta documentação está ainda em desenvolvimento ativo. Algumas secções podem estar incompletas ou sujeitas a alterações. Para questões específicas, contacta o nosso suporte técnico.

Sistema de Cálculo Fiscal

A API Atura calcula automaticamente todos os impostos portugueses, incluindo IVA com taxas regionais para os Açores e Madeira, garantindo conformidade total com a legislação fiscal.

Automático

Cálculo instantâneo e preciso

Regional

Suporte para Açores e Madeira

Conforme

Atualizado com legislação

Calcular Impostos

POST/v1/tax/calculate

Calcula impostos para uma lista de itens, considerando a localização geográfica e tipos de produto.

Exemplo de Pedido

JSON
POST /v1/tax/calculate
Content-Type: application/json
Authorization: Bearer atura_live_1234...

{
  "location": "PT-30", // Madeira
  "currency": "EUR",
  "items": [
    {
      "description": "Serviços de consultoria",
      "unit_price": 100.00,
      "quantity": 5,
      "tax_category": "standard"
    },
    {
      "description": "Livro técnico",
      "unit_price": 25.00,
      "quantity": 2,
      "tax_category": "reduced"
    },
    {
      "description": "Medicamento",
      "unit_price": 15.50,
      "quantity": 1,
      "tax_category": "super_reduced"
    }
  ],
  "customer": {
    "tax_id": "123456789",
    "country": "PT",
    "location": "PT-30"
  }
}

Resposta

JSON
{
  "calculation_id": "calc_abc123def456",
  "location": "PT-30",
  "currency": "EUR",
  "items": [
    {
      "description": "Serviços de consultoria",
      "unit_price": 100.00,
      "quantity": 5,
      "subtotal": 500.00,
      "tax_category": "standard",
      "tax_rate": 22, // Taxa da Madeira
      "tax_amount": 110.00,
      "total": 610.00
    },
    {
      "description": "Livro técnico",
      "unit_price": 25.00,
      "quantity": 2,
      "subtotal": 50.00,
      "tax_category": "reduced",
      "tax_rate": 12, // Taxa reduzida da Madeira
      "tax_amount": 6.00,
      "total": 56.00
    },
    {
      "description": "Medicamento",
      "unit_price": 15.50,
      "quantity": 1,
      "subtotal": 15.50,
      "tax_category": "super_reduced",
      "tax_rate": 5, // Taxa super reduzida da Madeira
      "tax_amount": 0.78,
      "total": 16.28
    }
  ],
  "summary": {
    "subtotal": 565.50,
    "tax_total": 116.78,
    "total": 682.28,
    "tax_breakdown": [
      {
        "rate": 22,
        "taxable_amount": 500.00,
        "tax_amount": 110.00
      },
      {
        "rate": 12,
        "taxable_amount": 50.00,
        "tax_amount": 6.00
      },
      {
        "rate": 5,
        "taxable_amount": 15.50,
        "tax_amount": 0.78
      }
    ]
  },
  "calculated_at": "2025-01-15T14:30:00Z"
}

Taxas de IVA

Portugal tem diferentes taxas de IVA dependendo da localização geográfica e categoria do produto.

CategoriaContinentalAçoresMadeiraExemplos
Normal23%18%22%Serviços, eletrónicos, roupa
Reduzida13%9%12%Restauração, livros, hotéis
Super Reduzida6%4%5%Medicamentos, pão, leite
Isenta0%0%0%Exportações, serviços médicos

Códigos de Localização

Usa os seguintes códigos ISO 3166-2 para especificar a localização:

Portugal Continental

  • PT-01 - Aveiro
  • PT-02 - Beja
  • PT-03 - Braga
  • PT-04 - Bragança
  • PT-05 - Castelo Branco
  • PT-06 - Coimbra
  • PT-07 - Évora
  • PT-08 - Faro
  • PT-09 - Guarda
  • PT-10 - Leiria
  • PT-11 - Lisboa
  • PT-12 - Portalegre
  • PT-13 - Porto
  • PT-14 - Santarém
  • PT-15 - Setúbal
  • PT-16 - Viana do Castelo
  • PT-17 - Vila Real
  • PT-18 - Viseu

Região Autónoma dos Açores

  • PT-20 - Açores

Região Autónoma da Madeira

  • PT-30 - Madeira

Códigos Especiais

  • PT - Portugal (padrão continental)
  • PT-EXPORT - Exportação (0% IVA)
  • PT-INTRA - Intracomunitário

Categorias Fiscais

Especifica a categoria fiscal para aplicar a taxa correta automaticamente:

Categorias Disponíveis

  • standard - Taxa normal (23%/18%/22%)
  • reduced - Taxa reduzida (13%/9%/12%)
  • super_reduced - Taxa super reduzida (6%/4%/5%)
  • exempt - Isento de IVA (0%)
  • reverse_charge - Autoliquidação

Exemplo de Uso

JSON
{
  "description": "Livro de receitas",
  "unit_price": 15.00,
  "quantity": 1,
  "tax_category": "reduced"
  // Taxa será automaticamente 13%/9%/12%
  // dependendo da localização
}

Tratamento de Erros

400 Bad Request

Categoria fiscal ou localização inválida.

JSON
{
  "error": {
    "type": "validation_error",
    "code": "invalid_tax_category",
    "message": "Categoria fiscal 'invalid_category' não é válida",
    "valid_categories": ["standard", "reduced", "super_reduced", "exempt"]
  }
}

422 Unprocessable Entity

Erro de cálculo ou dados inconsistentes.

JSON
{
  "error": {
    "type": "calculation_error",
    "code": "location_mismatch",
    "message": "Localização do cliente não coincide com localização da transação",
    "details": {
      "customer_location": "PT-20",
      "transaction_location": "PT-11"
    }
  }
}

Importante

As taxas de IVA podem mudar com alterações legislativas. A API é automaticamente atualizada para refletir as taxas oficiais em vigor.