Factuarea API
Tipos impositivos

Consulta el catálogo fiscal

Devuelve, en un solo documento, el conocimiento fiscal español que necesitas para construir un formulario de facturación conforme: regímenes de imposición indirecta (IVA, IGIC, IPSI) con sus tipos legales y su código L1 de VeriFactu, regímenes de operación a nivel de cabecera con la mención legal que exige cada uno, causas de exención con su código AEAT, su mención legal y su artículo de la Ley del IVA, los tipos de retención de IRPF del sistema y la matriz cerrada de pares legales de IVA/recargo de equivalencia. Sustituye a la tabla hardcodeada que toda integración acaba manteniendo a mano.

El catálogo no lleva ningún dato de la empresa autenticada: dos empresas distintas reciben cuerpos idénticos byte a byte para el mismo idioma, y retention_rates nunca incluye los impuestos personalizados que una empresa crea con POST /v1/taxes. Los tipos de retención se publican en POSITIVO, así que aplícalos como una deducción sobre la base imponible.

Este es el catálogo de lo que la plataforma admite, NO una lista normativa exhaustiva de todos los regímenes, exenciones o tipos de retención que define la ley española. Úsalo para saber qué puedes enviar a esta API; no lo leas como asesoramiento fiscal ni como sustituto de la legislación.

Cada entrada lleva su label (y, en los dos bloques normativos, su description) en español, inglés y catalán a la vez. Accept-Language solo elige el idioma que se informa en primary_language; nunca filtra el payload, así que con un documento cacheado basta para pintar un selector multiidioma. La respuesta es cacheable: lleva ETag y un Cache-Control público, y devolver el validador en If-None-Match responde un 304 sin cuerpo. Dos idiomas producen dos ETag distintos, porque el idioma negociado viaja dentro del cuerpo.

GET
/tax-catalog
AuthorizationBearer <token>

En: header

Parámetros de cabecera

Factuarea-Version?string

Fija la versión de la API (YYYY-MM-DD, versionado por fecha estilo Stripe) para esta petición; omítelo para usar la versión fijada de la clave, o la última si no hay ninguna. Versión no soportada → 400 unsupported_api_version; malformada → 400 parameter_invalid_format. La versión efectiva se refleja en la cabecera de respuesta Factuarea-Version. Consulta la guía de Versioning.

Formatodate
X-Active-Profile?string

Opera en nombre de una empresa hija (API key maestra de gestoría): pasa su id público (UUID v7) y la petición se ejecuta contra los datos de esa hija sin cambiar el scope, el tier ni el environment de la clave (omítelo para usar la propia empresa de la clave). UUID inválido → 400 parameter_invalid_uuid; id desconocido o no propio → 404 profile_not_found. Consulta la guía de Acting on behalf.

Formatouuid

Cuerpo de la respuesta

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"
        }
      }
    ]
  }
}
Vacío

{
  "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"
  }
}