Financieros y Reportes API

Propósito

Endpoints que cubren la operación financiera (bancos, conciliación, créditos, anticipos, libro banco) y la generación de reportes (estados financieros, análisis, exportes PDF). Estos endpoints son consumidos principalmente por las vistas de reportería ejecutiva y por la conciliación bancaria mensual.

Mapa de Familias

Familia	Prefijo	Router	Servicio responsable
Bancos	/api/financieros/bancos	routes/financieros/bancos.ts	FinanzasService
Movimientos	/api/financieros/movimientos	routes/financieros/movimientos.ts	FinanzasService
Categorías de movimiento	/api/financieros/categorias-movimiento	routes/financieros/categorias-movimiento.ts	FinanzasService
Libro banco	/api/financieros/libro-banco	routes/financieros/libro-banco.ts	FinanzasService
Conciliación	/api/financieros/conciliacion	routes/financieros/conciliacion.ts	FinanzasService
Resoluciones de conciliación	/api/financieros/resoluciones-conciliacion	routes/financieros/resoluciones-conciliacion.ts	FinanzasService
Préstamos	/api/financieros/prestamos	routes/financieros/prestamos.ts	FinanzasService
Anticipos	/api/financieros/anticipos	routes/financieros/anticipos.ts	FinanzasService
Reportes	/api/reportes	routes/reportes/index.ts	ReportesService
Generación PDF	/api/generate-pdf	routes/internal/...	PdfService

Bancos y Movimientos

Método	Ruta	Uso
GET	/api/financieros/bancos	Lista cuentas bancarias del tenant.
POST	/api/financieros/bancos	Crea cuenta bancaria.
GET	/api/financieros/movimientos	Lista movimientos por banco y periodo.
POST	/api/financieros/movimientos	Registra movimiento manual.
POST	/api/financieros/movimientos/importar	Importa cartola bancaria.
GET	/api/financieros/categorias-movimiento	Lista categorías para clasificar movimientos.

Conciliación Bancaria

Método	Ruta	Uso
GET	/api/financieros/conciliacion/:banco_id/:periodo	Estado de conciliación del banco en el periodo.
POST	/api/financieros/conciliacion/match	Empareja movimiento del banco con asiento contable.
POST	/api/financieros/resoluciones-conciliacion	Crea resolución para una partida no conciliada.

Estado de conciliación

curl -X GET "http://localhost:8000/api/financieros/conciliacion/1/2026-05" \
  -b cookies.txt

Response 200

{
  "success": true,
  "data": {
    "banco_id": 1,
    "periodo": "2026-05",
    "movimientos_total": 124,
    "movimientos_conciliados": 119,
    "movimientos_pendientes": 5,
    "diferencia_saldo": 0
  }
}

Libro Banco

Método	Ruta	Uso
GET	/api/financieros/libro-banco/:banco_id	Libro banco por cuenta.
GET	/api/financieros/libro-banco/:banco_id/:periodo	Libro banco del periodo.

Créditos y Anticipos

Método	Ruta	Uso
GET	/api/financieros/prestamos	Lista créditos bancarios con tablas de amortización.
POST	/api/financieros/prestamos	Registra nuevo crédito y calcula tabla.
POST	/api/financieros/prestamos/:id/pagar-cuota	Registra pago de cuota (genera asiento).
GET	/api/financieros/anticipos	Lista anticipos a empleados o proveedores.

Reportes

Endpoints de reportería que producen vistas consolidadas: estados financieros, análisis de razones, comparativos periodo a periodo.

Método	Ruta	Uso
GET	/api/reportes/balance-general	Balance general al cierre del periodo.
GET	/api/reportes/estado-resultado	Estado de resultado del periodo.
GET	/api/reportes/flujo-efectivo	Estado de flujo de efectivo (NIC 7).
GET	/api/reportes/razones	Razones financieras (liquidez, endeudamiento, rentabilidad).

Generación de PDF

Método	Ruta	Uso
POST	/api/generate-pdf	Genera PDF a partir de un template y payload. Usado por servicios que entregan documentos (contratos, liquidaciones, finiquitos).

El endpoint /api/generate-pdf se invoca internamente desde el Orchestrator (no desde Sevastopol directamente); los endpoints públicos de descarga (/api/contracts/:id/download, etc.) lo orquestan.