Saltearse al contenido
Keirost Keirost · Docs

Fiscalidad

Impuestos

Keirost soporta configuracion fiscal completa con impuestos por pais y tipo de documento. Cada impuesto define un porcentaje, si es retencion, 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 automaticamente las retenciones de IRPF en facturas de venta y compra. El sistema soporta distintos tipos de retenciones segun la legislacion applicable.

Configuracion por defecto

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

  • Tipo de retencion: general, reducida, minima
  • Porcentaje base: segun tablas de la Agencia Tributaria
  • Aplicacion automatica: segun tipo de partner (autonomo, empresa, particular)

Tabla de porcentajes habituales (España)

TipoBase imponibleRetencion
Generalcualquier importe19%
Reducidahasta 24.000 euros15%
Minimahasta 12.000 euros7%

Calculo en facturas

Cuando se genera una factura, el motor fiscal:

  1. Detecta el tipo de documento y el partner asociado
  2. Aplica la retencion del partner si esta configurada (o la general)
  3. Calcula la base imponible sin la retencion
  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 linea de retencion como un concepto adicional en el documento

Ejemplo de calculo 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 operacion.

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

Configuracion 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
}
CampoDescripcion
fiscal_countryPais de la normativa fiscal
fiscal_year_start_monthMes de inicio del ano fiscal (1=enero)
default_tax_type_idImpuesto por defecto en nuevos documentos
default_retention_type_idRetencion por defecto
auto_apply_retentionAplicar retencion automaticamente en facturas
fiscal_sequence_prefixPrefijo en numeracion fiscal (ej: “F” para F-2026-0001)
round_tax_linesDecimales en calculo de impuestos (normalmente 2)
require_document_lockBloquear facturas al asentar

Lock de facturas

Cuando require_document_lock esta activo, toda factura o documento financiero se bloquea automaticamente al asentarse.

Estados del documento

EstadoDescripcion
draftBorrador, editable sin restricciones
sentEnviado al cliente/proveedor
lockedAsentado, no editable. Solo admins pueden modificar
cancelledAnulado, no editable

Desbloqueo

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

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


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

Revertir asiento

Tambien 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 seccion de series documentales en la documentacion de almacenes para la configuracion de numeracion fiscal.

Periodos

Los periodos fiscales delimitian los ciclos de facturacion 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
}
CampoDescripcion
statusopen (activo), closed (cerrado), archived
lockedSi esta bloqueado, no se pueden crear documentos en el

Resumen de endpoints

MetodoRutaDescripcion
GET/api/fiscal/tax-typesListar tipos de impuesto
POST/api/fiscal/tax-typesCrear tipo de impuesto
PATCH/api/fiscal/tax-types/:idActualizar tipo de impuesto
DELETE/api/fiscal/tax-types/:idEliminar tipo de impuesto
GET/api/fiscal/tax-types/:idObtener tipo de impuesto
GET/api/fiscal/fiscal-groupsListar grupos fiscales
POST/api/fiscal/fiscal-groupsCrear grupo fiscal
GET/api/fiscal/configObtener config fiscal
PATCH/api/fiscal/configActualizar config fiscal
POST/api/fiscal/unlock/:type/:idDesbloquear documento
POST/api/fiscal/revert/:type/:idRevertir documento
GET/api/periodsListar periodos
POST/api/periodsCrear periodo