Fiscalidad

Impuestos

Keirost soporta configuración fiscal completa con impuestos por pais y tipo de documento. Cada impuesto define un porcentaje, si es retención, y si aplica recargo de equivalencia.

Modelo de datos

interface TaxType {
  id: string;
  name: string;          // "IVA 21%", "IRPF 15%", "Recargo 0.5%"
  rate: number;          // 21.0 = 21%
  is_retention: boolean; // true para IRPF, false para IVA
  is_recargo: boolean;   // true para recargo de equivalencia
  country: string;       // "ES", "PT", etc.
  active: boolean;
  created_at: string;
}

Endpoints

Listar tipos de impuesto

GET /api/fiscal/tax-types
Authorization: Bearer <token>

Respuesta:

{
  "data": [
    {
      "id": "tt_iva21",
      "name": "IVA 21%",
      "rate": 21.0,
      "is_retention": false,
      "is_recargo": false,
      "country": "ES",
      "active": true
    },
    {
      "id": "tt_irpf19",
      "name": "IRPF 19%",
      "rate": 19.0,
      "is_retention": true,
      "is_recargo": false,
      "country": "ES",
      "active": true
    }
  ]
}

Crear tipo de impuesto

POST /api/fiscal/tax-types
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "IVA 10%",
  "rate": 10.0,
  "is_retention": false,
  "is_recargo": false,
  "country": "ES"
}

Actualizar tipo de impuesto

PATCH /api/fiscal/tax-types/:id
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "IVA 10% reducido",
  "rate": 10.0
}

---

Retenciones IRPF

Keirost calcula automáticamente las retenciones de IRPF en facturas de venta y compra. El sistema soporta distintos tipos de retenciones según la legislación applicable.

Configuración por defecto

Las retenciones por defecto se configuran en Ajustes > Fiscal > Retenciones. Puedes definir:

• Tipo de retención: general, reducida, mínima
• Porcentaje base: según tablas de la Agencia Tributaria
• Aplicación automática: según tipo de partner (autonomo, empresa, particular)

Tabla de porcentajes habituales (España)

Tipo	Base imponible	Retención
General	cualquier importe	19%
Reducida	hasta 24.000 euros	15%
Mínima	hasta 12.000 euros	7%

Cálculo en facturas

Cuando se genera una factura, el motor fiscal:

1. Detecta el tipo de documento y el partner asociado
2. Aplica la retención del partner si esta configurada (o la general)
3. Calcula la base imponible sin la retención
4. Calcula el IRPF como porcentaje de la base imponible
5. Resta el IRPF del total (el emisor retiene y luego lo ingresa a Hacienda)
6. Registra la línea de retención como un concepto adicional en el documento

Ejemplo de cálculo en una factura de 1.000 EUR + 21% IVA:

Base imponible:          1.000,00 EUR
IRPF 19% (retencion):     -190,00 EUR
IVA 21%:                  +210,00 EUR
-------------------------------
Total a cobrar:         1.020,00 EUR
Total a ingresar AEAT:    20,00 EUR  (210 - 190)

---

Grupos fiscales

Los grupos fiscales permiten organizar impuestos relacionados y configurar politicas fiscales por region o tipo de operación.

Modelo

interface FiscalGroup {
  id: string;
  name: string;            // "Espana peninsula", "Canarias", "Portugal"
  country: string;
  default_tax_type_id: string;
  tax_types: string[];     // IDs de impuestos aplicables
  active: boolean;
}

Uso en documentos

Un grupo fiscal se asigna al partner o a la empresa. Al crear un documento:

• Se usa el grupo fiscal del partner (si existe)
• Si no, se usa el grupo fiscal de la empresa
• Los impuestos disponibles se filtran por el grupo

---

Configuración fiscal de empresa

Endpoint

GET /api/fiscal/config
PATCH /api/fiscal/config

Campos configurables

{
  "fiscal_country": "ES",
  "fiscal_year_start_month": 1,
  "default_tax_type_id": "tt_iva21",
  "default_retention_type_id": "tt_irpf19",
  "auto_apply_retention": true,
  "fiscal_sequence_prefix": "F",
  "round_tax_lines": 2,
  "require_document_lock": true
}

Campo	Descripción
fiscal_country	Pais de la normativa fiscal
fiscal_year_start_month	Mes de inicio del ano fiscal (1=enero)
default_tax_type_id	Impuesto por defecto en nuevos documentos
default_retention_type_id	Retención por defecto
auto_apply_retention	Aplicar retención automáticamente en facturas
fiscal_sequence_prefix	Prefijo en numeración fiscal (ej: “F” para F-2026-0001)
round_tax_lines	Decimales en cálculo de impuestos (normalmente 2)
require_document_lock	Bloquear facturas al asentar

---

Lock de facturas

Cuando require_document_lock esta activo, toda factura o documento financiero se bloquea automáticamente al asentarse.

Estados del documento

Estado	Descripción
draft	Borrador, editable sin restricciones
sent	Enviado al cliente/proveedor
locked	Asentado, no editable. Solo admins pueden modificar
cancelled	Anulado, no editable

Desbloqueo

Solo usuarios con rol admin pueden desbloquear un documento bloqueado. El desbloqueo deja un registro en el audit log con justificación obligatoria.

POST /api/fiscal/unlock/:documentType/:documentId
Authorization: Bearer <token>
Content-Type: application/json

{
  "reason": "Correccion de error en base imponible"
}

Revertir asiento

También se puede revertir completamente un asiento (crear un asiento inverso):

POST /api/fiscal/revert/:documentType/:documentId

Esto genera un nuevo documento del mismo tipo con importe negativo que compensa el original.

---

Series y periodos fiscales

Series documentales

Consulta la sección de series documentales en la documentación de almacenes para la configuración de numeración fiscal.

Periodos

Los periodos fiscales delimitian los ciclos de facturación y son necesarios para el cierre contable.

GET  /api/periods
POST /api/periods

Un periodo tiene:

{
  "id": "per_2026Q1",
  "name": "Q1 2026",
  "fiscal_year": 2026,
  "quarter": 1,
  "date_from": "2026-01-01",
  "date_to": "2026-03-31",
  "status": "open",
  "locked": false
}

Campo	Descripción
status	open (activo), closed (cerrado), archived
locked	Si esta bloqueado, no se pueden crear documentos en el

---

Resumen de endpoints

Método	Ruta	Descripción
GET	/api/fiscal/tax-types	Listar tipos de impuesto
POST	/api/fiscal/tax-types	Crear tipo de impuesto
PATCH	/api/fiscal/tax-types/:id	Actualizar tipo de impuesto
DELETE	/api/fiscal/tax-types/:id	Eliminar tipo de impuesto
GET	/api/fiscal/tax-types/:id	Obtener tipo de impuesto
GET	/api/fiscal/fiscal-groups	Listar grupos fiscales
POST	/api/fiscal/fiscal-groups	Crear grupo fiscal
GET	/api/fiscal/config	Obtener config fiscal
PATCH	/api/fiscal/config	Actualizar config fiscal
POST	/api/fiscal/unlock/:type/:id	Desbloquear documento
POST	/api/fiscal/revert/:type/:id	Revertir documento
GET	/api/periods	Listar periodos
POST	/api/periods	Crear periodo