Módulo Recaudación

En una frase

Gestión tributaria del ayuntamiento: ordenanzas fiscales, censos (Catastro/DGT/IAE), objetos tributarios, padrones (emisión periódica de recibos), deuda (voluntaria y ejecutiva, recargos, prescripción), planes de pago, cobros y remesas SEPA. Cierra el ciclo del ingreso (fases DR→C), enlazando con los cobros de Tesorería.

Padrón tributario ≠ Padrón de habitantes

El "padrón" de este módulo es la emisión periódica de recibos tributarios (IBI, IVTM, IAE…). No confundir con el Padrón de Habitantes, que es el registro municipal de residentes (módulo aparte).

1. Propósito y alcance

Conceptos de ingreso y ordenanzas fiscales (tarifas y bonificaciones).
Censos: importación de los registros oficiales de Catastro (IBI), DGT (IVTM) e IAE.
Objetos tributarios: el bien gravado persistente (inmueble, vehículo, actividad) con sus titulares e histórico.
Padrones tributarios: emisión masiva y periódica de recibos a partir del censo + ordenanza.
Deuda: el recibo/liquidación con su ciclo (voluntaria → ejecutiva → pagada / anulada / aplazada / prescrita), recargos, intereses y costas.
Planes de pago (fraccionamientos) con domiciliación.
Cobros, remesas SEPA y prescripción automática.

2. Estructura de archivos

app/modules/recaudacion/
├── recaudacion.py        # Blueprint principal (~4560 líneas): conceptos, objetos, tributos, padrones, organismos, dashboard
├── deuda.py              # Deuda, cobros, planes de pago, prescripción (~2539 líneas)
├── padron.py             # Ordenanzas fiscales y reconciliación de censos
├── censos/               # censos.py (importación DGT/Catastro/IAE) + models.py
├── generador_padron.py   # Generación masiva de líneas de padrón desde censo
├── motor_fiscal.py       # Cálculo de cuotas (IBI, IVTM, bonificaciones)
├── prescripcion.py / prescripcion_scheduler.py   # Prescripción (LGT, 4 años) + cron MOS
├── plan_pago_sepa_scheduler.py   # Orquestación SEPA de planes de pago (cron MOS)
├── mos_actions.py        # Registro de acciones MOS
└── models.py             # Modelos del módulo

Blueprints (todos bajo /api/recaudacion): recaudacion_bp, padron_bp, deuda_bp (y el de censos).

3. Modelos de datos

3.1 Conceptos, tributos y ordenanzas

Modelo	Tabla	Propósito
`ConceptoIngreso`	`recaudacion_conceptos_ingreso`	Concepto de ingreso con su comportamiento (PADRON/LIQUIDACION/AUTOLIQUIDACION/SANCION), regla contable y clasificación presupuestaria.
`RecaudacionTributo` / `RecaudacionTributoModalidad`	`recaudacion_tributos` / `…_modalidades`	Tributo (IBI, IVTM, IAE) y sus modalidades (IBI urbano/rústico/BICE…).
`RecaudacionOrdenanza`	`recaudacion_ordenanzas`	Ordenanza fiscal por ejercicio (base de cálculo, BOP, vigencia).
`RecaudacionOrdenanzaTarifa`	`recaudacion_ordenanzas_tarifas`	Tarifa: tipo de gravamen %, cuota fija o por tramos.
`RecaudacionOrdenanzaBonificacion`	`recaudacion_ordenanzas_bonificaciones`	Bonificación (familia numerosa, minusvalía…) con condiciones.

3.2 Censos y objetos tributarios

Modelo	Tabla	Propósito
`RecaudacionCenso`	`recaudacion_censos`	Censo importado (DGT/CATASTRO/IAE), estado CARGADO→OFICIAL→CADUCADO, hash de integridad.
`RecaudacionCensoDGTDetalle`	`…_dgt_detalle`	Vehículo (matrícula, potencia, carga…).
`RecaudacionCensoCatastroDetalle` / `…Titular`	`…_catastro_detalle` / `…_titulares`	Inmueble (referencia catastral, base liquidable) y sus titulares.
`RecaudacionIAEActividad` / `…Local` / `…Matricula`	`recaudacion_iae_*`	Actividad económica, local y matrícula IAE.
`ObjetoTributario`	`recaudacion_objetos_tributarios`	Bien gravado persistente (identificador, importe base, estado, datos JSON).
`ObjetoTributarioTitular`	`…_titulares`	Titular del objeto con porcentaje de participación.
`ObjetoTributarioHistorico`	`…_historico`	Auditoría de cambios (ALTA/BAJA/CAMBIO_VALOR/CAMBIO_TITULAR…).

3.3 Padrones

Modelo	Tabla	Propósito
`Padron`	`recaudacion_padrones`	Cabecera del padrón: ejercicio, periodo, concepto/modalidad, estado (BORRADOR→APROBADO→DEUDAS_GENERADAS→EN_FASE_DE_COBRO→CERRADO), totales.
`PadronLinea`	`recaudacion_padron_lineas`	Una línea por recibo: importes (principal, bonificación, recargo, intereses, costas) y gestión de incidencias (identificación/importe/datos/duplicado).
`RecaudacionTipoFichero` / `…Campo`	`recaudacion_tipos_fichero` / `…_campos`	Configuración de importación (formato, delimitador, mapeo de columnas).
`OrganismoRecaudador` / `EnvioPadron`	`recaudacion_organismos` / `recaudacion_envios_padron`	Organismo (OAR, Tesorería) y registro de envío del padrón.
`RecaudacionHerenciaPadron`	`recaudacion_herencias_padron`	Bonificación/exención permanente por tercero/objeto (se aplica al generar).

3.4 Deuda, cobros y planes de pago

Modelo	Tabla	Propósito
`RecaudacionDeuda`	`recaudacion_deudas`	Modelo central: el recibo/liquidación. Origen (PADRON/LIQUIDACION/…), estado, importes (principal, bonificación, recargo, intereses, costas, pagado, pendiente) y fechas del ciclo.
`RecaudacionDeudaLinea`	`recaudacion_deudas_lineas`	Desglose de la deuda por concepto.
`MovimientoRecaudacion`	`recaudacion_movimientos`	Auditoría de cada acción (GENERACION/COBRO/PASE_EJECUTIVA/RECARGO/ANULACION/EMBARGO/PRESCRIPCION) con su asiento contable.
`RecaudacionAplicacionCobro`	`recaudacion_aplicaciones_cobro`	Cobro recibido (origen TESORERIA/OAR/MANUAL).
`PlanPago` / `PlanPagoPlazo`	`recaudacion_plan_pago` / `…_plazo`	Fraccionamiento de una deuda y sus cuotas (cada plazo enlaza con un `TesoreriaCobro`).

Relación con Tesorería

Cada RecaudacionDeuda se cobra mediante un TesoreriaCobro (módulo Tesorería). Las remesas SEPA de domiciliación se gestionan con TesoreriaRemesa / TesoreriaRemesaLinea.

4. Del censo al cobro

flowchart TD
    O["Ordenanza fiscal<br/>(tarifas + bonificaciones)"] --> G
    C["Censo importado<br/>(Catastro / DGT / IAE)"] -->|oficializar| OF["Censo OFICIAL"]
    OF -->|reconciliar| OT["Objetos tributarios<br/>(+ histórico)"]
    OT --> G["Generar padrón<br/>(motor fiscal: cuota − bonif.)"]
    G --> P["Padrón + líneas"]
    P -->|aprobar + generar deudas| D["Deuda (PENDIENTE)"]
    D -->|cobro voluntario| PG["PAGADA"]
    D -->|impago| EJ["EN_EJECUTIVA<br/>(recargo + intereses)"]
    EJ --> PG
    D -.4 años sin cobro/interrupción.-> PR["PRESCRITA"]

Se importa el censo (Catastro/DGT/IAE) y se oficializa (hash + expediente).
La reconciliación convierte el censo en objetos tributarios persistentes (con histórico de altas/bajas/cambios).
El generador de padrón crea una línea por recibo, calculando la cuota con el motor fiscal (base × tipo / tarifa por tramos) y restando bonificaciones (incluidas las "herencias" permanentes).
Al aprobar el padrón y generar deudas, cada línea se convierte en una RecaudacionDeuda.
La deuda se cobra (voluntaria) o pasa a vía ejecutiva (recargo + intereses); puede fraccionarse en un plan de pago o prescribir.

Motor fiscal

motor_fiscal.py calcula la cuota:

IBI: base_liquidable × tipo_gravamen / 100.
IVTM: clasifica el vehículo (turismo→CV, camión→carga, moto→cc…) y busca la cuota por tramo en la tarifa.
Bonificaciones: se aplican en cascada sobre la cuota íntegra.

5. Endpoints REST

Del orden de 120 endpoints bajo /api/recaudacion. Resumen por área:

Área	Rutas (ejemplos)	Permiso
Conceptos de ingreso	`/conceptos-ingreso` (CRUD + `/activo`)	`recaudacion:conceptos:ver/gestionar`
Ordenanzas fiscales	`/ordenanzas`, `/ordenanzas/tipos`, `/<id>/clonar`	`recaudacion:padrones:gestionar`
Tributos / modalidades	`/tributos`, `/tributos/<id>/modalidades`, `/modalidades`	`recaudacion:tablas:ver/gestionar`
Objetos tributarios	`/objetos`, `/objetos/<id>/titulares`, `/objetos/<id>/historico`	`recaudacion:objetos:ver/gestionar`
Censos	`/censos/{dgt,ibi,iae}/importar`, `/censos/<tipo>/<id>/oficializar`, `/reconciliar`	`recaudacion:padrones:gestionar`
Padrones	`/padrones` (CRUD), `/aprobar`, `/cerrar`, `/generar-desde-censo`, `/enviar`, `/incidencias`	`recaudacion:padron:crear`, `:padrones:ver/gestionar`
Líneas de padrón	`/padrones/<id>/lineas`, `/importar`, `/resolver-incidencia`	`recaudacion:padrones:gestionar`
Deuda	`/deudas` (CRUD), `/<id>/estado`, `/pasar-ejecutiva`, `/anular`, `/padrones/<id>/generar-deudas`	`recaudacion:deudas:ver/gestionar`
Cobros	`/deudas/<id>/crear-cobro`, `/aplicar-cobro`, `/aplicaciones-cobro`	`recaudacion:deudas:gestionar`, `:cobros:gestionar`
Planes de pago	`/deudas/<id>/plan-pago`, `/fraccionar`, `/plazos`	`recaudacion:deudas:ver`
Prescripción	`/prescripcion/preview`, `/prescripcion/ejecutar`, `/prescripcion/deudas/<id>`	`recaudacion:deudas:ver/gestionar`
Resultados SEPA / OAR	`/padrones/<id>/resultado-cobro`, `/envios-padron/<id>/importar-resultados`	`recaudacion:padrones/deudas:gestionar`
Organismos	`/organismos` (CRUD)	`recaudacion:organismos:ver/gestionar`
Configuración import.	`/admin/tipos-fichero`, `/campos`	`recaudacion:padrones:ver/gestionar`
Dashboard	`/dashboard`	`recaudacion:dashboard:ver`

6. Prescripción y orquestación SEPA

Prescripción (LGT, 4 años)

prescripcion.py + prescripcion_scheduler.py (acción MOS recaudacion.prescripcion.ejecutar, cron diario sugerido):

Plazo de 4 años desde la última interrupción (cobro, recargo, pase a ejecutiva, embargo) o la fecha base.
No prescribe si está bloqueada, pagada, sin saldo o con un plan de pago activo.
Al prescribir: estado PRESCRITA, movimiento PRESCRIPCION, reverso presupuestario (anula el derecho), evento MOS y aviso a Contabilidad.
Soporta dry-run y barrido masivo por todas las entidades.

Orquestación SEPA de planes de pago

plan_pago_sepa_scheduler.py (acción MOS recaudacion.plan_pago.sepa_orquestar, cron diario sugerido):

Detecta plazos de plan de pago próximos a vencer (parámetro de antelación, por defecto 5 días) con cobro domiciliado.
Crea una remesa SEPA (TesoreriaRemesa) con los cobros de terceros con IBAN, marca los cobros/plazos como en remesa y emite evento.
Requiere el parámetro recaudacion.plan_pago.sepa_cuenta_id (cuenta ordenante).

Acciones MOS del módulo

Acción	Periodicidad sugerida
`recaudacion.prescripcion.ejecutar`	diaria (p. ej. 04:00).
`recaudacion.plan_pago.sepa_orquestar`	diaria (p. ej. 05:00).
`recaudacion.contabilizar_cobro`	bajo demanda (al conciliar cobros).

7. Permisos y roles

~19 permisos recaudacion:*:

Categoría	Permisos
Conceptos	`recaudacion:conceptos:ver`, `:gestionar`.
Objetos / tipos	`recaudacion:objetos:ver`, `:gestionar`, `:tipos_objeto:ver/gestionar`.
Padrones	`recaudacion:padron:crear`, `:padron:ver`, `:padrones:ver`, `:padrones:gestionar`, `:padrones:generar_deudas`.
Deuda / cobros	`recaudacion:deudas:ver`, `:deudas:gestionar`, `:cobros:gestionar`.
Organismos / tablas	`recaudacion:organismos:ver/gestionar`, `:tablas:ver/gestionar`.
Dashboard	`recaudacion:dashboard:ver`.

Roles base: Jefe de Recaudación (acceso completo) y Supervisor de Recaudación (similar); el Interventor recibe permisos de solo lectura (dashboard, deudas, padrones, conceptos).

8. Integraciones

Tesorería: cada deuda se cobra vía TesoreriaCobro; los planes de pago generan remesas SEPA (TesoreriaRemesa); las compensaciones de Tesorería liquidan deudas.
Presupuesto: el reconocimiento del derecho y el cobro registran las fases DR/C del MovimientoPresupuestario; la prescripción anula el derecho.
Contabilidad: los movimientos generan asientos vía el motor contable (SYS-COB-DER, SYS-DER-BAJA, SYS-REC-APRE…).
Documental: la oficialización de censos y los envíos de padrón crean expedientes/UDs.
Catastro / DGT / AEAT: importación de censos oficiales.

Bonificaciones por herencia

El cálculo distingue las bonificaciones de ordenanza (por tipo) de las herencias (RecaudacionHerenciaPadron, permanentes por contribuyente/objeto). Un fallo histórico en este punto fue corregido; las bonificaciones por herencia se aplican al generar el padrón.