⚙️ Fiscal Engine v0.3 — 17/08/2026

Microservicios de cálculo fiscal para LincePro

Estrategia de casillas: Todos los modelos exponen totales de cálculo con nombres semánticos. El objeto casillas puede contener claves con numeración oficial AEAT (cuando el mapeo está cerrado) o claves semánticas (cuando el mapeo está intencionalmente diferido). Consulta la nota de cada endpoint para saber cuál aplica.
Autenticación requerida: Todos los endpoints de cálculo (POST) requieren la cabecera Authorization: Bearer <FISCALENGINE_API_TOKEN>. Las rutas públicas (GET /health y esta landing) no requieren token. Las llamadas sin token o con token incorrecto reciben 401 Unauthorized. Sin token configurado en el servidor, el servicio responde 503 Service Unavailable.
Solo cálculo — sin persistencia Sin envío a AEAT Sin generación de TXT Sin UI para usuario final Autenticación Bearer
GET /fiscal-engine/health Implementado Health

Comprueba que el servicio está operativo. Utilizado por el proxy de producción como health check de inicio. No requiere autenticación.

Entrada

  • Sin cuerpo ni parámetros

Salida

  • { "status": "ok" }
POST /fiscal-engine/modelo-111/calcular Implementado Bearer Modelo 111

Retenciones e ingresos a cuenta — rendimientos del trabajo, actividades profesionales, premios, ganancias forestales y derechos de imagen. Agrega por tipo de percepción y cuenta perceptores únicos por tipo.

Entrada

  • ejercicio — entero
  • periodo — string (p.ej. "T1")
  • percepciones[] — mín. 1 ítem
  • tipo: trabajo | profesional | premio | forestal | imagen
  • perceptorNif o perceptorId (mín. uno)
  • baseRetencion, cuotaRetencion ≥ 0

Salida

  • resumen por tipo: perceptores, base, retenciones
  • totalPerceptores, totalBaseRetencion, totalRetenciones
  • casillas — claves semánticas por tipo
  • avisos[]
trabajoPerceptores trabajoBase trabajoRetenciones profesionalPerceptores profesionalBase profesionalRetenciones premioPerceptores premioBase premioRetenciones forestalPerceptores forestalBase forestalRetenciones imagenPerceptores imagenBase imagenRetenciones totalRetenciones

Claves semánticas; numeración oficial pendiente.

POST /fiscal-engine/modelo-115/calcular Implementado Bearer Modelo 115

Retenciones e ingresos a cuenta sobre arrendamientos de inmuebles urbanos. Agrega por proveedor (NIF o ID interno) y calcula totales del período.

Entrada

  • ejercicio — entero
  • periodo — string (p.ej. "T1")
  • arrendamientos[] — mín. 1 ítem
  • proveedorNif o proveedorId (mín. uno)
  • baseRetencion, cuotaRetencion ≥ 0

Salida

  • totalPerceptores
  • totalBaseRetencion
  • totalRetenciones
  • casillas
  • avisos[]
casillaNumeroPerceptores casillaBaseRetenciones casillaRetencionesIngresosCuenta

Casillas funcionales del modelo 115.

POST /fiscal-engine/modelo-130/v2/calcular Implementado Bearer Modelo 130 v2

Pago fraccionado IRPF — nueva generación. Entrada basada en movimientos contables etiquetados por actividad. Soporte multi-actividad, tipos diferenciados para Ceuta/Melilla (8%/0.8%), bloque agrícola-ganadero y coherencia entre trimestres declarados.

Entrada

  • ejercicio — entero
  • periodo — T1 | T2 | T3 | T4
  • modalidadEstimacion — normal | simplificada
  • tipoDeclaracion — ordinaria | complementaria
  • actividadesFiscales[] — id, bloqueFiscal, ceutaMelilla
  • movimientos[] — idOrigen, origen, actividadId; para gastos/ingresos: categoriaFiscal, fechaFiscal; para amortizacion: importeAmortizacionAnual, fechaInicioComputo[, fechaFinComputo]
  • declaracionesAnteriores[] — T1–T3 del mismo ejercicio
  • ajustes — minoración ejercicio anterior, vivienda habitual, % voluntario

Salida

  • casillas 01–19 (numeración oficial AEAT)
  • rendimientoNetoAcumulado, basePagoFraccionado
  • pagosFraccionadosAnterioresCalculado
  • saldoNegativoResidual
  • importeResultado = casilla 19
  • totalesPorActividad[] — desglose por actividad fiscal
  • totalesPorBloque — general / agrícola
  • reglasAplicadas[]
  • advertencias[], erroresCoherencia[]
"01" "02" "03" "04" "05" "06" "07" "08" "09" "10" "11" "12" "13" "14" "15" "16" "17" "18" "19"

Contrato completo: docs/modelo-130-v2-contrato.md. Casillas oficiales 01–19 mapeadas.

POST /fiscal-engine/modelo-303/calcular Implementado Bearer Modelo 303

Autoliquidación del IVA — régimen general básico, primera versión. Agrega IVA devengado y deducible, calcula el resultado de la liquidación y determina importe a ingresar o a compensar.

Entrada

  • ejercicio — entero
  • periodo — 1T | 2T | 3T | 4T | 01–12
  • ivaDevengado[] — tipoIva, baseImponible, cuotaIva
  • ivaDeducible[] — baseImponible, cuotaIva; tipoIva y tipoOperacion opcionales
  • compensacionPeriodosAnteriores — opc., def. 0

Salida

  • totalBaseDevengado, totalCuotaDevengado
  • totalBaseDeducible, totalCuotaDeducible
  • resultadoAntesCompensacion, resultadoLiquidacion
  • importeIngresar / importeCompensar
  • resumenPorTipoIvaDevengado[], resumenPorTipoIvaDeducible[]
  • casillas, avisos[]
totalBaseDevengado totalCuotaDevengado totalBaseDeducible totalCuotaDeducible compensacionPeriodosAnteriores resultadoAntesCompensacion resultadoLiquidacion importeIngresar importeCompensar

Claves semánticas; numeración oficial pendiente.