Factuarea API
Tax rates

Retrieve the tax catalog

Return, in a single document, the Spanish tax knowledge you need to build a compliant invoicing form: indirect tax regimes (IVA, IGIC, IPSI) with their legal rates and their VeriFactu L1 code, header-level operation regimes with the legal wording each one requires, exemption causes with their AEAT code, legal wording and article of the Spanish VAT Act, the system IRPF withholding rates and the closed matrix of legal VAT/equivalence-surcharge pairs. It replaces the hardcoded table every integration ends up maintaining by hand.

The catalog carries no data of the authenticated company: two different companies receive byte-identical bodies for the same language, and retention_rates never includes the custom taxes a company creates through POST /v1/taxes. Withholding rates are published in POSITIVE, so apply them as a deduction from the taxable base.

This is the catalog of what the platform supports, NOT an exhaustive normative list of every regime, exemption or withholding rate Spanish law defines. Use it to know what you can send to this API; do not read it as tax advice or as a substitute for the legislation.

Every entry carries its label (and, in the two normative blocks, its description) in Spanish, English and Catalan at once. Accept-Language only picks the language reported in primary_language; it never filters the payload, so one cached document is enough to render a multilingual selector. The response is cacheable: it ships ETag and a public Cache-Control, and sending the validator back in If-None-Match returns 304 with no body. Two languages produce two different ETags, because the negotiated language travels inside the body.

GET
/tax-catalog

Authorization

AuthorizationBearer <token>

In: header

Header Parameters

Factuarea-Version?string

Pin the API version (YYYY-MM-DD, Stripe-style date versioning) for this request; omit to use the key's pinned version, or the latest if none. Unsupported version → 400 unsupported_api_version; malformed → 400 parameter_invalid_format. The effective version is echoed in the Factuarea-Version response header. See the Versioning guide.

Formatdate
X-Active-Profile?string

Operate on behalf of a child company (gestoría master key): pass its public id (UUID v7) and the request runs against that child's data without changing the key's scope, tier or environment (omit to use the key's own company). Invalid UUID → 400 parameter_invalid_uuid; unknown or non-owned id → 404 profile_not_found. See the Acting on behalf guide.

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

import { Factuarea } from "@factuarea/sdk";const factuarea = new Factuarea({ apiKey: process.env.FACTUAREA_API_KEY! });const result = await factuarea.taxCatalog.show();
{
  "data": {
    "primary_language": "es",
    "indirect_tax_regimes": [
      {
        "code": "iva",
        "aeat_code": "01",
        "valid_rates": [
          0,
          4,
          10,
          21
        ],
        "general_rate": 21,
        "aeat_zones": [
          "peninsula"
        ],
        "label": {
          "es": "IVA — Impuesto sobre el Valor Añadido (Península y Baleares)",
          "en": "IVA — Spanish value added tax (mainland Spain and the Balearic Islands)",
          "ca": "IVA — Impost sobre el Valor Afegit (Península i Balears)"
        }
      },
      {
        "code": "igic",
        "aeat_code": "03",
        "valid_rates": [
          0,
          3,
          5,
          7,
          9.5,
          15,
          20
        ],
        "general_rate": 7,
        "aeat_zones": [
          "canarias"
        ],
        "label": {
          "es": "IGIC — Impuesto General Indirecto Canario (Canarias)",
          "en": "IGIC — Canary Islands general indirect tax (Canary Islands)",
          "ca": "IGIC — Impost General Indirecte Canari (Canàries)"
        }
      }
    ],
    "operation_regimes": [
      {
        "code": "general",
        "legal_mention": null,
        "requires_zero_vat": false,
        "label": {
          "es": "Régimen general",
          "en": "General regime",
          "ca": "Règim general"
        },
        "description": {
          "es": "Operación interior ordinaria: se repercute IVA al tipo que corresponda y la factura no necesita ninguna mención legal adicional.",
          "en": "Ordinary domestic transaction: VAT is charged at the applicable rate and the invoice needs no additional legal wording.",
          "ca": "Operació interior ordinària: es repercuteix IVA al tipus que correspongui i la factura no necessita cap menció legal addicional."
        }
      },
      {
        "code": "intracomunitaria",
        "legal_mention": "Operación intracomunitaria sujeta y exenta - Art. 25 LIVA",
        "requires_zero_vat": true,
        "label": {
          "es": "Entrega intracomunitaria",
          "en": "Intra-Community supply",
          "ca": "Lliurament intracomunitari"
        },
        "description": {
          "es": "Entrega a un cliente de otro Estado miembro de la Unión Europea con NIF-IVA válido: la operación está sujeta y exenta, se factura sin cuota de IVA y la factura debe recoger la mención del artículo 25 de la Ley 37/1992.",
          "en": "Supply to a customer in another EU Member State holding a valid VAT number: the transaction is taxable but exempt, it is invoiced with no VAT amount, and the invoice must carry the reference to article 25 of the Spanish VAT Act (Ley 37/1992).",
          "ca": "Lliurament a un client d'un altre Estat membre de la Unió Europea amb NIF-IVA vàlid: l'operació està subjecta i exempta, es factura sense quota d'IVA i la factura ha de recollir la menció de l'article 25 de la Llei 37/1992."
        }
      }
    ],
    "exemption_causes": [
      {
        "code": "exenta_art_25",
        "calificacion_operacion": null,
        "causa_exencion": "E5",
        "clave_regimen": null,
        "legal_mention": "Operación intracomunitaria sujeta y exenta conforme al artículo 25 de la Ley 37/1992.",
        "article": "Art. 25 LIVA",
        "line_level": true,
        "label": {
          "es": "Exenta — artículo 25 LIVA (entrega intracomunitaria)",
          "en": "Exempt — article 25 LIVA (intra-Community supply)",
          "ca": "Exempta — article 25 LIVA (lliurament intracomunitari)"
        },
        "description": {
          "es": "Entrega de bienes con destino a otro Estado miembro, sujeta y exenta por el artículo 25 de la Ley 37/1992. Se factura sin repercutir cuota y ante la AEAT se declara con la causa de exención E5.",
          "en": "Supply of goods dispatched to another EU Member State, taxable but exempt under article 25 of the Spanish VAT Act (Ley 37/1992). It is invoiced with no VAT amount and reported to AEAT with exemption reason E5.",
          "ca": "Lliurament de béns amb destinació a un altre Estat membre, subjecte i exempt per l'article 25 de la Llei 37/1992. Es factura sense repercutir quota i davant l'AEAT es declara amb la causa d'exempció E5."
        }
      },
      {
        "code": "regimen_recargo_equivalencia_art_154",
        "calificacion_operacion": null,
        "causa_exencion": null,
        "clave_regimen": "51",
        "legal_mention": "Operación acogida al régimen especial del recargo de equivalencia (artículo 154 de la Ley 37/1992).",
        "article": "Art. 154 LIVA",
        "line_level": false,
        "label": {
          "es": "Régimen especial del recargo de equivalencia — artículo 154 LIVA",
          "en": "Recargo de equivalencia regime — article 154 LIVA",
          "ca": "Règim especial del recàrrec d'equivalència — article 154 LIVA"
        },
        "description": {
          "es": "Operación acogida al régimen especial del recargo de equivalencia (artículo 154 de la Ley 37/1992), obligatorio para el comercio minorista: el emisor repercute al minorista un recargo además del IVA. Ante la AEAT se declara con la clave de régimen 51.",
          "en": "Transaction under the \"recargo de equivalencia\" regime (article 154 of the Spanish VAT Act, Ley 37/1992), compulsory for retailers: the issuer charges the retailer a surcharge on top of the VAT. It is reported to AEAT with special regime key 51.",
          "ca": "Operació acollida al règim especial del recàrrec d'equivalència (article 154 de la Llei 37/1992), obligatori per al comerç minorista: l'emissor repercuteix al minorista un recàrrec a més de l'IVA. Davant l'AEAT es declara amb la clau de règim 51."
        }
      }
    ],
    "retention_rates": [
      {
        "code": "IRPF_15",
        "rate": 15,
        "applies_to": "sale",
        "label": {
          "es": "IRPF del 15 % — actividades profesionales (el tipo más habitual)",
          "en": "15% IRPF — professional activities (the most common rate)",
          "ca": "IRPF del 15 % — activitats professionals (el tipus més habitual)"
        }
      },
      {
        "code": "IRPF_P_15",
        "rate": 15,
        "applies_to": "purchase",
        "label": {
          "es": "IRPF del 15 % practicado al proveedor — actividades profesionales",
          "en": "15% IRPF withheld from the supplier — professional activities",
          "ca": "IRPF del 15 % practicat al proveïdor — activitats professionals"
        }
      }
    ],
    "equivalence_surcharge_pairs": [
      {
        "vat": 21,
        "surcharge": 5.2,
        "label": {
          "es": "IVA del 21 % con recargo de equivalencia del 5,2 %",
          "en": "21% VAT with a 5.2% recargo de equivalencia",
          "ca": "IVA del 21 % amb recàrrec d'equivalència del 5,2 %"
        }
      },
      {
        "vat": 0,
        "surcharge": 0,
        "label": {
          "es": "IVA del 0 % sin recargo de equivalencia",
          "en": "0% VAT with no recargo de equivalencia",
          "ca": "IVA del 0 % sense recàrrec d'equivalència"
        }
      }
    ]
  }
}
Empty

{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "No se ha proporcionado una API key válida en el header Authorization.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#missing_api_key",
    "request_id": "req_01HKQS5N8VR7QXJ9K3T6BWPMZA"
  }
}

{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "Esta API key no tiene el scope requerido para esta operación.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#insufficient_scope",
    "request_id": "req_01HKQS5NBC3P8M1KX4V7SLNHQD"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Has excedido el rate limit de 60 peticiones por minuto. Reintenta tras 30 segundos.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#rate_limit_exceeded",
    "request_id": "req_01HKQS5NKW1C6W9T4G5H0JBZVL"
  }
}

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Ha ocurrido un error inesperado. Si persiste, contacta con soporte adjuntando el request_id.",
    "param": null,
    "doc_url": "https://docs.factuarea.com/guides/errors#internal_error",
    "request_id": "req_01HKQS5NLX2D7X0U5H6J1KCAWM"
  }
}
POST

Unarchive a series

GET

List active taxes